diff --git a/docs/users_guide/framework_basics/concepts.md b/docs/users_guide/framework_basics/concepts.md index e13626e5..477a2f80 100644 --- a/docs/users_guide/framework_basics/concepts.md +++ b/docs/users_guide/framework_basics/concepts.md @@ -53,6 +53,15 @@ All of the above quantity specifications have to be marked as `final`. and when `T` is implicitly convertible to `V`. +## `UnitMagnitude` { #UnitMagnitude } + +`UnitMagnitude` concept is satisfied by all types defining a unit magnitude. + +!!! info + + Unit magnitude implementation is a private implementation detail of the library. + + ## `Unit` { #Unit } `Unit` concept matches all the [units](../../appendix/glossary.md#unit) in the library including: @@ -126,49 +135,24 @@ A `Reference` can either be: [`QuantitySpecOf`](#QuantitySpecOf) concept. -## `Representation` { #Representation } - -`Representation` concept constraints a type of a number that stores the -[value of a quantity](../../appendix/glossary.md#quantity-value). - - ### `RepresentationOf` { #RepresentationOf } -`RepresentationOf` concept is satisfied: +`RepresentationOf` concept constraints a type of a number that stores the +[value of a quantity](../../appendix/glossary.md#quantity-value) and is satisfied: - if the type of `V` satisfies [`QuantitySpec`](#QuantitySpec): - - by all [`Representation`](#Representation) types when `V` describes + - by all representation types when `V` describes a [quantity kind](../../appendix/glossary.md#kind), - - otherwise, by [`Representation`](#Representation) types that are of + - otherwise, by representation types that are of a [quantity character](../../appendix/glossary.md#character) associated with a provided quantity specification `V`. - if `V` is of `quantity_character` type: - - by [`Representation`](#Representation) types that are of a provided + - by representation types that are of a provided [quantity character](../../appendix/glossary.md#character). -A user can declare a custom representation type to be of a specific character by providing the specialization -with `true` for one or more of the following variable templates: - -- `is_scalar` -- `is_complex` -- `is_vector` -- `is_tensor` - - -??? tip - - If we want to use scalar types to also express [vector quantities](character_of_a_quantity.md#defining-vector-and-tensor-quantities) - (e.g., ignoring the "direction" of the vector) the following definition can be provided to enable such a behavior: - - ```cpp - template - requires mp_units::is_scalar - constexpr bool mp_units::is_vector = true; - ``` - ## `Quantity` { #Quantity } @@ -182,6 +166,49 @@ satisfied by all types being or deriving from an instantiation of a `quantity` c is `true`. +### `QuantityLike` { #QuantityLike } + +`QuantityLike` concept provides interoperability with other libraries and is satisfied by a type `T` +for which an instantiation of `quantity_like_traits` type trait yields a valid type that provides: + +- `reference` static data member that matches the [`Reference`](#Reference) concept, +- `rep` type that matches [`RepresentationOf`](#RepresentationOf) concept with the character provided + in `reference`, +- `explicit_import` static data member convertible to `bool` that specifies that the conversion + from `T` to a `quantity` type should happen explicitly (if `true`), +- `explicit_export` static data member convertible to `bool` that specifies that the conversion + from a `quantity` type to `T` should happen explicitly (if `true`), +- `to_numerical_value(T)` static member function returning a raw value of the quantity, +- `from_numerical_value(rep)` static member function returning `T`. + +??? abstract "Examples" + + This is how support for `std::chrono::seconds` can be provided: + + ```cpp + template<> + struct mp_units::quantity_like_traits { + static constexpr auto reference = si::second; + static constexpr bool explicit_import = false; + static constexpr bool explicit_export = false; + using rep = std::chrono::seconds::rep; + + [[nodiscard]] static constexpr rep to_numerical_value(const std::chrono::seconds& d) + { + return d.count(); + } + + [[nodiscard]] static constexpr std::chrono::seconds from_numerical_value(const rep& v) + { + return std::chrono::seconds(v); + } + }; + + quantity q = 42s; + std::chrono::seconds dur = 42 * s; + ``` + + ## `PointOrigin` { #PointOrigin } `PointOrigin` concept matches all [quantity point origins](../../appendix/glossary.md#point-origin) in @@ -231,50 +258,7 @@ class template. | `PointOrigin` | The _point_ and `V` have the same absolute point origin. | -## `QuantityLike` { #QuantityLike } - -`QuantityLike` concept provides interoperability with other libraries and is satisfied by a type `T` -for which an instantiation of `quantity_like_traits` type trait yields a valid type that provides: - -- `reference` static data member that matches the [`Reference`](#Reference) concept, -- `rep` type that matches [`RepresentationOf`](#RepresentationOf) concept with the character provided - in `reference`, -- `explicit_import` static data member convertible to `bool` that specifies that the conversion - from `T` to a `quantity` type should happen explicitly (if `true`), -- `explicit_export` static data member convertible to `bool` that specifies that the conversion - from a `quantity` type to `T` should happen explicitly (if `true`), -- `to_numerical_value(T)` static member function returning a raw value of the quantity, -- `from_numerical_value(rep)` static member function returning `T`. - -??? abstract "Examples" - - This is how support for `std::chrono::seconds` can be provided: - - ```cpp - template<> - struct mp_units::quantity_like_traits { - static constexpr auto reference = si::second; - static constexpr bool explicit_import = false; - static constexpr bool explicit_export = false; - using rep = std::chrono::seconds::rep; - - [[nodiscard]] static constexpr rep to_numerical_value(const std::chrono::seconds& d) - { - return d.count(); - } - - [[nodiscard]] static constexpr std::chrono::seconds from_numerical_value(const rep& v) - { - return std::chrono::seconds(v); - } - }; - - quantity q = 42s; - std::chrono::seconds dur = 42 * s; - ``` - - -## `QuantityPointLike` { #QuantityPointLike } +### `QuantityPointLike` { #QuantityPointLike } `QuantityPointLike` concept provides interoperability with other libraries and is satisfied by a type `T` for which an instantiation of `quantity_point_like_traits` type trait yields a valid type that provides: