diff options
| -rw-r--r-- | doc/src/index.rst | 10 | ||||
| -rw-r--r-- | include/newtype/new_type.hpp | 271 |
2 files changed, 62 insertions, 219 deletions
diff --git a/doc/src/index.rst b/doc/src/index.rst index e8d50d6..17101c9 100644 --- a/doc/src/index.rst +++ b/doc/src/index.rst @@ -180,14 +180,14 @@ Class template :cpp:class:`new_type` .. cpp:function:: constexpr BaseType decay() const - Retrieve the object contained by this :cpp:class:`new_type` object + 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 the object contained by this :cpp:class:`new_type` object + 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*. @@ -443,6 +443,8 @@ Stream I/O Operators 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| @@ -467,6 +469,8 @@ Stream I/O Operators 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| @@ -729,6 +733,8 @@ Iterators :tparam TagType: |TagTypeDoc| :tparam DerivationClause: |DerivationClauseDoc| + Hash an instance of :cpp:class:`new_type` using the hash implementation of the :cpp:type:`base type <BaseType>`. + .. cpp:function:: constexpr std::size operator()(nt::new_type<BaseType, TagType, DerivationClause> const & value) const :param value: A :cpp:class:`nt::new_type` value to be hashed diff --git a/include/newtype/new_type.hpp b/include/newtype/new_type.hpp index ef36a75..0cf6ec3 100644 --- a/include/newtype/new_type.hpp +++ b/include/newtype/new_type.hpp @@ -18,14 +18,7 @@ namespace nt { /** - * @brief Create a new type based on an existing one - * - * The class template nt::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 An existing type that shall aliased - * @tparam TagType A unique type to identify this nt::new_type - * @tparam DervivationClause An nt::derivation_clause describing which features shall be automatically derived for the new type alias + * Create a new type based on an existing one */ template<typename BaseType, typename TagType, auto DerivationClause = deriving()> class new_type @@ -72,96 +65,65 @@ namespace nt using super = impl::new_type_move_assignment<BaseType, TagType>; public: - /// @section Type aliases + /// Member Type Aliases /** - * @brief The base type of this nt::new_type - * - * This type alias provides convenient access to the contained objects type + * The base type of this nt::new_type */ using base_type = BaseType; /** - * @brief The tag type of this nt::new_type - * - * This type alias provides convenient access to the tag type of this nt::new_type instance + * The tag type of this nt::new_type */ using tag_type = TagType; /** - * @brief The type of the derivation clause of this nt::newtype - * - * This type alias provides convenient access to the type of the derivation clause of this nt::new_type instance + * The type of the derivation clause of this nt::newtype */ using derivation_clause_type = decltype(DerivationClause); - /// @section Derivation clause access + /// Static Data Members /** - * @brief The derivation clause fo this nt::new_type - * - * This static data-member provides conevient access to the derivation clause of this nt::new_type instance + * The derivation clause fo this nt::new_type */ auto constexpr static derivation_clause = DerivationClause; - /// @section Constructors + /// Constructors using super::super; /** - * @brief Construct an instance of this nt::new_type by default initializing the contained object - * - * @note This constructor is available iff. the base type is default-constructible. Otherwise is is defined as deleted. - * @throw This constructor throws any exception thrown the base type constructor. It is noexcept iff. the base type constructor is noexcept + * Construct an instance of this nt::new_type by default initializing the contained object */ constexpr new_type() noexcept(std::is_nothrow_default_constructible_v<BaseType>) = default; /** - * @brief Copy-construct an instance of this nt::new_type from an existing one - * - * @note This constructor is available iff. the base type is copy-constructible. Otherwise is is defined as deleted. - * @throw This constructor throws any exception thrown the base type copy-constructor. It is noexcept iff. the base type copy-constructor - * is noexcept + * Copy-construct an instance of this nt::new_type from an existing one */ constexpr new_type(new_type const &) noexcept(std::is_nothrow_copy_constructible_v<BaseType>) = default; /** - * @brief Move-construct an instance of this nt::new_type from an existing one - * - * @note This constructor is available iff. the base type is move-constructible. Otherwise is is defined as deleted. - * @throw This constructor throws any exception thrown the base type move-constructor. It is noexcept iff. the base types move-constructor - * is noexcept + * Move-construct an instance of this nt::new_type from an existing one */ constexpr new_type(new_type &&) noexcept(std::is_nothrow_move_constructible_v<BaseType>) = default; - /// @section Assignment operators + /// Assignment Operators /** - * @brief Copy-assign the value of an existing instance of this nt::new_type to this instance - * - * @note This assignment operator is available iff. the base type is copy-assignable. Otherwise it is defined as deleted. - * @throw This assignment operator throws any exception thrown by the base type copy-assignment operator. It is noexcept iff. the base type - * copy-assignment operator is noexcept. - * @return A reference to this instance + * Copy-assign the value of an existing instance of this nt::new_type to this instance */ auto constexpr operator=(new_type const &) noexcept(std::is_nothrow_copy_assignable_v<BaseType>) -> new_type & = default; /** - * @brief Move-assign the value of an existing instance of this nt::new_type to this instance - * - * @note This assignment operator is available iff. the base type is move-assignable. Otherwise it is defined as deleted. - * @throw This assignment operator throws any exception thrown by the base type move-assignment operator. It is noexcept iff. the base type - * move-assignment operator is noexcept. - * @return A reference to this instance + * Move-assign the value of an existing instance of this nt::new_type to this instance */ auto constexpr operator=(new_type &&) noexcept(std::is_nothrow_move_assignable_v<BaseType>) -> new_type & = default; - /// @section Accessors + /// Accessors /** - * @brief Obtain a copy of the contained base type object - * - * @return BaseType + * Retrieve a copy of the object contained by this new_type object */ auto constexpr decay() const noexcept(std::is_nothrow_copy_constructible_v<BaseType>) -> BaseType { @@ -169,9 +131,7 @@ namespace nt } /** - * @brief Convert this instance into the equivalent base type value - * - * @note This is only available if the derivation clause of this nt::new_type contains nt::ImplicitConversion + * Retrieve a copy of the object contained by this new_type object */ template<typename NewType = new_type, std::enable_if_t<NewType::derivation_clause(nt::ImplicitConversion)> * = nullptr> constexpr operator base_type() const noexcept(std::is_nothrow_copy_constructible_v<base_type>) @@ -180,9 +140,7 @@ namespace nt } /** - * @brief Convert this instance into the equivalent base type value - * - * @note This overload is only avalaible if the derivation clause of this nt::new_type does not contain nt::ImplicitConversion + * Convert this instance into the equivalent base type value */ template<typename NewType = new_type, std::enable_if_t<!NewType::derivation_clause(nt::ImplicitConversion)> * = nullptr> explicit constexpr operator base_type() const noexcept(std::is_nothrow_copy_constructible_v<base_type>) @@ -190,12 +148,10 @@ namespace nt return decay(); } - /// @section Indirection operators + /// Member Access Through Pointer /** - * @brief Perform an access to a member of the base type - * - * @return A pointer to the contained base type object + * Perform "member access through pointer" via a pointer to object contained by this new_type */ template<typename NewType = new_type> auto constexpr operator-> () noexcept -> std::enable_if_t<NewType::derivation_clause(nt::Indirection), BaseType *> @@ -204,9 +160,7 @@ namespace nt } /** - * @brief Perform an access to a member of the base type - * - * @return A pointer to the contained base type object + * Perform "member access through pointer" via a pointer to object contained by this new_type */ template<typename NewType = new_type> auto constexpr operator-> () const noexcept -> std::enable_if_t<NewType::derivation_clause(nt::Indirection), BaseType const *> @@ -214,13 +168,10 @@ namespace nt return std::addressof(this->m_value); } - /// @section Iterators + /// Iterators /** - * @brief Get the begin iterator of the base type - * - * @return An iterator to the beginning of the base type sequence - * @throw Any exception thrown by the overload of 'begin' selected + * Get an iterator to the beginning of the object contained by this new_type */ template<typename NewType = new_type, std::enable_if_t<NewType::derivation_clause(nt::Iterable)> * = nullptr> auto constexpr begin() @@ -230,11 +181,7 @@ namespace nt } /** - * @brief Get the begin iterator of the base type - * - * @note Overload for constant instances - * @return An iterator to the beginning of the base type sequence - * @throw Any exception thrown by the overload of 'begin' selected + * Get an iterator to the beginning of the object contained by this new_type */ template<typename NewType = new_type> auto constexpr begin() const -> std::enable_if_t<NewType::derivation_clause(nt::Iterable) && impl::has_member_begin_v<BaseType const>, @@ -244,14 +191,10 @@ namespace nt } }; - /// @section Equality comparison operators + /// Equality Comparison Operators /** - * @brief Compare two objects for equality - * - * @throw This comparison operator throws any exception thrown by the base type comparison operator. It it noexcept iff. the base type - * comparison operator is noexcept. - * @return true iff. the base type comparison operator returns true, false otherwise. + * Check two instances of new_type<BaseType, TagType, DerivationClause> for equality */ template<typename BaseType, typename TagType, auto DerivationClause> auto constexpr @@ -263,11 +206,7 @@ namespace nt } /** - * @brief Compare an instance of a given nt::new_type with an object of its base type - * - * @throw This comparison operator throws any exception thrown by the base type comparison operator. It it noexcept iff. the base type - * comparison operator is noexcept. - * @return true iff. the base type comparison operator returns true, false otherwise. + * Check an instance of new_type<BaseType, TagType, DerivationClause> for equality with an instance of BaseType */ template<typename BaseType, typename TagType, auto DerivationClause> auto constexpr operator==(new_type<BaseType, TagType, DerivationClause> const & lhs, @@ -278,11 +217,7 @@ namespace nt } /** - * @brief Compare an instance of the base type with an instance of a given nt::new_type - * - * @throw This comparison operator throws any exception thrown by the base type comparison operator. It it noexcept iff. the base type - * comparison operator is noexcept. - * @return true iff. the base type comparison operator returns true, false otherwise. + * Check an instance of BaseType for equality with an instance of new_type<BaseType, TagType, DerivationClause> */ template<typename BaseType, typename TagType, auto DerivationClause> auto constexpr @@ -294,11 +229,7 @@ namespace nt } /** - * @brief Compare two objects for non-equality - * - * @throw This comparison operator throws any exception thrown by the base type comparison operator. It it noexcept iff. the base type - * comparison operator is noexcept. - * @return true iff. the base type comparison operator returns true, false otherwise. + * Check two instances of new_type<BaseType, TagType, DerivationClause> for in-equality */ template<typename BaseType, typename TagType, auto DerivationClause> auto constexpr @@ -310,11 +241,7 @@ namespace nt } /** - * @brief Compare an instance of a given nt::new_type with an object of its base type - * - * @throw This comparison operator throws any exception thrown by the base type comparison operator. It it noexcept iff. the base type - * comparison operator is noexcept. - * @return true iff. the base type comparison operator returns true, false otherwise. + * Check an instance of new_type<BaseType, TagType, DerivationClause> for in-equality with an instance of BaseType */ template<typename BaseType, typename TagType, auto DerivationClause> auto constexpr operator!=(new_type<BaseType, TagType, DerivationClause> const & lhs, @@ -325,11 +252,7 @@ namespace nt } /** - * @brief Compare an instance of the base type with an instance of a given nt::new_type - * - * @throw This comparison operator throws any exception thrown by the base type comparison operator. It it noexcept iff. the base type - * comparison operator is noexcept. - * @return true iff. the base type comparison operator returns true, false otherwise. + * Check an instance of BaseType for in-equality with an instance of new_type<BaseType, TagType, DerivationClause> */ template<typename BaseType, typename TagType, auto DerivationClause> auto constexpr @@ -340,16 +263,10 @@ namespace nt return lhs != rhs.decay(); } - /// @section Relational operators + /// Relational Comparison Operators /** - * @brief Check if one nt::new_type object is less-than an other - * - * @note This operator is only available if the the derivation clause of this nt::new_type does contains nt::Relational and the base type is - * less-than comparable. - * @throw This comparison operator throws any exception thrown by the base type comparison operator. It it noexcept iff. the base type - * comparison operator is noexcept. - * @return true iff. the base type comparison operator returns true, false otherwise. + * Compare two instances of the same new_type using '<' (less-than) */ template<typename BaseType, typename TagType, auto DerivationClause> auto constexpr @@ -361,13 +278,7 @@ namespace nt } /** - * Check if one nt::new_type object is greater-than an other - * - * @note This operator is only available if the the derivation clause of this nt::new_type does contains nt::Relational and the base type is - * greater-than comparable. - * @throw This comparison operator throws any exception thrown by the base type comparison operator. It it noexcept iff. the base type - * comparison operator is noexcept. - * @return true iff. the base type comparison operator returns true, false otherwise. + * Compare two instances of the same new_type using '>' (greater-than) */ template<typename BaseType, typename TagType, auto DerivationClause> auto constexpr @@ -379,13 +290,7 @@ namespace nt } /** - * Check if one nt::new_type object is less-than or equal-to an other - * - * @note This operator is only available if the the derivation clause of this nt::new_type does contains nt::Relational and the base type is - * less-than-or-equal-to comparable. - * @throw This comparison operator throws any exception thrown by the base type comparison operator. It it noexcept iff. the base type - * comparison operator is noexcept. - * @return true iff. the base type comparison operator returns true, false otherwise. + * Compare two instances of the same new_type using '<=' (less-than-equal) */ template<typename BaseType, typename TagType, auto DerivationClause> auto constexpr @@ -397,13 +302,7 @@ namespace nt } /** - * Check if one nt::new_type object is greater-than or equal-to an other - * - * @note This operator is only available if the the derivation clause of this nt::new_type does contains nt::Relational and the base type is - * greater-than-or-equal comparable - * @throw This comparison operator throws any exception thrown by the base type comparison operator. It it noexcept iff. the base type - * comparison operator is noexcept. - * @return true iff. the base type comparison operator returns true, false otherwise. + * Compare two instances of the same new_type using '>=' (greater-than-equal) */ template<typename BaseType, typename TagType, auto DerivationClause> auto constexpr @@ -414,15 +313,10 @@ namespace nt return lhs.decay() >= rhs.decay(); } - /// @section Stream input/output operators + /// Stream I/O Operators /** - * @brief Write the contained base type object to a standard output stream - * - * @note This operator is only available if the derivation clause of the passed in nt::new_type object contains nt::Show. - * @param output The output stream to write to - * @param source An instance of an nt::new_type that shall be written to the stream - * @return The a reference to the output stream + * Write an instance of new_type<BaseType, TagType, DerivationClause> to a standard ostream */ template<typename BaseType, typename TagType, auto DerivationClause, typename CharType, typename StreamTraits> auto operator<<(std::basic_ostream<CharType, StreamTraits> & output, new_type<BaseType, TagType, DerivationClause> const & source) noexcept( @@ -434,12 +328,7 @@ namespace nt } /** - * @brief Read an object of the base type from a standard input stream - * - * @note This operator is only available if the derivation clause of the passed in nt::new_type object contains nt::Read. - * @param output The input stream to read from - * @param source An instance of an nt::new_type that shall be read from the stream - * @return The a reference to the input stream + * Read an instance of new_type<BaseType, TagType, DerivationClause> from the a standard istream */ template<typename BaseType, typename TagType, auto DerivationClause, typename CharType, typename StreamTraits> auto operator>>(std::basic_istream<CharType, StreamTraits> & input, new_type<BaseType, TagType, DerivationClause> & target) noexcept( @@ -450,16 +339,10 @@ namespace nt return input >> target.m_value; } - /// @section Arithmetic operators + /// Arithmetic Operators /** - * @brief Add two instances of the same nt::new_type - * - * @note This operator is only available if the derivation clause of the passed in nt::new_type objects contains nt::Arithmetic and the base - * type is addable. - * @param lhs The left-hand side of the addition - * @param rhs The right-hand side of the addition - * @return a new instance of the same nt::new_type + * Add two instances of the same new_type */ template<typename BaseType, typename TagType, auto DerivationClause> auto constexpr @@ -471,13 +354,7 @@ namespace nt } /** - * @brief Add two instances of the same nt::new_type, modifying the left-hand side - * - * @note This operator is only available if the derivation clause of the passed in nt::new_type objects contains nt::Arithmetic and the base - * type is addable. - * @param lhs The left-hand side of the addition - * @param rhs The right-hand side of the addition - * @return a reference to the the modified value + * Add two instances of the same new_type by overwriting the first one */ template<typename BaseType, typename TagType, auto DerivationClause> auto constexpr operator+=(new_type<BaseType, TagType, DerivationClause> & lhs, @@ -490,13 +367,7 @@ namespace nt } /** - * @brief Subtract two instances of the same nt::new_type - * - * @note This operator is only available if the derivation clause of the passed in nt::new_type objects contains nt::Arithmetic and the base - * type is subtractable. - * @param lhs The left-hand side of the subtraction - * @param rhs The right-hand side of the subtraction - * @return a new instance of the same nt::new_type + * Subtract two instances of the same new_type */ template<typename BaseType, typename TagType, auto DerivationClause> auto constexpr @@ -508,13 +379,7 @@ namespace nt } /** - * @brief Subtract two instances of the same nt::new_type, modifying the left-hand side - * - * @note This operator is only available if the derivation clause of the passed in nt::new_type objects contains nt::Arithmetic and the base - * type is subtractable. - * @param lhs The left-hand side of the subtractition - * @param rhs The right-hand side of the subtractition - * @return a reference to the the modified value + * Subtract two instances of the same new_type by overwriting the first one */ template<typename BaseType, typename TagType, auto DerivationClause> auto constexpr @@ -528,13 +393,7 @@ namespace nt } /** - * @brief Multiply two instances of the same nt::new_type - * - * @note This operator is only available if the derivation clause of the passed in nt::new_type objects contains nt::Arithmetic and the base - * type is multipliable. - * @param lhs The left-hand side of the multiplication - * @param rhs The right-hand side of the multiplication - * @return a new instance of the same nt::new_type + * Multiply two instances of the same new_type */ template<typename BaseType, typename TagType, auto DerivationClause> auto constexpr @@ -546,13 +405,7 @@ namespace nt } /** - * @brief Multiply two instances of the same nt::new_type, modifying the left-hand side - * - * @note This operator is only available if the derivation clause of the passed in nt::new_type objects contains nt::Arithmetic and the base - * type is multiplyable. - * @param lhs The left-hand side of the multiplication - * @param rhs The right-hand side of the multiplication - * @return a reference to the the modified value + * Multiply two instances of the same new_type by overwriting the first one */ template<typename BaseType, typename TagType, auto DerivationClause> auto constexpr @@ -566,13 +419,7 @@ namespace nt } /** - * @brief Divide two instances of the same nt::new_type - * - * @note This operator is only available if the derivation clause of the passed in nt::new_type objects contains nt::Arithmetic and the base - * type is dividable. - * @param lhs The left-hand side of the division - * @param rhs The right-hand side of the division - * @return a new instance of the same nt::new_type + * Divide two instances of the same nt::new_type */ template<typename BaseType, typename TagType, auto DerivationClause> auto constexpr @@ -584,13 +431,7 @@ namespace nt } /** - * @brief Divide two instances of the same nt::new_type, modifying the left-hand side - * - * @note This operator is only available if the derivation clause of the passed in nt::new_type objects contains nt::Arithmetic and the base - * type is dividable. - * @param lhs The left-hand side of the division - * @param rhs The right-hand side of the division - * @return a reference to the the modified value + * Divide two instances of the same new_type by overwriting the first one */ template<typename BaseType, typename TagType, auto DerivationClause> auto constexpr operator/=(new_type<BaseType, TagType, DerivationClause> & lhs, @@ -602,13 +443,10 @@ namespace nt return lhs; } - /// @section Free Iterator Accessors + /// Iterators /** - * @brief Get the begin iterator of the base type - * - * @return An iterator to the beginning of the base type sequence - * @throw Any exception thrown by the overload of 'begin' selected + * Get an iterator to the beginning of the object contained by an instance of new_type */ template<typename BaseType, typename TagType, auto DerivationClause, typename NewType = new_type<BaseType, TagType, DerivationClause>> auto constexpr begin(new_type<BaseType, TagType, DerivationClause> & obj) @@ -618,11 +456,7 @@ namespace nt } /** - * @brief Get the begin iterator of the base type - * - * @note Overload for constant instances - * @return An iterator to the beginning of the base type sequence - * @throw Any exception thrown by the overload of 'begin' selected + * Get a constant iterator to the beginning of the object contained by an instance of new_type */ template<typename BaseType, typename TagType, auto DerivationClause, typename NewType = new_type<BaseType, TagType, DerivationClause>> auto constexpr begin(new_type<BaseType, TagType, DerivationClause> const & obj) @@ -635,6 +469,9 @@ namespace nt namespace std { + /** + * Hash an instance of new_type using the hash implementation of the base type + */ template<typename BaseType, typename TagType, auto DerivationClause> struct hash<nt::new_type<BaseType, TagType, DerivationClause>> { |