newtype: initial commit

4 files changed, 444 insertions, 0 deletions

diff --git a/doc/Pipfile b/doc/Pipfile
new file mode 100644
index 0000000..92d66ea
--- /dev/null
+++ b/doc/Pipfile
@@ -0,0 +1,14 @@
+[[source]]
+name = "pypi"
+url = "https://pypi.org/simple"
+verify_ssl = true
+
+[dev-packages]
+
+[packages]
+sphinx = "*"
+breathe = "*"
+sphinx-better-theme = "*"
+
+[requires]
+python_version = "3"
diff --git a/doc/Pipfile.lock b/doc/Pipfile.lock
new file mode 100644
index 0000000..fca92c1
--- /dev/null
+++ b/doc/Pipfile.lock
@@ -0,0 +1,232 @@
+{
+    "_meta": {
+        "hash": {
+            "sha256": "867ebbc446f1c3064607a63aa5b4a7f0b53e2878ee60ccb51b6d33e320622f25"
+        },
+        "pipfile-spec": 6,
+        "requires": {
+            "python_version": "3"
+        },
+        "sources": [
+            {
+                "name": "pypi",
+                "url": "https://pypi.org/simple",
+                "verify_ssl": true
+            }
+        ]
+    },
+    "default": {
+        "alabaster": {
+            "hashes": [
+                "sha256:446438bdcca0e05bd45ea2de1668c1d9b032e1a9154c2c259092d77031ddd359",
+                "sha256:a661d72d58e6ea8a57f7a86e37d86716863ee5e92788398526d58b26a4e4dc02"
+            ],
+            "version": "==0.7.12"
+        },
+        "babel": {
+            "hashes": [
+                "sha256:af92e6106cb7c55286b25b38ad7695f8b4efb36a90ba483d7f7a6628c46158ab",
+                "sha256:e86135ae101e31e2c8ec20a4e0c5220f4eed12487d5cf3f78be7e98d3a57fc28"
+            ],
+            "version": "==2.7.0"
+        },
+        "breathe": {
+            "hashes": [
+                "sha256:178848e4088faf8c2c60f000379fcabfb3411b260e0fbddc08fb57e0e5caea08",
+                "sha256:94b4267355571f729038eaad076dab9a851016c5d8b9ba156e2e2360dbbf930d"
+            ],
+            "index": "pypi",
+            "version": "==4.14.0"
+        },
+        "certifi": {
+            "hashes": [
+                "sha256:017c25db2a153ce562900032d5bc68e9f191e44e9a0f762f373977de9df1fbb3",
+                "sha256:25b64c7da4cd7479594d035c08c2d809eb4aab3a26e5a990ea98cc450c320f1f"
+            ],
+            "version": "==2019.11.28"
+        },
+        "chardet": {
+            "hashes": [
+                "sha256:84ab92ed1c4d4f16916e05906b6b75a6c0fb5db821cc65e70cbd64a3e2a5eaae",
+                "sha256:fc323ffcaeaed0e0a02bf4d117757b98aed530d9ed4531e3e15460124c106691"
+            ],
+            "version": "==3.0.4"
+        },
+        "docutils": {
+            "hashes": [
+                "sha256:6c4f696463b79f1fb8ba0c594b63840ebd41f059e92b31957c46b74a4599b6d0",
+                "sha256:9e4d7ecfc600058e07ba661411a2b7de2fd0fafa17d1a7f7361cd47b1175c827",
+                "sha256:a2aeea129088da402665e92e0b25b04b073c04b2dce4ab65caaa38b7ce2e1a99"
+            ],
+            "version": "==0.15.2"
+        },
+        "idna": {
+            "hashes": [
+                "sha256:c357b3f628cf53ae2c4c05627ecc484553142ca23264e593d327bcde5e9c3407",
+                "sha256:ea8b7f6188e6fa117537c3df7da9fc686d485087abf6ac197f9c46432f7e4a3c"
+            ],
+            "version": "==2.8"
+        },
+        "imagesize": {
+            "hashes": [
+                "sha256:3f349de3eb99145973fefb7dbe38554414e5c30abd0c8e4b970a7c9d09f3a1d8",
+                "sha256:f3832918bc3c66617f92e35f5d70729187676313caa60c187eb0f28b8fe5e3b5"
+            ],
+            "version": "==1.1.0"
+        },
+        "jinja2": {
+            "hashes": [
+                "sha256:74320bb91f31270f9551d46522e33af46a80c3d619f4a4bf42b3164d30b5911f",
+                "sha256:9fe95f19286cfefaa917656583d020be14e7859c6b0252588391e47db34527de"
+            ],
+            "version": "==2.10.3"
+        },
+        "markupsafe": {
+            "hashes": [
+                "sha256:00bc623926325b26bb9605ae9eae8a215691f33cae5df11ca5424f06f2d1f473",
+                "sha256:09027a7803a62ca78792ad89403b1b7a73a01c8cb65909cd876f7fcebd79b161",
+                "sha256:09c4b7f37d6c648cb13f9230d847adf22f8171b1ccc4d5682398e77f40309235",
+                "sha256:1027c282dad077d0bae18be6794e6b6b8c91d58ed8a8d89a89d59693b9131db5",
+                "sha256:24982cc2533820871eba85ba648cd53d8623687ff11cbb805be4ff7b4c971aff",
+                "sha256:29872e92839765e546828bb7754a68c418d927cd064fd4708fab9fe9c8bb116b",
+                "sha256:43a55c2930bbc139570ac2452adf3d70cdbb3cfe5912c71cdce1c2c6bbd9c5d1",
+                "sha256:46c99d2de99945ec5cb54f23c8cd5689f6d7177305ebff350a58ce5f8de1669e",
+                "sha256:500d4957e52ddc3351cabf489e79c91c17f6e0899158447047588650b5e69183",
+                "sha256:535f6fc4d397c1563d08b88e485c3496cf5784e927af890fb3c3aac7f933ec66",
+                "sha256:62fe6c95e3ec8a7fad637b7f3d372c15ec1caa01ab47926cfdf7a75b40e0eac1",
+                "sha256:6dd73240d2af64df90aa7c4e7481e23825ea70af4b4922f8ede5b9e35f78a3b1",
+                "sha256:717ba8fe3ae9cc0006d7c451f0bb265ee07739daf76355d06366154ee68d221e",
+                "sha256:79855e1c5b8da654cf486b830bd42c06e8780cea587384cf6545b7d9ac013a0b",
+                "sha256:7c1699dfe0cf8ff607dbdcc1e9b9af1755371f92a68f706051cc8c37d447c905",
+                "sha256:88e5fcfb52ee7b911e8bb6d6aa2fd21fbecc674eadd44118a9cc3863f938e735",
+                "sha256:8defac2f2ccd6805ebf65f5eeb132adcf2ab57aa11fdf4c0dd5169a004710e7d",
+                "sha256:98c7086708b163d425c67c7a91bad6e466bb99d797aa64f965e9d25c12111a5e",
+                "sha256:9add70b36c5666a2ed02b43b335fe19002ee5235efd4b8a89bfcf9005bebac0d",
+                "sha256:9bf40443012702a1d2070043cb6291650a0841ece432556f784f004937f0f32c",
+                "sha256:ade5e387d2ad0d7ebf59146cc00c8044acbd863725f887353a10df825fc8ae21",
+                "sha256:b00c1de48212e4cc9603895652c5c410df699856a2853135b3967591e4beebc2",
+                "sha256:b1282f8c00509d99fef04d8ba936b156d419be841854fe901d8ae224c59f0be5",
+                "sha256:b2051432115498d3562c084a49bba65d97cf251f5a331c64a12ee7e04dacc51b",
+                "sha256:ba59edeaa2fc6114428f1637ffff42da1e311e29382d81b339c1817d37ec93c6",
+                "sha256:c8716a48d94b06bb3b2524c2b77e055fb313aeb4ea620c8dd03a105574ba704f",
+                "sha256:cd5df75523866410809ca100dc9681e301e3c27567cf498077e8551b6d20e42f",
+                "sha256:e249096428b3ae81b08327a63a485ad0878de3fb939049038579ac0ef61e17e7"
+            ],
+            "version": "==1.1.1"
+        },
+        "packaging": {
+            "hashes": [
+                "sha256:28b924174df7a2fa32c1953825ff29c61e2f5e082343165438812f00d3a7fc47",
+                "sha256:d9551545c6d761f3def1677baf08ab2a3ca17c56879e70fecba2fc4dde4ed108"
+            ],
+            "version": "==19.2"
+        },
+        "pygments": {
+            "hashes": [
+                "sha256:2a3fe295e54a20164a9df49c75fa58526d3be48e14aceba6d6b1e8ac0bfd6f1b",
+                "sha256:98c8aa5a9f778fcd1026a17361ddaf7330d1b7c62ae97c3bb0ae73e0b9b6b0fe"
+            ],
+            "version": "==2.5.2"
+        },
+        "pyparsing": {
+            "hashes": [
+                "sha256:20f995ecd72f2a1f4bf6b072b63b22e2eb457836601e76d6e5dfcd75436acc1f",
+                "sha256:4ca62001be367f01bd3e92ecbb79070272a9d4964dce6a48a82ff0b8bc7e683a"
+            ],
+            "version": "==2.4.5"
+        },
+        "pytz": {
+            "hashes": [
+                "sha256:1c557d7d0e871de1f5ccd5833f60fb2550652da6be2693c1e02300743d21500d",
+                "sha256:b02c06db6cf09c12dd25137e563b31700d3b80fcc4ad23abb7a315f2789819be"
+            ],
+            "version": "==2019.3"
+        },
+        "requests": {
+            "hashes": [
+                "sha256:11e007a8a2aa0323f5a921e9e6a2d7e4e67d9877e85773fba9ba6419025cbeb4",
+                "sha256:9cf5292fcd0f598c671cfc1e0d7d1a7f13bb8085e9a590f48c010551dc6c4b31"
+            ],
+            "version": "==2.22.0"
+        },
+        "six": {
+            "hashes": [
+                "sha256:1f1b7d42e254082a9db6279deae68afb421ceba6158efa6131de7b3003ee93fd",
+                "sha256:30f610279e8b2578cab6db20741130331735c781b56053c59c4076da27f06b66"
+            ],
+            "version": "==1.13.0"
+        },
+        "snowballstemmer": {
+            "hashes": [
+                "sha256:209f257d7533fdb3cb73bdbd24f436239ca3b2fa67d56f6ff88e86be08cc5ef0",
+                "sha256:df3bac3df4c2c01363f3dd2cfa78cce2840a79b9f1c2d2de9ce8d31683992f52"
+            ],
+            "version": "==2.0.0"
+        },
+        "sphinx": {
+            "hashes": [
+                "sha256:298537cb3234578b2d954ff18c5608468229e116a9757af3b831c2b2b4819159",
+                "sha256:e6e766b74f85f37a5f3e0773a1e1be8db3fcb799deb58ca6d18b70b0b44542a5"
+            ],
+            "index": "pypi",
+            "version": "==2.3.1"
+        },
+        "sphinx-better-theme": {
+            "hashes": [
+                "sha256:420570d80d8cab25b35cef2b79619104675777dff5a23deebe9ba2191d48c1ce"
+            ],
+            "index": "pypi",
+            "version": "==0.1.5"
+        },
+        "sphinxcontrib-applehelp": {
+            "hashes": [
+                "sha256:edaa0ab2b2bc74403149cb0209d6775c96de797dfd5b5e2a71981309efab3897",
+                "sha256:fb8dee85af95e5c30c91f10e7eb3c8967308518e0f7488a2828ef7bc191d0d5d"
+            ],
+            "version": "==1.0.1"
+        },
+        "sphinxcontrib-devhelp": {
+            "hashes": [
+                "sha256:6c64b077937330a9128a4da74586e8c2130262f014689b4b89e2d08ee7294a34",
+                "sha256:9512ecb00a2b0821a146736b39f7aeb90759834b07e81e8cc23a9c70bacb9981"
+            ],
+            "version": "==1.0.1"
+        },
+        "sphinxcontrib-htmlhelp": {
+            "hashes": [
+                "sha256:4670f99f8951bd78cd4ad2ab962f798f5618b17675c35c5ac3b2132a14ea8422",
+                "sha256:d4fd39a65a625c9df86d7fa8a2d9f3cd8299a3a4b15db63b50aac9e161d8eff7"
+            ],
+            "version": "==1.0.2"
+        },
+        "sphinxcontrib-jsmath": {
+            "hashes": [
+                "sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178",
+                "sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8"
+            ],
+            "version": "==1.0.1"
+        },
+        "sphinxcontrib-qthelp": {
+            "hashes": [
+                "sha256:513049b93031beb1f57d4daea74068a4feb77aa5630f856fcff2e50de14e9a20",
+                "sha256:79465ce11ae5694ff165becda529a600c754f4bc459778778c7017374d4d406f"
+            ],
+            "version": "==1.0.2"
+        },
+        "sphinxcontrib-serializinghtml": {
+            "hashes": [
+                "sha256:c0efb33f8052c04fd7a26c0a07f1678e8512e0faec19f4aa8f2473a8b81d5227",
+                "sha256:db6615af393650bf1151a6cd39120c29abaf93cc60db8c48eb2dddbfdc3a9768"
+            ],
+            "version": "==1.1.3"
+        },
+        "urllib3": {
+            "hashes": [
+                "sha256:a8a318824cc77d1fd4b2bec2ded92646630d7fe8619497b142c84a9e6f5a7293",
+                "sha256:f3c5fd51747d450d4dcf6f923c81f78f811aab8205fda64b0aba34a4e48b0745"
+            ],
+            "version": "==1.25.7"
+        }
+    },
+    "develop": {}
+}
diff --git a/doc/src/conf.py b/doc/src/conf.py
new file mode 100644
index 0000000..305ef6b
--- /dev/null
+++ b/doc/src/conf.py
@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+
+import os
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'newtype'
+copyright = '2019, Felix Morgner'
+author = 'Felix Morgner'
+version = '1.0'
+release = '1.0.0'
+
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    'sphinx.ext.todo',
+    'sphinx.ext.githubpages',
+]
+
+highlight_language = 'c++'
+
+pygments_style = 'tango'
+
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+
+html_theme = 'haiku'
+html_theme_options = {
+}
+
+# -- Options for manual page output -------------------------------------------------
+
+man_pages = [
+    (
+        "index",
+        "newtype",
+        "A library of types and functions to create strong type aliases",
+        ["Felix Morgner <felix.morgner@gmail.com>"],
+        3,
+    ),
+]
\ No newline at end of file
diff --git a/doc/src/index.rst b/doc/src/index.rst
new file mode 100644
index 0000000..3a324e1
--- /dev/null
+++ b/doc/src/index.rst
@@ -0,0 +1,154 @@
+#############
+Documentation
+#############
+
+The ``newtype`` library provides types and functions to facilitate the creation of strong type aliases.
+
+API
+===
+
+.. cpp:namespace-push:: nt
+
+This section of the documentation describes the public API of the *new_type*.
+It provides detailed descriptions of the types and functions designed to be used by applications.
+Additionally, this section provides usage examples that demonstrate the use and properties of the public API.
+
+Class template :cpp:class:`new_type`
+----------------------------------------
+
+.. cpp:class:: template<typename BaseType, typename TagType, auto DerivationClause = deriving()> \
+               new_type
+
+   The class template :cpp:class:`new_type` is designed to allow the creation of new types based on existing types.
+   Similarly to the Haskell :literal:`newtype`, this class template creates a new type that is layout equivalent to the underlying type.
+
+   :tparam BaseType: The underlying type of the new strong alias
+   :tparam TagType: A type uniquely identifying this string alias
+   :tparam DerivationClause: A :cpp:struct:`derivation_clause` listing all features that shall be automatically derived.
+
+
+Usage
+~~~~~
+
+:ref:`new-type-usage-simple` below demonstrate the most basic usage of :cpp:class:`new_type`.
+In it, :cpp:class:`new_type` is used to create a new strong alias :literal:`width` for :literal:`unsigned int`.
+
+.. code-block:: c++
+   :linenos:
+   :name: new-type-usage-simple
+   :caption: Creating a new strong alias for :literal:`unsigned int`
+
+   #include <newtype/new_type.hpp>
+
+   using width = nt::new_type<unsigned int, struct width_tag>;
+
+The class template :cpp:class:`new_type` expects the desired underlying type as its first template argument, :literal:`unsigned int` in the example above.
+As a second template argument, :cpp:class:`new_type` expects a tag- or phantom-type.
+Neither the underlying type, nor the tag-type are is required to be complete.
+
+The class template :cpp:class:`new_type` takes as a third template argument an instance of :cpp:class:`derivation_clause`.
+Derivation clauses make it possible to let the implementation derive certain operations automatically.
+For example, the derivation tag :cpp:var:`Arithmetic` enables automatic derivation of arithmetic operations for a given instance of :cpp:class:`new_type` (see :ref:`new-type-usage-deriving-arithmetic` below).
+
+.. code-block:: c++
+   :linenos:
+   :name: new-type-usage-deriving-arithmetic
+   :caption: Automatically deriving arithmetic operations
+
+   #include <newtype/new_type.hpp>
+
+   using width = nt::new_type<unsigned int, struct width_tag, deriving(nt::Arithmetic)>;
+
+Synopsis
+~~~~~~~~
+
+.. code-block::
+
+   namespace nt
+   {
+     template<typename BaseType, typename TagType, auto DerivationClause = deriving()>
+     class new_type
+     {
+     public:
+
+       // Constructors
+
+       constexpr explicit new_type() noexcept(std::is_nothrow_default_constructible_v<BaseType>) = /*see below*/;
+
+       constexpr explicit new_type(BaseType const &) noexcept(std::is_nothrow_copy_constructible_v<BaseType>);
+
+       constexpr explicit new_type(BaseType      &&) noexcept(std::is_nothrow_move_constructible_v<BaseType>);
+
+       // Assignment operators
+
+       auto constexpr operator=(new_type const &) noexcept(std::is_nothrow_copy_assignable_v<BaseType>) -> new_type & = /*see below*/
+
+       auto constexpr operator=(new_type &&) noexcept(std::is_nothrow_move_assignable_v<BaseType>) -> new_type & = /*see below*/
+
+       // Accessors
+
+       auto constexpr decay() const noexcept -> BaseType;
+
+       /* EXPLICIT: see below */ constexpr operator base_type() const noexcept(/*see below*/)
+
+       // Indirection operators
+
+       auto constexpr operator->()       noexcept -> std::enable_if_t<DerivationClause(nt::Indirection), BaseType       *>;
+
+       auto constexpr operator->() const noexcept -> std::enable_if_t<DerivationClause(nt::Indirection), BaseType const *>;
+
+     private:
+       BaseType m_value;
+     };
+
+     // Equality comparison operators
+
+     template<typename BaseType,
+              typename TagType,
+              auto DerivationClause>
+     auto constexpr operator==(new_type<BaseType, TagType, DerivationClause> const &,
+                               new_type<BaseType, TagType, DerivationClause> const &) noexcept(/*see below*/)
+                               -> bool;
+
+     template<typename BaseType,
+              typename TagType,
+              auto DerivationClause>
+     auto constexpr operator!=(new_type<BaseType, TagType, DerivationClause> const &,
+                               new_type<BaseType, TagType, DerivationClause> const &) noexcept(/*see below*/)
+                               -> bool;
+     
+     // Relational operators
+
+     template<typename BaseType,
+              typename TagType,
+              auto DerivationClause,
+              typename = std::enable_if_t<DerivationClause(nt::Relational)>
+     auto constexpr operator<(new_type<BaseType, TagType, DerivationClause> const &,
+                              new_type<BaseType, TagType, DerivationClause> const &) noexcept(/*see below*/)
+                              -> bool;
+
+     template<typename BaseType,
+              typename TagType,
+              auto DerivationClause,
+              typename = std::enable_if_t<DerivationClause(nt::Relational)>
+     auto constexpr operator>(new_type<BaseType, TagType, DerivationClause> const &,
+                              new_type<BaseType, TagType, DerivationClause> const &) noexcept(/*see below*/)
+                              -> bool;
+
+     template<typename BaseType,
+              typename TagType,
+              auto DerivationClause,
+              typename = std::enable_if_t<DerivationClause(nt::Relational)>
+     auto constexpr operator<=(new_type<BaseType, TagType, DerivationClause> const &,
+                               new_type<BaseType, TagType, DerivationClause> const &) noexcept(/*see below*/)
+                               -> bool;
+
+     template<typename BaseType,
+              typename TagType,
+              auto DerivationClause,
+              typename = std::enable_if_t<DerivationClause(nt::Relational)>
+     auto constexpr operator>=(new_type<BaseType, TagType, DerivationClause> const &,
+                               new_type<BaseType, TagType, DerivationClause> const &) noexcept(/*see below*/)
+                               -> bool;
+
+   }