doc: move docs to source

4 files changed, 1319 insertions, 0 deletions

diff --git a/source/doc/.gitignore b/source/doc/.gitignore
new file mode 100644
index 0000000..ee826c1
--- /dev/null
+++ b/source/doc/.gitignore
@@ -0,0 +1,2 @@
+Pipfile
+Pipfile.lock
diff --git a/source/doc/requirements.txt b/source/doc/requirements.txt
new file mode 100644
index 0000000..b80a564
--- /dev/null
+++ b/source/doc/requirements.txt
@@ -0,0 +1 @@
+sphinx==2.4.2
diff --git a/source/doc/src/conf.py b/source/doc/src/conf.py
new file mode 100644
index 0000000..1337ce3
--- /dev/null
+++ b/source/doc/src/conf.py
@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+
+import os
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'newtype'
+copyright = '2020, Felix Morgner'
+author = 'Felix Morgner'
+version = '1.1'
+release = '1.1.0'
+
+
+# -- General configuration ---------------------------------------------------
+
+master_doc = 'index'
+
+extensions = [
+    'sphinx.ext.todo',
+    'sphinx.ext.githubpages',
+]
+
+highlight_language = 'c++'
+
+pygments_style = 'tango'
+
+exclude_patterns = []
+
+numfig = True
+
+# -- 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/source/doc/src/index.rst b/source/doc/src/index.rst
new file mode 100644
index 0000000..290f17e
--- /dev/null
+++ b/source/doc/src/index.rst
@@ -0,0 +1,1268 @@
+.. cpp:namespace-push:: nt
+
+.. |BaseTypeDoc| replace:: The type of the contained object
+.. |TagTypeDoc| replace:: A tag to uniquely identify an instance of :cpp:class:`nt::new_type`
+.. |DerivationClauseDoc| replace:: A (possibly empty) list of derivation tags as generated by :cpp:func:`nt::deriving`
+
+.. only:: html
+
+   .. contents:: Table of Contents
+      :depth: 5
+
+#############
+Documentation
+#############
+
+The ``newtype`` library provides types and functions to facilitate the creation of strong type aliases.
+
+Example Usage
+#############
+
+.. note::
+
+   All examples shown in this section can be found in the directory :literal:`examples/src` within the source root.
+
+:ref:`new-type-usage-basic` below demonstrates the basic usage of :cpp:class:`new_type`.
+In it, :cpp:class:`new_type` is used to create thre new strong aliases :literal:`Width`, :literal:`Height`, and :literal:`Area` that all alias :literal:`unsigned int`.
+
+.. literalinclude:: ../../examples/src/basic_usage.cpp
+   :language: c++
+   :linenos:
+   :name: new-type-usage-basic
+   :caption: Basic usage of :cpp:class:`new_type`
+
+However, using :cpp:class:`new_type` in this fashion seem quite cumbersome.
+Starting from the bottom, :literal:`unsigned int` can normally be shifted on to any :cpp:class:`std::basic_ostream`, like :cpp:var:`std::cout` in this example.
+Since printing values, among other things, is a common scenario, ``newtype`` provides facilities to support automatic derivation of supporting functions.
+
+.. literalinclude:: ../../examples/src/basic_usage_with_show.cpp
+   :emphasize-lines: 1,2,9
+   :language: c++
+   :linenos:
+   :name: new-type-usage-basic-show
+   :caption: Improved usability using the :cpp:var:`Show` derivation tag
+
+:ref:`new-type-usage-basic-show` demonstrates how the function template :cpp:func:`deriving` can be used to enable automatic derivation of the stream output operator for :literal:`Area`.
+Similarly, it is possible to derive the stream input operators of :literal:`Width` and :literal:`Height`, as shown in :ref:`new-type-usage-basic-read` below.
+
+.. literalinclude:: ../../examples/src/basic_usage_with_read.cpp
+   :emphasize-lines: 7,8,31,32,34
+   :language: c++
+   :linenos:
+   :name: new-type-usage-basic-read
+   :caption: Deriving input operations using the :cpp:var:`Read` derivation tag
+
+API
+###
+
+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.
+All declarations described in this section are found in the namespace :cpp:any:`nt`, unless noted otherwise.
+
+Header :literal:`<newtype/new_type.hpp>`
+========================================
+
+This header contains the definitions of the class template :cpp:class:`new_type` as well as a set of associated namespace-level functions.
+
+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 newtype, this class template creates a new type that is layout equivalent to the underlying type.
+
+   :tparam BaseType: |BaseTypeDoc|
+   :tparam TagType: |TagTypeDoc|
+   :tparam DerivationClause: |DerivationClauseDoc|
+
+   .. versionadded:: 1.0.0
+
+   **Member Type Aliases**
+
+   .. cpp:type:: base_type = BaseType
+
+   .. cpp:type:: tag_type = TagType
+
+   .. cpp:type:: derivation_clause_type = decltype(DerivationClause)
+
+   .. cpp:type:: iterator = typename BaseType::iterator
+
+      :enablement: This type alias shall be defined iff. this :cpp:class:`new_type`'s :cpp:type:`base_type` has a member type :cpp:type:`iterator <new_type::base_type::iterator>` and the :cpp:var:`derivation clause <derivation_clause>` contains :cpp:var:`Iterable`.
+
+      .. versionadded:: 1.1.0
+
+   .. cpp:type:: const_iterator = typename BaseType::const_iterator
+
+      :enablement: This type alias shall be defined iff. this :cpp:class:`new_type`'s :cpp:type:`base_type` has a member type :cpp:type:`const_iterator <new_type::base_type::const_iterator>` and the :cpp:var:`derivation clause <derivation_clause>` contains :cpp:var:`Iterable`.
+
+      .. versionadded:: 1.1.0
+
+   .. cpp:type:: reverse_iterator = typename BaseType::reverse_iterator
+
+      :enablement: This type alias shall be defined iff. this :cpp:class:`new_type`'s :cpp:type:`base_type` has a member type :cpp:type:`reverse_iterator <new_type::base_type::reverse_iterator>` and the :cpp:var:`derivation clause <derivation_clause>` contains :cpp:var:`Iterable`.
+
+      .. versionadded:: 1.1.0
+
+   .. cpp:type:: const_reverse_iterator = typename BaseType::const_reverse_iterator
+
+      :enablement: This type alias shall be defined iff. this :cpp:class:`new_type`'s :cpp:type:`base_type` has a member type :cpp:type:`const_reverse_iterator <new_type::base_type::const_reverse_iterator>` and the :cpp:var:`derivation clause <derivation_clause>` contains :cpp:var:`Iterable`.
+
+      .. versionadded:: 1.1.0
+
+   **Static Data Members**
+
+   .. cpp:var:: static derivation_clause_type constexpr derivation_clause = DerivationClause
+
+   **Constructors**
+
+   .. cpp:function:: constexpr new_type()
+
+      Construct a new instance of this :cpp:class:`new_type` by default constructing the contained object.
+
+      :throws: Any exception thrown by the default constructor of this :cpp:class:`new_type`'s :cpp:type:`base_type`.
+               This constructor shall be noexcept iff. this :cpp:class:`new_type`'s :cpp:type:`base_type` is *nothrow default-construtible*.
+      :enablement: This constructor shall be defined as :literal:`= default` iff. this :cpp:class:`new_type`'s :cpp:type:`base_type` is *default-construtible*.
+                   Otherwise, this constructor shall be explicitely deleted.
+
+   .. cpp:function:: constexpr new_type(new_type const & other)
+
+      Construct a new instance of this :cpp:class:`new_type` by copy-constructing the contained object using the value contained by :literal:`other`.
+
+      :param other: An existing instance of this :cpp:class:`new_type`
+      :throws: Any exception thrown by the copy-constructor of this :cpp:class:`new_type`'s :cpp:type:`base_type`.
+               This constructor shall be noexcept iff. this :cpp:class:`new_type`'s :cpp:type:`base_type` is *nothrow copy-construtible*.
+      :enablement: This constructor shall be defined as :literal:`= default` iff. this :cpp:class:`new_type`'s :cpp:type:`base_type` is *copy-construtible*.
+                   Otherwise, this constructor shall be explicitely deleted.
+
+   .. cpp:function:: constexpr new_type(new_type && other)
+
+      Construct a new instance of this :cpp:class:`new_type` by move-constructing the contained object using the value contained by :literal:`other`.
+
+      :param other: An existing instance of this :cpp:class:`new_type`
+      :throws: Any exception thrown by the move-constructor of this :cpp:class:`new_type`'s :cpp:type:`base_type`.
+               This constructor shall be noexcept iff. this :cpp:class:`new_type`'s :cpp:type:`base_type` is *nothrow move-construtible*.
+      :enablement: This constructor shall be defined as :literal:`= default` iff. this :cpp:class:`new_type`'s :cpp:type:`base_type` is *move-construtible*.
+                   Otherwise, this constructor shall be explicitely deleted.
+
+   .. cpp:function:: constexpr new_type(BaseType const & value)
+
+      Construct a new instance of this :cpp:class:`new_type` by copy-constructing the contained object using :literal:`value`.
+
+      :param value: An existing instance of this :cpp:class:`new_type`
+      :throws: Any exception thrown by the copy-constructor of this :cpp:class:`new_type`'s :cpp:type:`base_type`.
+               This constructor shall be noexcept iff. this :cpp:class:`new_type`'s :cpp:type:`base_type` is *nothrow copy-construtible*.
+      :enablement: This constructor shall be defined as :literal:`= default` iff. this :cpp:class:`new_type`'s :cpp:type:`base_type` is *copy-construtible*.
+                   Otherwise, this constructor shall be explicitely deleted.
+
+   .. cpp:function:: constexpr new_type(BaseType && value)
+
+      Construct a new instance of this :cpp:class:`new_type` by move-constructing the contained object using :literal:`value`.
+
+      :param value: An existing instance of this :cpp:class:`new_type`
+      :throws: Any exception thrown by the move-constructor of this :cpp:class:`new_type`'s :cpp:type:`base_type`.
+               This constructor shall be noexcept iff. this :cpp:class:`new_type`'s :cpp:type:`base_type` is *nothrow move-construtible*.
+      :enablement: This constructor shall be defined as :literal:`= default` iff. this :cpp:class:`new_type`'s :cpp:type:`base_type` is *move-construtible*.
+                   Otherwise, this constructor shall be explicitely deleted.
+
+   **Assignment Operators**
+
+   .. cpp:function:: constexpr new_type & operator=(new_type const & other)
+
+      Copy the value of an existing instance of this :cpp:class:`new_type` and replace this instance's value
+
+      :param other: An existing instance of this :cpp:class:`new_type`
+      :throws: Any exception thrown by the copy-assignment operator of this :cpp:class:`new_type`'s :cpp:type:`base_type`.
+               This operator shall be noexcept iff. this :cpp:class:`new_type`'s :cpp:type:`base_type` is *nothrow copy-assignable*.
+      :enablement: This operator shall be defined as :literal:`= default` iff. this :cpp:class:`new_type`'s :cpp:type:`base_type` is *copy-assignable*.
+                   Otherwise, this operator shall be explicitely deleted.
+
+   .. cpp:function:: constexpr new_type & operator=(new_type && other)
+
+      Move the value of an existing instance of this :cpp:class:`new_type` and replace this instance's value
+
+      :param other: An existing instance of this :cpp:class:`new_type`
+      :throws: Any exception thrown by the move-assignment operator of this :cpp:class:`new_type`'s :cpp:type:`base_type`.
+               This operator shall be noexcept iff. this :cpp:class:`new_type`'s :cpp:type:`base_type` is *nothrow move-assignable*.
+      :enablement: This operator shall be defined as :literal:`= default` iff. this :cpp:class:`new_type`'s :cpp:type:`base_type` is *move-assignable*.
+                   Otherwise, this operator shall be explicitely deleted.
+
+   **Accessors**
+
+   .. cpp:function:: constexpr BaseType decay() const
+
+      Retrieve a copy of the object contained by this :cpp:class:`new_type` object
+
+      :throws: Any exception thrown by the copy-constructor of this :cpp:class:`new_type`'s :cpp:type:`base_type`.
+               This operator shall be noexcept iff. this :cpp:class:`new_type`'s :cpp:type:`base_type` is *nothrow copy-constructible*.
+
+   .. cpp:function:: constexpr operator BaseType() const
+
+      Retrieve a copy of the object contained by this :cpp:class:`new_type` object
+
+      :throws: Any exception thrown by the copy-constructor of this :cpp:class:`new_type`'s :cpp:type:`base_type`.
+               This operator shall be noexcept iff. this :cpp:class:`new_type`'s :cpp:type:`base_type` is *nothrow copy-constructible*.
+      :explicit: This conversion operator shall be explicit unless this :cpp:class:`new_type`'s :cpp:var:`derivation clause <derivation_clause>` contains :cpp:var:`ImplicitConversion`.
+
+   **Member Access Through Pointer**
+
+   .. cpp:function:: constexpr BaseType operator->() noexcept
+
+      Perform "member access through pointer" via a pointer to object contained by this :cpp:class:`new_type`
+
+      :enablement: This operator shall be available iff. this :cpp:class:`new_type`'s :cpp:var:`derivation clause <derivation_clause>` contains :cpp:var:`Indirection`
+
+   .. cpp:function:: constexpr BaseType const * operator->() const noexcept
+
+      Perform "member access through pointer" via a pointer to object contained by this :cpp:class:`new_type`
+
+      :enablement: This operator shall be available iff. this :cpp:class:`new_type`'s :cpp:var:`derivation clause <derivation_clause>` contains :cpp:var:`Indirection`
+
+   **Iterators**
+
+   .. cpp:function:: constexpr iterator begin()
+
+      Get an iterator to the beginning of the object contained by this :cpp:class:`new_type`
+
+      :enablement: This function shall be available iff.
+
+         a) this :cpp:class:`new_type`'s :cpp:var:`derivation clause <derivation_clause>` contains :cpp:var:`Iterable` and
+         b) this :cpp:class:`new_type`'s :cpp:type:`base type <base_type>` has a non-static member function :cpp:func:`begin() <new_type::base_type::begin()>` that returns an instance of type :cpp:type:`iterator`
+
+      .. versionadded:: 1.1.0
+
+   .. cpp:function:: constexpr iterator begin() const
+
+      Get a constant iterator to the beginning of the object contained by this :cpp:class:`new_type`
+
+      :enablement: This function shall be available iff.
+
+         a) this :cpp:class:`new_type`'s :cpp:var:`derivation clause <derivation_clause>` contains :cpp:var:`Iterable` and
+         b) this :cpp:class:`new_type`'s :cpp:type:`base type <base_type>` has a non-static member function :cpp:func:`begin() const <new_type::base_type::begin()>` that returns an instance of type :cpp:type:`const_iterator`
+
+      .. versionadded:: 1.1.0
+
+   .. cpp:function:: constexpr iterator cbegin() const
+
+      Get a constant iterator to the beginning of the object contained by this :cpp:class:`new_type`
+
+      :enablement: This function shall be available iff.
+
+         a) this :cpp:class:`new_type`'s :cpp:var:`derivation clause <derivation_clause>` contains :cpp:var:`Iterable` and
+         b) this :cpp:class:`new_type`'s :cpp:type:`base type <base_type>` has a non-static member function :cpp:func:`cbegin() const <new_type::base_type::cbegin()>` that returns an instance of type :cpp:type:`const_iterator`
+
+      .. versionadded:: 1.1.0
+
+   .. cpp:function:: constexpr iterator rbegin()
+
+      Get a reverse iterator to the beginning of the object contained by this :cpp:class:`new_type`
+
+      :enablement: This function shall be available iff.
+
+         a) this :cpp:class:`new_type`'s :cpp:var:`derivation clause <derivation_clause>` contains :cpp:var:`Iterable` and
+         b) this :cpp:class:`new_type`'s :cpp:type:`base type <base_type>` has a non-static member function :cpp:func:`rbegin() <new_type::base_type::rbegin()>` that returns an instance of type :cpp:type:`reverse_iterator`
+
+      .. versionadded:: 1.1.0
+
+   .. cpp:function:: constexpr iterator rbegin() const
+
+      Get a constant reverse iterator to the beginning of the object contained by this :cpp:class:`new_type`
+
+      :enablement: This function shall be available iff.
+
+         a) this :cpp:class:`new_type`'s :cpp:var:`derivation clause <derivation_clause>` contains :cpp:var:`Iterable` and
+         b) this :cpp:class:`new_type`'s :cpp:type:`base type <base_type>` has a non-static member function :cpp:func:`rbegin() const <new_type::base_type::rbegin()>` that returns an instance of type :cpp:type:`const_reverse_iterator`
+
+      .. versionadded:: 1.1.0
+
+   .. cpp:function:: constexpr iterator crbegin() const
+
+      Get a constant reverse iterator to the beginning of the object contained by this :cpp:class:`new_type`
+
+      :enablement: This function shall be available iff.
+
+         a) this :cpp:class:`new_type`'s :cpp:var:`derivation clause <derivation_clause>` contains :cpp:var:`Iterable` and
+         b) this :cpp:class:`new_type`'s :cpp:type:`base type <base_type>` has a non-static member function :cpp:func:`crbegin() const <new_type::base_type::crbegin()>` that returns an instance of type :cpp:type:`const_reverse_iterator`
+
+      .. versionadded:: 1.1.0
+
+   .. cpp:function:: constexpr iterator end()
+
+      Get an iterator beyond the end of the object contained by this :cpp:class:`new_type`
+
+      :enablement: This function shall be available iff.
+
+         a) this :cpp:class:`new_type`'s :cpp:var:`derivation clause <derivation_clause>` contains :cpp:var:`Iterable` and
+         b) this :cpp:class:`new_type`'s :cpp:type:`base type <base_type>` has a non-static member function :cpp:func:`end() <new_type::base_type::end()>` that returns an instance of type :cpp:type:`iterator`
+
+      .. versionadded:: 1.1.0
+
+   .. cpp:function:: constexpr iterator end() const
+
+      Get a constant iterator beyond the end of the object contained by this :cpp:class:`new_type`
+
+      :enablement: This function shall be available iff.
+
+         a) this :cpp:class:`new_type`'s :cpp:var:`derivation clause <derivation_clause>` contains :cpp:var:`Iterable` and
+         b) this :cpp:class:`new_type`'s :cpp:type:`base type <base_type>` has a non-static member function :cpp:func:`end() const <new_type::base_type::end()>` that returns an instance of type :cpp:type:`const_iterator`
+
+      .. versionadded:: 1.1.0
+
+   .. cpp:function:: constexpr iterator cend() const
+
+      Get a constant iterator beyond the end of the object contained by this :cpp:class:`new_type`
+
+      :enablement: This function shall be available iff.
+
+         a) this :cpp:class:`new_type`'s :cpp:var:`derivation clause <derivation_clause>` contains :cpp:var:`Iterable` and
+         b) this :cpp:class:`new_type`'s :cpp:type:`base type <base_type>` has a non-static member function :cpp:func:`cend() const <new_type::base_type::cend()>` that returns an instance of type :cpp:type:`const_iterator`
+
+      .. versionadded:: 1.1.0
+
+   .. cpp:function:: constexpr iterator rend()
+
+      Get a reverse iterator beyond the end of the object contained by this :cpp:class:`new_type`
+
+      :enablement: This function shall be available iff.
+
+         a) this :cpp:class:`new_type`'s :cpp:var:`derivation clause <derivation_clause>` contains :cpp:var:`Iterable` and
+         b) this :cpp:class:`new_type`'s :cpp:type:`base type <base_type>` has a non-static member function :cpp:func:`rend() <new_type::base_type::rend()>` that returns an instance of type :cpp:type:`reverse_iterator`
+
+      .. versionadded:: 1.1.0
+
+   .. cpp:function:: constexpr iterator rend() const
+
+      Get a constant reverse iterator beyond the end of the object contained by this :cpp:class:`new_type`
+
+      :enablement: This function shall be available iff.
+
+         a) this :cpp:class:`new_type`'s :cpp:var:`derivation clause <derivation_clause>` contains :cpp:var:`Iterable` and
+         b) this :cpp:class:`new_type`'s :cpp:type:`base type <base_type>` has a non-static member function :cpp:func:`rend() const <new_type::base_type::rend()>` that returns an instance of type :cpp:type:`const_reverse_iterator`
+
+      .. versionadded:: 1.1.0
+
+   .. cpp:function:: constexpr iterator crend() const
+
+      Get a constant reverse iterator beyond the end of the object contained by this :cpp:class:`new_type`
+
+      :enablement: This function shall be available iff.
+
+         a) this :cpp:class:`new_type`'s :cpp:var:`derivation clause <derivation_clause>` contains :cpp:var:`Iterable` and
+         b) this :cpp:class:`new_type`'s :cpp:type:`base type <base_type>` has a non-static member function :cpp:func:`crend() const <new_type::base_type::crend()>` that returns an instance of type :cpp:type:`const_reverse_iterator`
+
+      .. versionadded:: 1.1.0
+
+:literal:`namespace`-level functions and function templates
+-----------------------------------------------------------
+
+The functions and functions templates described in this section provide additional functionality for the class template :cpp:class:`new_type` that is not part of the class itself.
+
+Equality Comparison Operators
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. cpp:function:: template<typename BaseType, typename TagType, auto DerivationClause> \
+                  constexpr bool operator==(new_type<BaseType, TagType, DerivationClause> const & lhs, new_type<BaseType, TagType, DerivationClause> const & rhs)
+
+   Check two instances of :cpp:class:`new_type\<BaseType, TagType, DerivationClause>` for equality.
+
+   :tparam BaseType: |BaseTypeDoc|
+   :tparam TagType: |TagTypeDoc|
+   :tparam DerivationClause: |DerivationClauseDoc|
+   :param lhs: The left-hand side of the comparison
+   :param rhs: The right-hand side of the comparison
+   :returns: The value returned by the comparison of the contained objects.
+   :throws: Any exception thrown by the comparison operator of objects contained by :literal:`lhs` and :literal:`rhs`.
+            This operator shall be noexcept iff. :cpp:type:`new_type::base_type` is *nothrow equals-comparable*.
+   :enablement: This operator shall be available iff. :cpp:type:`new_type::base_type` supports comparison using :literal:`==`
+
+   .. versionadded:: 1.0.0
+
+.. cpp:function:: template<typename BaseType, typename TagType, auto DerivationClause> \
+                  constexpr bool operator==(new_type<BaseType, TagType, DerivationClause> const & lhs, BaseType const & rhs)
+
+   Check an instance of :cpp:class:`new_type\<BaseType, TagType, DerivationClause>` for equality with an instance of :cpp:type:`BaseType`.
+
+   :tparam BaseType: |BaseTypeDoc|
+   :tparam TagType: |TagTypeDoc|
+   :tparam DerivationClause: |DerivationClauseDoc|
+   :param lhs: The left-hand side of the comparison
+   :param rhs: The right-hand side of the comparison
+   :returns: The value returned by the comparison of object contained by :literal:`lhs` with an object of the :cpp:type:`base type <new_type::base_type>`.
+   :throws: Any exception thrown by the comparison of object contained by :literal:`lhs` with an object of the :cpp:type:`base type <new_type::base_type>`. This operator shall be noexcept iff. :cpp:type:`new_type::base_type` is *nothrow equals-comparable*.
+   :enablement: This operator shall be available iff.
+
+      a. :cpp:type:`new_type::base_type` supports comparison using :literal:`==` and
+      b. the :cpp:var:`derivation clause <DerivationClause>` contains :cpp:var:`EqBase`
+
+   .. versionadded:: 1.0.0
+
+.. cpp:function:: template<typename BaseType, typename TagType, auto DerivationClause> \
+                  constexpr bool operator==(BaseType const & lhs, new_type<BaseType, TagType, DerivationClause> const & rhs)
+
+   Check an instance of :cpp:type:`BaseType` for equality with an instance of :cpp:class:`new_type\<BaseType, TagType, DerivationClause>`.
+
+   :tparam BaseType: |BaseTypeDoc|
+   :tparam TagType: |TagTypeDoc|
+   :tparam DerivationClause: |DerivationClauseDoc|
+   :param lhs: The left-hand side of the comparison
+   :param rhs: The right-hand side of the comparison
+   :returns: The value returned by the comparison of an object of :cpp:type:`base type <new_type::base_type>` with the object contained by :literal:`rhs`.
+   :throws: Any exception thrown by the comparison of an object of :cpp:type:`base type <new_type::base_type>` with the object contained by :literal:`rhs`. This operator shall be noexcept iff. :cpp:type:`new_type::base_type` is *nothrow equals-comparable*.
+   :enablement: This operator shall be available iff.
+
+      a. :cpp:type:`new_type::base_type` supports comparison using :literal:`==` and
+      b. the :cpp:var:`derivation clause <DerivationClause>` contains :cpp:var:`EqBase`
+
+   .. versionadded:: 1.0.0
+
+.. cpp:function:: template<typename BaseType, typename TagType, auto DerivationClause> \
+                  constexpr bool operator!=(new_type<BaseType, TagType, DerivationClause> const & lhs, new_type<BaseType, TagType, DerivationClause> const & rhs)
+
+   Check two instances of :cpp:class:`new_type\<BaseType, TagType, DerivationClause>` for in-equality.
+
+   :tparam BaseType: |BaseTypeDoc|
+   :tparam TagType: |TagTypeDoc|
+   :tparam DerivationClause: |DerivationClauseDoc|
+   :param lhs: The left-hand side of the comparison
+   :param rhs: The right-hand side of the comparison
+   :returns: The value returned by the comparison of the contained objects.
+   :throws: Any exception thrown by the comparison operator of theobjects contained by :literal:`lhs` and :literal:`rhs`.
+            This operator shall be noexcept iff. :cpp:type:`new_type::base_type` is *nothrow not-equals-comparable*.
+   :enablement: This operator shall be available iff. :cpp:type:`new_type::base_type` supports comparison using :literal:`!=`
+
+   .. versionadded:: 1.0.0
+
+.. cpp:function:: template<typename BaseType, typename TagType, auto DerivationClause> \
+                  constexpr bool operator!=(new_type<BaseType, TagType, DerivationClause> const & lhs, BaseType const & rhs)
+
+   Check an instance of :cpp:class:`new_type\<BaseType, TagType, DerivationClause>` for in-equality with an instance of :cpp:type:`BaseType`.
+
+   :tparam BaseType: |BaseTypeDoc|
+   :tparam TagType: |TagTypeDoc|
+   :tparam DerivationClause: |DerivationClauseDoc|
+   :param lhs: The left-hand side of the comparison
+   :param rhs: The right-hand side of the comparison
+   :returns: The value returned by the comparison of the object contained by :literal:`lhs` with an object of the :cpp:type:`base type <new_type::base_type>`.
+   :throws: Any exception thrown by the comparison of the object contained by :literal:`lhs` with an object of the :cpp:type:`base type <new_type::base_type>`.
+            This operator shall be noexcept iff. :cpp:type:`new_type::base_type` is *nothrow not-equals-comparable*.
+   :enablement: This operator shall be available iff.
+
+      a) :cpp:type:`new_type::base_type` supports comparison using :literal:`!=` and
+      b) the :cpp:var:`derivation clause <DerivationClause>` contains :cpp:var:`EqBase`
+
+   .. versionadded:: 1.0.0
+
+.. cpp:function:: template<typename BaseType, typename TagType, auto DerivationClause> \
+                  constexpr bool operator!=(BaseType const & lhs, new_type<BaseType, TagType, DerivationClause> const & rhs)
+
+   Check an instance of :cpp:type:`BaseType` for in-equality with an instance of :cpp:class:`new_type\<BaseType, TagType, DerivationClause>`.
+
+   :tparam BaseType: |BaseTypeDoc|
+   :tparam TagType: |TagTypeDoc|
+   :tparam DerivationClause: |DerivationClauseDoc|
+   :param lhs: The left-hand side of the comparison
+   :param rhs: The right-hand side of the comparison
+   :returns: The value returned by the comparison of an object of :cpp:type:`base type <new_type::base_type>` with the object contained by :literal:`rhs`.
+   :throws: Any exception thrown by the comparison of an object of :cpp:type:`base type <new_type::base_type>` with the object contained by :literal:`rhs`. This operator shall be noexcept iff. :cpp:type:`new_type::base_type` is *nothrow not-equals-comparable*.
+   :enablement: This operator shall be available iff.
+
+      a. :cpp:type:`new_type::base_type` supports comparison using :literal:`!=` and
+      b. the :cpp:var:`derivation clause <DerivationClause>` contains :cpp:var:`EqBase`
+
+   .. versionadded:: 1.0.0
+
+Relational Comparison Operators
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. cpp:function:: template<typename BaseType, typename TagType, auto DerivationClause> \
+                  constexpr bool operator<(new_type<BaseType, TagType, DerivationClause> const & lhs, new_type<BaseType, TagType, DerivationClause> const & rhs)
+
+   Compare two instances of the same :cpp:class:`new_type` using :literal:`<` (*less-than*).
+
+   :tparam BaseType: |BaseTypeDoc|
+   :tparam TagType: |TagTypeDoc|
+   :tparam DerivationClause: |DerivationClauseDoc|
+   :param lhs: The left-hand side of the comparison
+   :param rhs: The right-hand side of the comparison
+   :returns: The value returned by the comparison of the contained objects.
+   :throws: Any exception thrown by the comparison operator of the objects contained by :literal:`lhs` and :literal:`rhs`.
+            This operator shall be noexcept iff. :cpp:type:`new_type::base_type` is *nothrow less-than-comparable*.
+   :enablement: This operator shall be available iff.
+
+      a. :cpp:type:`new_type::base_type` supports comparison using :literal:`<` and
+      b. the :cpp:var:`derivation clause <DerivationClause>` contains :cpp:var:`Relational`
+
+   .. versionadded:: 1.0.0
+
+.. cpp:function:: template<typename BaseType, typename TagType, auto DerivationClause> \
+                  constexpr bool operator>(new_type<BaseType, TagType, DerivationClause> const & lhs, new_type<BaseType, TagType, DerivationClause> const & rhs)
+
+   Compare two instances of the same :cpp:class:`new_type` using :literal:`>` (*greater-than*).
+
+   :tparam BaseType: |BaseTypeDoc|
+   :tparam TagType: |TagTypeDoc|
+   :tparam DerivationClause: |DerivationClauseDoc|
+   :param lhs: The left-hand side of the comparison
+   :param rhs: The right-hand side of the comparison
+   :returns: The value returned by the comparison of the contained objects.
+   :throws: Any exception thrown by the comparison operator of the objects contained by :literal:`lhs` and :literal:`rhs`.
+            This operator shall be noexcept iff. :cpp:type:`new_type::base_type` is *nothrow greater-than-comparable*.
+   :enablement: This operator shall be available iff.
+
+      a. :cpp:type:`new_type::base_type` supports comparison using :literal:`>` and
+      b. the :cpp:var:`derivation clause <DerivationClause>` contains :cpp:var:`Relational`
+
+   .. versionadded:: 1.0.0
+
+.. cpp:function:: template<typename BaseType, typename TagType, auto DerivationClause> \
+                  constexpr bool operator<=(new_type<BaseType, TagType, DerivationClause> const & lhs, new_type<BaseType, TagType, DerivationClause> const & rhs)
+
+   Compare two instances of the same :cpp:class:`new_type` using :literal:`<=` (*less-than-equal*).
+
+   :tparam BaseType: |BaseTypeDoc|
+   :tparam TagType: |TagTypeDoc|
+   :tparam DerivationClause: |DerivationClauseDoc|
+   :param lhs: The left-hand side of the comparison
+   :param rhs: The right-hand side of the comparison
+   :returns: The value returned by the comparison of the contained objects.
+   :throws: Any exception thrown by the comparison operator of the objects contained by :literal:`lhs` and :literal:`rhs`.
+            This operator shall be noexcept iff. :cpp:type:`new_type::base_type` is *nothrow less-than-equal-comparable*.
+   :enablement: This operator shall be available iff.
+
+      a. :cpp:type:`new_type::base_type` supports comparison using :literal:`<=` and
+      b. the :cpp:var:`derivation clause <DerivationClause>` contains :cpp:var:`Relational`
+
+   .. versionadded:: 1.0.0
+
+.. cpp:function:: template<typename BaseType, typename TagType, auto DerivationClause> \
+                  constexpr bool operator>=(new_type<BaseType, TagType, DerivationClause> const & lhs, new_type<BaseType, TagType, DerivationClause> const & rhs)
+
+   Compare two instances of the same :cpp:class:`new_type` using :literal:`>=` (*greater-than-equal*).
+
+   :tparam BaseType: |BaseTypeDoc|
+   :tparam TagType: |TagTypeDoc|
+   :tparam DerivationClause: |DerivationClauseDoc|
+   :param lhs: The left-hand side of the comparison
+   :param rhs: The right-hand side of the comparison
+   :returns: The value returned by the comparison of the contained objects.
+   :throws: Any exception thrown by the comparison operator of the objects contained by :literal:`lhs` and :literal:`rhs`.
+            This operator shall be noexcept iff. :cpp:type:`new_type::base_type` is *nothrow greater-than-equal-comparable*.
+   :enablement: This operator shall be available iff.
+
+      a. :cpp:type:`new_type::base_type` supports comparison using :literal:`>=` and
+      b. the :cpp:var:`derivation clause <DerivationClause>` contains :cpp:var:`Relational`
+
+   .. versionadded:: 1.0.0
+
+Stream I/O Operators
+~~~~~~~~~~~~~~~~~~~~
+
+.. cpp:function:: template<typename BaseType, \
+                  typename TagType, \
+                  auto DerivationClause, \
+                  typename CharType, \
+                  typename StreamTraits> \
+                  std::basic_ostream<CharType, StreamTraits> & operator<<(std::basic_ostream<CharType, StreamTraits> & out, new_type<BaseType, TagType, DerivationClause> const & value)
+
+   Write an instance of :cpp:class:`new_type\<BaseType, TagType, DerivationClause>` to a standard :cpp:type:`ostream <std::ostream>`.
+
+   :tparam BaseType: |BaseTypeDoc|
+   :tparam TagType: |TagTypeDoc|
+   :tparam DerivationClause: |DerivationClauseDoc|
+   :tparam CharType: The stream character type
+   :tparam StreamTraits: The traits of the output stream
+   :param out: The output stream
+   :param value: A :cpp:class:`new_type` value to write to the output stream
+   :returns: A reference to the output stream
+   :throws: Any exception thrown by the stream-output operator of the object contained by :literal:`value`.
+            This operator shall be noexcept iff. :cpp:type:`new_type::base_type` is *nothrow output-streamable*.
+   :enablement: This operator shall be available iff.
+
+      a. :cpp:type:`new_type::base_type` supports being written to an output stream using :literal:`<<` and
+      b. the :cpp:var:`derivation clause <DerivationClause>` contains :cpp:var:`Show`
+
+   .. versionadded:: 1.0.0
+
+.. cpp:function:: template<typename BaseType, \
+                  typename TagType, \
+                  auto DerivationClause, \
+                  typename CharType, \
+                  typename StreamTraits> \
+                  std::basic_istream<CharType, StreamTraits> & operator>>(std::basic_istream<CharType, StreamTraits> & in, new_type<BaseType, TagType, DerivationClause> & value)
+
+   Read an instance of :cpp:class:`new_type\<BaseType, TagType, DerivationClause>` from a standard :cpp:type:`istream <std::istream>`.
+
+   :tparam BaseType: |BaseTypeDoc|
+   :tparam TagType: |TagTypeDoc|
+   :tparam DerivationClause: |DerivationClauseDoc|
+   :tparam CharType: The stream character type
+   :tparam StreamTraits: The traits of the input stream
+   :param in: The input stream
+   :param value: A :cpp:class:`new_type` value to be read from the output stream
+   :returns: A reference to the input stream
+   :throws: Any exception thrown by the stream-input operator of the object contained by :literal:`value`.
+            This operator shall be noexcept iff. :cpp:type:`new_type::base_type` is *nothrow input-streamable*.
+   :enablement: This operator shall be available iff.
+
+      a. :cpp:type:`new_type::base_type` supports being read from an input stream using :literal:`>>` and
+      b. the :cpp:var:`derivation clause <DerivationClause>` contains :cpp:var:`Read`
+
+   .. versionadded:: 1.0.0
+
+Arithmetic Operators
+~~~~~~~~~~~~~~~~~~~~
+
+.. cpp:function:: template<typename BaseType, typename TagType, auto DerivationClause> \
+                  constexpr new_type<BaseType, TagType, DerivationClause> operator+(new_type<BaseType, TagType, DerivationClause> const & lhs, new_type<BaseType, TagType, DerivationClause> const & rhs)
+
+   Add two instances of the same :cpp:class:`new_type`.
+
+   :tparam BaseType: |BaseTypeDoc|
+   :tparam TagType: |TagTypeDoc|
+   :tparam DerivationClause: |DerivationClauseDoc|
+   :param lhs: The left-hand side of the addition
+   :param rhs: The right-hand side of the addition
+   :returns: A new instance of :cpp:class:`new_type\<BaseType, TagType, DerivationClause>` containing the result of applying :literal:`+` to the objects contained by :literal:`lhs` and :literal:`rhs`.
+   :throws: Any exception thrown by the addition operator of the objects contained by :literal:`lhs` and :literal:`rhs`.
+            This operator shall be noexcept iff.
+
+            a. :cpp:type:`new_type::base_type` is *nothrow addable* and
+            b. :cpp:type:`new_type::base_type` is *nothrow copy-constructible*
+
+   :enablement: This operator shall be available iff.
+
+      a. :cpp:type:`new_type::base_type` supports addition using :literal:`+` and
+      b. the :cpp:var:`derivation clause <DerivationClause>` contains :cpp:var:`Arithmetic`
+
+   .. versionadded:: 1.0.0
+
+.. cpp:function:: template<typename BaseType, typename TagType, auto DerivationClause> \
+                  constexpr new_type<BaseType, TagType, DerivationClause> & operator+=(new_type<BaseType, TagType, DerivationClause> & lhs, new_type<BaseType, TagType, DerivationClause> const & rhs)
+
+   Add two instances of the same :cpp:class:`new_type` by overwriting the first one.
+
+   :tparam BaseType: |BaseTypeDoc|
+   :tparam TagType: |TagTypeDoc|
+   :tparam DerivationClause: |DerivationClauseDoc|
+   :param lhs: The left-hand side of the addition
+   :param rhs: The right-hand side of the addition
+   :returns: A reference to the first argument containing the value modified by applying :literal:`+=` to the objects contained by :literal:`lhs` and :literal:`rhs`.
+   :throws: Any exception thrown by the addition-assignment operator of the objects contained by :literal:`lhs` and :literal:`rhs`.
+            This operator shall be noexcept iff.
+
+            a. :cpp:type:`new_type::base_type` is *nothrow add-assignable* and
+            b. :cpp:type:`new_type::base_type` is *nothrow copy-constructible*
+
+   :enablement: This operator shall be available iff.
+
+      a. :cpp:type:`new_type::base_type` supports addition using :literal:`+=` and
+      b. the :cpp:var:`derivation clause <DerivationClause>` contains :cpp:var:`Arithmetic`
+
+   .. versionadded:: 1.0.0
+
+.. cpp:function:: template<typename BaseType, typename TagType, auto DerivationClause> \
+                  constexpr new_type<BaseType, TagType, DerivationClause> operator-(new_type<BaseType, TagType, DerivationClause> const & lhs, new_type<BaseType, TagType, DerivationClause> const & rhs)
+
+   Subtract two instances of the same :cpp:class:`new_type`.
+
+   :tparam BaseType: |BaseTypeDoc|
+   :tparam TagType: |TagTypeDoc|
+   :tparam DerivationClause: |D