From 4d1b14ab52d7f0ba24b2a1383476a60031f6f87c Mon Sep 17 00:00:00 2001 From: Felix Morgner Date: Sat, 28 Dec 2019 14:56:44 +0100 Subject: doc: rename master document to index --- doc/src/conf.py | 2 +- doc/src/index.rst | 206 +++++++++++++++++++++++++++++++++++++++++++++++++++ doc/src/new_type.rst | 206 --------------------------------------------------- 3 files changed, 207 insertions(+), 207 deletions(-) create mode 100644 doc/src/index.rst delete mode 100644 doc/src/new_type.rst (limited to 'doc') diff --git a/doc/src/conf.py b/doc/src/conf.py index d76c856..230960d 100644 --- a/doc/src/conf.py +++ b/doc/src/conf.py @@ -14,7 +14,7 @@ release = '1.0.0' # -- General configuration --------------------------------------------------- -master_doc = 'new_type' +master_doc = 'index' extensions = [ 'sphinx.ext.todo', diff --git a/doc/src/index.rst b/doc/src/index.rst new file mode 100644 index 0000000..41f9675 --- /dev/null +++ b/doc/src/index.rst @@ -0,0 +1,206 @@ +############# +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:: c++ + + namespace nt + { + template + class new_type + { + public: + + // Type aliases + + using base_type = BaseType; + using tag_type = TagType; + using derivation_clause_type = decltype(DerivationClause); + + // Derivation clause access + + auto constexpr static derivation_clause = DerivationClause; + + // 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; // exposition only + }; + + // 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; + + // Stream input/output operators + + template + auto operator<<(std::basic_ostream &&, + new_type const &) noexcept(/*see below*/) + -> std::basic_ostream &; + + template + auto operator>>(std::basic_istream &&, + new_type &&) noexcept(/*see below*/) + -> std::basic_istream &; + } + +Member Type Aliases +~~~~~~~~~~~~~~~~~~~ + +Static Data Members +~~~~~~~~~~~~~~~~~~~ + +Special Member Functions +~~~~~~~~~~~~~~~~~~~~~~~~ + +Free Equality Comparison Operators +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Free Relational Operators +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Free Stream Input/Ouput Operators +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Unit Tests +========== diff --git a/doc/src/new_type.rst b/doc/src/new_type.rst deleted file mode 100644 index 41f9675..0000000 --- a/doc/src/new_type.rst +++ /dev/null @@ -1,206 +0,0 @@ -############# -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:: c++ - - namespace nt - { - template - class new_type - { - public: - - // Type aliases - - using base_type = BaseType; - using tag_type = TagType; - using derivation_clause_type = decltype(DerivationClause); - - // Derivation clause access - - auto constexpr static derivation_clause = DerivationClause; - - // 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; // exposition only - }; - - // 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; - - // Stream input/output operators - - template - auto operator<<(std::basic_ostream &&, - new_type const &) noexcept(/*see below*/) - -> std::basic_ostream &; - - template - auto operator>>(std::basic_istream &&, - new_type &&) noexcept(/*see below*/) - -> std::basic_istream &; - } - -Member Type Aliases -~~~~~~~~~~~~~~~~~~~ - -Static Data Members -~~~~~~~~~~~~~~~~~~~ - -Special Member Functions -~~~~~~~~~~~~~~~~~~~~~~~~ - -Free Equality Comparison Operators -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Free Relational Operators -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Free Stream Input/Ouput Operators -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Unit Tests -========== -- cgit v1.2.3