From 6370b3fc6ffb973cc272f18d18db521c02fea0f1 Mon Sep 17 00:00:00 2001 From: Felix Morgner Date: Sun, 22 Dec 2019 19:47:21 +0100 Subject: newtype: initial commit --- doc/Pipfile | 14 ++++ doc/Pipfile.lock | 232 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/src/conf.py | 44 +++++++++++ doc/src/index.rst | 154 ++++++++++++++++++++++++++++++++++++ 4 files changed, 444 insertions(+) create mode 100644 doc/Pipfile create mode 100644 doc/Pipfile.lock create mode 100644 doc/src/conf.py create mode 100644 doc/src/index.rst (limited to 'doc') 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 "], + 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 \ + 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 + + using width = nt::new_type; + +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 + + using width = nt::new_type; + +Synopsis +~~~~~~~~ + +.. code-block:: + + namespace nt + { + template + class new_type + { + public: + + // Constructors + + constexpr explicit new_type() noexcept(std::is_nothrow_default_constructible_v) = /*see below*/; + + constexpr explicit new_type(BaseType const &) noexcept(std::is_nothrow_copy_constructible_v); + + constexpr explicit new_type(BaseType &&) noexcept(std::is_nothrow_move_constructible_v); + + // Assignment operators + + auto constexpr operator=(new_type const &) noexcept(std::is_nothrow_copy_assignable_v) -> new_type & = /*see below*/ + + auto constexpr operator=(new_type &&) noexcept(std::is_nothrow_move_assignable_v) -> 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; + + auto constexpr operator->() const noexcept -> std::enable_if_t; + + private: + BaseType m_value; + }; + + // Equality comparison operators + + template + auto constexpr operator==(new_type const &, + new_type const &) noexcept(/*see below*/) + -> bool; + + template + auto constexpr operator!=(new_type const &, + new_type const &) noexcept(/*see below*/) + -> bool; + + // Relational operators + + template + auto constexpr operator<(new_type const &, + new_type const &) noexcept(/*see below*/) + -> bool; + + template + auto constexpr operator>(new_type const &, + new_type const &) noexcept(/*see below*/) + -> bool; + + template + auto constexpr operator<=(new_type const &, + new_type const &) noexcept(/*see below*/) + -> bool; + + template + auto constexpr operator>=(new_type const &, + new_type const &) noexcept(/*see below*/) + -> bool; + + } -- cgit v1.2.3