diff --git a/docs/_static/img/concepts.png b/docs/_static/img/concepts.png index 31b56e8e..37677310 100644 Binary files a/docs/_static/img/concepts.png and b/docs/_static/img/concepts.png differ diff --git a/docs/conf.py b/docs/conf.py index bb94e896..be014700 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -294,6 +294,10 @@ nitpicky = True # or ('envvar', 'LD_LIBRARY_PATH'). nitpick_ignore = [] +# True to prefix each section label with the name of the document it is in, +# followed by a colon. Useful for avoiding ambiguity when the same section +# heading appears in different documents. +autosectionlabel_prefix_document = True # -- C++ configuration --------------------------------------------------- diff --git a/docs/design/directories.rst b/docs/design/directories.rst index 954058ec..77b121cc 100644 --- a/docs/design/directories.rst +++ b/docs/design/directories.rst @@ -57,7 +57,7 @@ Library Directories Structure .. seealso:: More information on provided :term:`systems of units ` can be - found in :ref:`Systems` chapter. + found in :ref:`reference/systems:Systems` chapter. .. important:: diff --git a/docs/faq.rst b/docs/faq.rst index 29b017aa..e2836e49 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -39,7 +39,8 @@ of units of the same physical dimension between different systems. .. seealso:: - More details on this subject can be found in the :ref:`Custom Systems` chapter. + More details on this subject can be found in the + :ref:`use_cases/extensions:Custom Systems` chapter. Why a dimensionless quantity is not just an fundamental arithmetic type? @@ -66,8 +67,8 @@ This is why it was decided to go with the current approach. .. seealso:: - More information on the current design can be found in :ref:`Dimensionless quantities` - chapter. + More information on the current design can be found in + the :ref:`framework/quantities:Dimensionless Quantities` chapter. Why do we spell ``metre`` instead of ``meter``? @@ -114,7 +115,7 @@ to obey the rules and be consistent with ISO specifications. .. seealso:: We do understand engineering reality and constraints and that is why the library - has the option of :ref:`ASCII-only quantity symbols`. + has the option of :ref:`framework/text_output:ASCII-only quantity symbols`. Compilation Errors @@ -124,6 +125,7 @@ error: reference to ‘time’ is ambiguous ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Unfortunately, if `using-directives `_ -(i.e. ``using namespace units::physical::si``) are being used, `units::physical::si::time` will -collide with C `time `_ function. In such a case the library's -``time`` function needs to be prefixed with at least one (or all) namespace names. +(i.e. ``using namespace units::physical::si``) are being used, `units::physical::si::time` +will collide with C `time `_ function. In +such a case the library's ``time`` function needs to be prefixed with at least one (or all) +namespace names. diff --git a/docs/framework/basic_concepts.rst b/docs/framework/basic_concepts.rst index f2561ea7..6c11c7ae 100644 --- a/docs/framework/basic_concepts.rst +++ b/docs/framework/basic_concepts.rst @@ -45,7 +45,7 @@ The most important concepts in the library are `Unit`, `Dimension`, [PointKind]<-[QuantityPointKind] [Kind]<-[PointKind] - [QuantityKind]-<[QuantityPointKind] + [QuantityKind]<-[QuantityPointKind] `Unit` is a basic building block of the library. Every dimension works with a concrete hierarchy of units. Such hierarchy defines a reference unit and diff --git a/docs/framework/conversions_and_casting.rst b/docs/framework/conversions_and_casting.rst index 7f6deaac..6ce8346a 100644 --- a/docs/framework/conversions_and_casting.rst +++ b/docs/framework/conversions_and_casting.rst @@ -55,8 +55,7 @@ Implicit conversions are allowed only across quantities of the same dimension: Explicit -------- -Explicit conversions are available with -the `quantity_cast`, `quantity_point_cast`, +Explicit conversions are available with the `quantity_cast`, `quantity_point_cast`, `quantity_kind_cast`, and `quantity_point_kind_cast` function templates. They are especially useful to force a truncating conversion across quantities of the same dimension for integral representation types and ratios that may cause precision loss:: @@ -66,9 +65,9 @@ dimension for integral representation types and ratios that may cause precision .. seealso:: - Explicit casts are also really useful when working with legacy interfaces. More - information on this subject can be found in :ref:`Working with Legacy Interfaces` - chapter. + Explicit casts are also really useful when working with legacy interfaces. + More information on this subject can be found in the + :ref:`use_cases/legacy_interfaces:Working with Legacy Interfaces` chapter. Quantity Cast Overloads ^^^^^^^^^^^^^^^^^^^^^^^ @@ -109,17 +108,18 @@ accept a `PointKind` and `Kind` instead of a `Dimension`, respectively. .. seealso:: - For more information on conversion and casting and on how to extend the above "integral" - vs "floating-point" logic please refer to the :ref:`Using Custom Representation Types` - chapter. + For more information on conversion and casting and on how to extend the above + "integral" vs "floating-point" logic please refer to the + :ref:`use_cases/custom_representation_types:Using Custom Representation Types` chapter. Implicit conversions of dimensionless quantities ------------------------------------------------ -As noted in the :ref:`Dimensionless Quantities` chapter, :term:`quantity of dimension one` -is somehow special but still obey most of the rules defined for quantities. However, as they -represent numbers it would be highly uncomfortable to every time type:: +As noted in the :ref:`framework/quantities:Dimensionless Quantities` chapter, +:term:`quantity of dimension one` is somehow special but still obey most of the rules defined +for quantities. However, as they represent numbers it would be highly uncomfortable to every +time type:: const auto d1 = 10_q_km; const auto d2 = 3_q_km; diff --git a/docs/framework/dimensions.rst b/docs/framework/dimensions.rst index 279f83a6..bde6378a 100644 --- a/docs/framework/dimensions.rst +++ b/docs/framework/dimensions.rst @@ -8,8 +8,11 @@ In the previous chapter we briefly introduced the notion of a physical Length, time, speed, area, energy are only a few examples of physical dimensions. -Operations ----------- +Arithmetics +----------- + +Quantities +++++++++++ Quantities of the same dimension can be easily added or subtracted with each other and the result will always be a quantity of the same dimension: @@ -61,24 +64,32 @@ dimension, than we will end up with just a dimensionless quantity: Dimensionless auto v1 = dur1 / dur2; // quantity(5) Dimensionless auto v2 = dur1 * fr1; // quantity(50) -Quantity kinds behave the same as quantities for addition, substraction, and -multiplication with, and division by a :term:`scalable number`. +Quantity Kinds +++++++++++++++ -Multiplication and divison with a quantity -(but not a quantity kind) is allowed. -The result is a quantity kind with the appropiate dimension -and related to the original quantity kind. +Quantity kinds behave the same as quantities for addition and subtraction. +The same behavior is also provided for multiplication with, and division by +a :term:`scalable number`. + +Multiplication and division with a quantity (but not a quantity kind) is allowed. +The result is a quantity kind with the appropriate dimension +and related to the original quantity kind: + +.. code-block:: + :emphasize-lines: 5-6 struct height : kind {}; struct rate_of_climb : derived_kind {}; quantity_kind h(height{}, 100 * m); quantity_point_kind rate = h / (25 * s); - // `quantity_point_kind(4 * m / s)` + // quantity_point_kind(4 * m / s) + +Quantity Points ++++++++++++++++ Quantity points have a more restricted set of operations. -Quantity points can't be added together, -but can be added to or subtracted from quantities. +Quantity can be added to or subtracted from a quantity point. The result will always be a quantity point of the same dimension: .. code-block:: @@ -90,17 +101,6 @@ The result will always be a quantity point of the same dimension: QuantityPoint auto res2 = dist1 + quantity_point{dist2}; QuantityPoint auto res3 = quantity_point{dist1} - dist2; -.. note:: - - You can't subtract a quantity from a quantity point: - - .. code-block:: - :emphasize-lines: 3 - - Length auto dist1 = 2_q_m; - Length auto dist2 = 1_q_m; - auto res1 = dist1 - quantity_point{dist2}; // ERROR - We can also subtract two quantity points. The result is a relative quantity of the same dimension: @@ -111,7 +111,25 @@ The result is a relative quantity of the same dimension: Length auto dist2 = 1_q_m; Length auto res1 = quantity_point{dist1} - quantity_point{dist2}; -That's it! You can't multiply nor divide quantity points with anything else. +.. note:: + + It is not allowed to: + + - add quantity points + - subtract a quantity point from a quantity: + - multiply nor divide quantity points with anything else. + + .. code-block:: + :emphasize-lines: 3-5 + + Length auto dist1 = 2_q_m; + Length auto dist2 = 1_q_m; + auto res1 = quantity_point{dist1} + quantity_point{dist2}; // ERROR + auto res2 = dist1 - quantity_point{dist2}; // ERROR + auto res3 = quantity_point{dist1} / 2_q_s; // ERROR + +Quantity Point Kinds +++++++++++++++++++++ The same restrictions of a quantity point with respect to its quantity apply to a quantity point kind with respect to its quantity kind. @@ -185,7 +203,8 @@ an dimension's unnamed unit symbol is being printed in the text output. .. seealso:: More information on how the :term:`recipe` affect the printed symbol - of unnamed unit can be found in the :ref:`Derived Unnamed Units` chapter. + of unnamed unit can be found in the :ref:`framework/units:Derived Unnamed Units` + chapter. It is important to mention here that beside text output the order and the number of elements in the `derived_dimension` definition does not @@ -213,7 +232,8 @@ analysis in the library to work as expected. child class inherited from the instantiation of this `derived_dimension` class template. This is called a :abbr:`CRTP (Curiously Recurring Template Parameter)` Idiom and is used - in many places in this library to provide :ref:`The Downcasting Facility`. + in many places in this library to provide + :ref:`design/downcasting:The Downcasting Facility`. Hopefully if [P0847]_ will land in C++23 the additional CRTP-related template parameter will be removed from this definition. diff --git a/docs/framework/quantities.rst b/docs/framework/quantities.rst index d89726f7..ab909437 100644 --- a/docs/framework/quantities.rst +++ b/docs/framework/quantities.rst @@ -7,7 +7,6 @@ A :term:`quantity` is a concrete amount of a unit for a specified dimension with a specific representation and is represented in the library with a `quantity` class template. -.. _quantity-construction: Construction ------------ @@ -198,6 +197,7 @@ The above code can be fixed in one of the below ways: inline constexpr auto km_per_h = km / h; Speed auto v = 220 / 2 * km_per_h; + Dimension-specific Concepts --------------------------- @@ -266,8 +266,8 @@ units like CGS. .. seealso:: - Please refer to :ref:`avg_speed` example for more information on different - kinds of interfaces supported by the library. + Please refer to :ref:`examples/avg_speed:avg_speed` example for more + information on different kinds of interfaces supported by the library. Working With Constrained Deduced Quantity Types @@ -295,8 +295,8 @@ but often we would like to know a specific type too. We have two options here: .. seealso:: - More information on this subject can be found in :ref:`Conversions and Casting` - chapter. + More information on this subject can be found in the + :ref:`framework/conversions_and_casting:Conversions and Casting` chapter. Dimensionless Quantities @@ -315,7 +315,7 @@ are zero". .. seealso:: Reasoning for the above design is provided in - :ref:`Why a dimensionless quantity is not just an fundamental arithmetic type?` + :ref:`faq:Why a dimensionless quantity is not just an fundamental arithmetic type?` To simplify the usage of the dimensionless quantity a following concept and alias template are provided:: @@ -351,5 +351,6 @@ is expressed as a ratio of kilometers and megaparsecs. .. seealso:: - More information on dimensionless quantities can be found in - :ref:`Implicit conversions of dimensionless quantities`. + More information on dimensionless quantities can be found in the + :ref:`framework/conversions_and_casting:Implicit conversions of dimensionless quantities` + chapter. diff --git a/docs/framework/quantity_kinds.rst b/docs/framework/quantity_kinds.rst index df347c7f..73528afd 100644 --- a/docs/framework/quantity_kinds.rst +++ b/docs/framework/quantity_kinds.rst @@ -7,16 +7,14 @@ A quantity kind is a quantity of more specific usage. It is represented in the library with a `quantity_kind` class template. -.. _quantity-point-construction: - -Kind creation +Kind Creation ------------- We need a `kind` to represent the more specific usage of a quantity:: struct radius : kind {}; -Quantities of kind `radius` represent a radius. +Quantities of kind ``radius`` represent a radius. They are clearly distinct from more generic usages of length quantities. @@ -40,23 +38,26 @@ the value to the `quantity_kind` class template constructor:: quantity_kind d = 123 * km; // ERROR -Differences to quantity +Differences To Quantity ----------------------- Unlike `quantity`, the library provides: - no kinds, such as ``radius`` or ``width``, therefore + * no UDLs or unit constants, * no kind-specific concepts, such as ``Radius``, (there's the generic `QuantityKind` and kind-specifiable `QuantityKindOf`), + - a slightly different set of operations on quantity kinds - (see the :ref:`Dimensions` chapter). + (see the :ref:`framework/dimensions:Quantity Kinds` chapter). -Quantity point kind -------------------- -A quantity point kind is the analogous of a quantity point for quantity kinds. -(see the :ref:`Quantity Points` chapter). +Quantity Point Kinds +-------------------- + +A quantity point kind is the analogous of a quantity point for quantity kinds +(see the :ref:`framework/quantity_points:Quantity Points` chapter). They are represented in the library with a `quantity_point_kind` class template. @@ -67,6 +68,10 @@ First, we need a `point_kind` for a `kind`:: Now ``x`` coordinates can be constructed:: - quantity_point_kind auto x_pos(123 * m); - // `QuantityPointKindOf` with `x_pos.relative()` - // equal to `quantity_kind(123 * m)` + quantity_point_kind auto x_pos(123 * m); // QuantityPointKindOf + auto x = x_pos.relative(); // quantity_kind(123 * m) + +.. seealso:: + + Please refer to :ref:`examples/glide_computer:glide_computer` example for more + information on the quantity kinds usage. diff --git a/docs/framework/quantity_points.rst b/docs/framework/quantity_points.rst index 4652da66..4929c68f 100644 --- a/docs/framework/quantity_points.rst +++ b/docs/framework/quantity_points.rst @@ -8,8 +8,6 @@ A quantity point is an absolute quantity with respect to zero `quantity_point` class template. -.. _quantity-point-construction: - Construction ------------ @@ -30,7 +28,7 @@ the value to the `quantity_point` class template explicit constructor:: quantity_point d = 123_q_km; // ERROR -Differences to quantity +Differences To Quantity ----------------------- Unlike `quantity`, the library provides: @@ -40,4 +38,4 @@ Unlike `quantity`, the library provides: - no dimension-specific concepts, such as ``LengthPoint`` (there's the dimension-agnostic `QuantityPoint`), - a more limited set of operations on quantity points - (see the :ref:`Dimensions` chapter) + (see the :ref:`framework/dimensions:Quantity Points` chapter) diff --git a/docs/framework/text_output.rst b/docs/framework/text_output.rst index a714e24f..678b85fd 100644 --- a/docs/framework/text_output.rst +++ b/docs/framework/text_output.rst @@ -16,8 +16,7 @@ Output Streams .. tip:: - The streaming support is provided via the ```` header - file. + The streaming support is provided via the ```` header file. The easiest way to print a quantity is to provide its object to the output stream:: @@ -55,6 +54,10 @@ over width, fill, and alignment:: fmt::format ----------- +.. tip:: + + The text formatting support is provided via the ```` header file. + The **mp-units** via ``fmt::format`` provides a fine-grained control over what and how is being printed on the text output. diff --git a/docs/framework/units.rst b/docs/framework/units.rst index 486959ea..6e6adac6 100644 --- a/docs/framework/units.rst +++ b/docs/framework/units.rst @@ -57,7 +57,8 @@ definitions of prefixed units using ``si::metre`` as a reference (i.e. child class inherited from the instantiation of this `named_unit` class template. This is called a :abbr:`CRTP (Curiously Recurring Template Parameter)` Idiom and is used - in many places in this library to provide :ref:`The Downcasting Facility`. + in many places in this library to provide + :ref:`design/downcasting:The Downcasting Facility`. Hopefully if [P0847]_ will land in C++23 the additional CRTP-related template parameter will be removed from this definition. @@ -90,7 +91,7 @@ knows how to convert ``si::metre`` to ``si::centimetre`` and vice versa). More details on custom systems definitions and conversions between units of the same physical dimension can be found in the - :ref:`Custom Systems` chapter. + :ref:`use_cases/extensions:Custom Systems` chapter. Derived Units @@ -399,5 +400,5 @@ type here instead. .. seealso:: - To learn more about unknown units please refer to - :ref:`Working with Unknown Dimensions and Their Units` chapter. + To learn more about unknown units please refer to the + :ref:`use_cases/unknown_dimensions:Working with Unknown Dimensions and Their Units` chapter. diff --git a/docs/introduction.rst b/docs/introduction.rst index 16acde27..e380b922 100644 --- a/docs/introduction.rst +++ b/docs/introduction.rst @@ -14,7 +14,7 @@ general facility for unit conversions. The library architecture has been designed with flexibility and extensibility in mind. The demonstrations of the ease of adding new dimensions, their units, -and unit conversions are provided in the :ref:`Examples`. +and unit conversions are provided in the :ref:`examples:Examples`. Open Source ----------- @@ -61,7 +61,7 @@ To achieve this goal several techniques are applied: - usage of C++20 concepts, - using strong types for framework entities (instead of type aliases), - limiting the number of template arguments to the bare minimum, -- :ref:`The Downcasting Facility`. +- :ref:`design/downcasting:The Downcasting Facility`. .. important:: diff --git a/docs/quick_start.rst b/docs/quick_start.rst index 929c87a1..b3a507dc 100644 --- a/docs/quick_start.rst +++ b/docs/quick_start.rst @@ -76,4 +76,4 @@ of basic library features:: .. seealso:: - You can find more code examples in the :ref:`Examples` chapter. + You can find more code examples in the :ref:`examples:Examples` chapter. diff --git a/docs/reference/core/concepts.rst b/docs/reference/core/concepts.rst index fc06e807..43c8349d 100644 --- a/docs/reference/core/concepts.rst +++ b/docs/reference/core/concepts.rst @@ -14,7 +14,7 @@ Concepts .. concept:: template Prefix - A concept matching a symbol prefix. Satisfied by all instantiations of :class:`prefix`. + A concept matching a symbol prefix. Satisfied by all instantiations of :struct:`prefix`. .. concept:: template UnitRatio @@ -71,13 +71,13 @@ Concepts .. concept:: template QuantityValue A concept matching types that can be used as a `Quantity` representation type. Satisfied - by types that match :expr:`(!Quantity) && (!QuantityLike) && (!WrappedQuantity) && std::regular` + by types that match ``(!Quantity) && (!QuantityLike) && (!WrappedQuantity) && std::regular`` and satisfy one of the following: - - if :expr:`common_type_with` is ``true``, then :expr:`std::common_type_t` + - if ``common_type_with`` is ``true``, then ``std::common_type_t`` must at least provide binary multiplication and division operators, - - otherwise, :expr:`T::value_type` must be valid, :expr:`common_type_with` be - ``true``, and :expr:`std::common_type_t` must at least provide binary + - otherwise, ``T::value_type`` must be valid, ``common_type_with`` be + ``true``, and ``std::common_type_t`` must at least provide binary multiplication and division operators with itself and ``T``. .. concept:: template QuantityPoint @@ -85,6 +85,26 @@ Concepts A concept matching all quantity points in the library. Satisfied by all instantiations of :class:`quantity_point`. +.. concept:: template Kind + + A concept matching all kind types. Satisfied by all kind types derived from an specialization of + :class:`kind`. + +.. concept:: template PointKind + + A concept matching all point kind types. Satisfied by all point kind types derived from an specialization of + :class:`point_kind`. + +.. concept:: template QuantityKind + + A concept matching all quantity kinds in the library. Satisfied by all specializations of + :class:`quantity_kind`. + +.. concept:: template QuantityPointKind + + A concept matching all quantity point kinds in the library. Satisfied by all specializations of + :class:`quantity_point_kind`. + .. concept:: template typename DimTemplate> DimensionOfT A concept matching all dimensions being the instantiations derived from the provided dimension @@ -95,7 +115,44 @@ Concepts A concept matching all quantities with a dimension being the instantiation derived from the provided dimension class template. -.. concept:: template QuantityOf +.. concept:: template QuantityOf A concept matching all quantities with a dimension being the instantiation derived from the provided dimension type. + +.. concept:: template QuantityEquivalentTo + + A concept matching two equivalent quantities. Satisfied by quantities having equivalent dimensions. + +.. concept:: template QuantityPointOf + + A concept matching all quantity points with a dimension being the instantiation derived from + the provided dimension type. + +.. concept:: template QuantityPointEquivalentTo + + A concept matching two equivalent quantity points. Satisfied by quantity points having equivalent + dimensions. + +.. concept:: template QuantityKindOf + + A concept matching only quantity kinds of a specific kind. + + :tparam QK: Quantity kind to verify. + :tparam K: Kind type to use for verification. + +.. concept:: template QuantityKindEquivalentTo + + A concept matching two equivalent quantity kinds. Satisfied by quantity kinds having equivalent kinds. + +.. concept:: template QuantityPointKindOf + + A concept matching only quantity point kinds of a specific point kind. + + :tparam QPK: Quantity point kind to verify. + :tparam PK: Point kind type to use for verification. + +.. concept:: template QuantityPointKindEquivalentTo + + A concept matching two equivalent quantity point kinds. Satisfied by quantity point kinds having + equivalent kinds. diff --git a/docs/reference/core/downcasting.rst b/docs/reference/core/downcasting.rst index a3e909a9..9b4bff8e 100644 --- a/docs/reference/core/downcasting.rst +++ b/docs/reference/core/downcasting.rst @@ -1,6 +1,8 @@ The Downcasting Facility ======================== +.. doxygenenum:: downcast_mode + .. concept:: template Downcastable .. doxygenstruct:: units::downcast_base diff --git a/docs/reference/core/types.rst b/docs/reference/core/types.rst index e3cb555f..0e68ea9b 100644 --- a/docs/reference/core/types.rst +++ b/docs/reference/core/types.rst @@ -6,6 +6,9 @@ Types types/quantity types/quantity_point + types/kind + types/quantity_kind + types/quantity_point_kind types/dimensions types/units types/prefixes diff --git a/docs/reference/core/types/kind.rst b/docs/reference/core/types/kind.rst new file mode 100644 index 00000000..57ba9109 --- /dev/null +++ b/docs/reference/core/types/kind.rst @@ -0,0 +1,8 @@ +Kinds +===== + +.. doxygenstruct:: units::kind + :members: + +.. doxygenstruct:: units::point_kind + :members: diff --git a/docs/reference/core/types/quantity_kind.rst b/docs/reference/core/types/quantity_kind.rst new file mode 100644 index 00000000..882ef3bf --- /dev/null +++ b/docs/reference/core/types/quantity_kind.rst @@ -0,0 +1,6 @@ +Quantity Kind +============= + +.. doxygenclass:: units::quantity_kind + :members: + :undoc-members: diff --git a/docs/reference/core/types/quantity_point_kind.rst b/docs/reference/core/types/quantity_point_kind.rst new file mode 100644 index 00000000..6e5010c5 --- /dev/null +++ b/docs/reference/core/types/quantity_point_kind.rst @@ -0,0 +1,6 @@ +Quantity Point Kind +=================== + +.. doxygenclass:: units::quantity_point_kind + :members: + :undoc-members: diff --git a/docs/usage.rst b/docs/usage.rst index 1cc3c9a6..7a065f91 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -125,7 +125,7 @@ downcast_mode **Defaulted to**: ``on`` -Specifies how :ref:`The Downcasting Facility` works: +Specifies how :ref:`design/downcasting:The Downcasting Facility` works: - ``off`` - no downcasting at all - ``on`` - downcasting always forced -> compile-time errors in case of duplicated definitions diff --git a/docs/use_cases/custom_representation_types.rst b/docs/use_cases/custom_representation_types.rst index b70f0728..37ca2efd 100644 --- a/docs/use_cases/custom_representation_types.rst +++ b/docs/use_cases/custom_representation_types.rst @@ -217,10 +217,11 @@ operations. `treat_as_floating_point` ^^^^^^^^^^^^^^^^^^^^^^^^^ -In the :ref:`Conversions and Casting` chapter we learned that the conversions provided by the -library's framework treat floating-point representation types differently than the integral -ones. This behavior can also be extended to the custom representation types with -`treat_as_floating_point` customization point which default definition is:: +In the :ref:`framework/conversions_and_casting:Conversions and Casting` chapter we learned +that the conversions provided by the library's framework treat floating-point representation +types differently than the integral ones. This behavior can also be extended to the custom +representation types with `treat_as_floating_point` customization point which default +definition is:: template inline constexpr bool treat_as_floating_point = std::is_floating_point_v; @@ -303,4 +304,5 @@ representation types with:: .. seealso:: For more examples of custom representation types usage please refer to the - :ref:`Linear Algebra vs. Quantities` chapter and the :ref:`measurement` example. + :ref:`use_cases/linear_algebra:Linear Algebra vs. Quantities` chapter and the + :ref:`examples/measurement:measurement` example. diff --git a/docs/use_cases/extensions.rst b/docs/use_cases/extensions.rst index 6ec9a266..83693c8d 100644 --- a/docs/use_cases/extensions.rst +++ b/docs/use_cases/extensions.rst @@ -309,4 +309,5 @@ In such a situation the standalone system may be a better choice here. .. seealso:: More information on extending the library can be found in the - :ref:`Using Custom Representation Types` chapter. + :ref:`use_cases/custom_representation_types:Using Custom Representation Types` + chapter. diff --git a/docs/use_cases/linear_algebra.rst b/docs/use_cases/linear_algebra.rst index a9b8c097..0a39299e 100644 --- a/docs/use_cases/linear_algebra.rst +++ b/docs/use_cases/linear_algebra.rst @@ -61,7 +61,8 @@ types provided to a `quantity` class template. .. seealso:: More information on providing custom representation types for `quantity` can be - found in the :ref:`Using Custom Representation Types` chapter. + found in the :ref:`use_cases/custom_representation_types:Using Custom Representation Types` + chapter. With this the above vector definitions can be rewritten as follows:: @@ -84,4 +85,4 @@ output: .. seealso:: For more examples of Linear Algebra definition and operations please refer to - the :ref:`linear_algebra` example. + the :ref:`examples/linear_algebra:linear_algebra` example. diff --git a/docs/use_cases/unknown_dimensions.rst b/docs/use_cases/unknown_dimensions.rst index be269b3e..65a41596 100644 --- a/docs/use_cases/unknown_dimensions.rst +++ b/docs/use_cases/unknown_dimensions.rst @@ -10,12 +10,14 @@ detail. What is an unknown dimension? ----------------------------- -As we learned in the :ref:`Dimensions` chapter, in most cases the result of multiplying -or dividing two quantities of specific dimensions is a quantity of yet another dimension. +As we learned in the :ref:`framework/dimensions:Dimensions` chapter, in most cases the result +of multiplying or dividing two quantities of specific dimensions is a quantity of yet another +dimension. If such a resulting dimension is predefined by the user (and a proper header file with its -definition is included in the current translation unit) :ref:`The Downcasting Facility` -will determine its type. The same applies to the resulting unit. For example: +definition is included in the current translation unit) +:ref:`design/downcasting:The Downcasting Facility` will determine its type. +The same applies to the resulting unit. For example: .. code-block:: :emphasize-lines: 1,7,9 @@ -83,7 +85,7 @@ following:: .. seealso:: Another good example of unknown dimension usage can be found in the - :ref:`box_example`:: + :ref:`examples/box_example:box_example`:: std::cout << "float rise rate = " << box.fill_level(measured_mass) / fill_time << '\n'; diff --git a/src/include/units/bits/basic_concepts.h b/src/include/units/bits/basic_concepts.h index 43602c86..50456c84 100644 --- a/src/include/units/bits/basic_concepts.h +++ b/src/include/units/bits/basic_concepts.h @@ -222,7 +222,7 @@ concept kind_impl_ = /** * @brief A concept matching all kind types * - * Satisfied by all kind types derived from an specialization of :class:`kind`. + * Satisfied by all kind types derived from an specialization of @c kind. */ template concept Kind = @@ -241,7 +241,7 @@ struct _point_kind_base; /** * @brief A concept matching all point kind types * - * Satisfied by all point kind types derived from an specialization of :class:`point_kind`. + * Satisfied by all point kind types derived from an specialization of @c point_kind. */ template concept PointKind = kind_impl_; diff --git a/src/include/units/bits/quantity_of.h b/src/include/units/bits/quantity_of.h index cd319cab..832f273f 100644 --- a/src/include/units/bits/quantity_of.h +++ b/src/include/units/bits/quantity_of.h @@ -76,6 +76,11 @@ concept QuantityOfT = Quantity && DimensionOfT concept QuantityOf = Quantity && Dimension && equivalent; +/** + * @brief A concept matching two equivalent quantities + * + * Satisfied by quantities having equivalent dimensions. + */ template concept QuantityEquivalentTo = Quantity && QuantityOf; @@ -88,6 +93,11 @@ concept QuantityEquivalentTo = Quantity && QuantityOf concept QuantityPointOf = QuantityPoint && Dimension && equivalent; +/** + * @brief A concept matching two equivalent quantity points + * + * Satisfied by quantity points having equivalent dimensions. + */ template concept QuantityPointEquivalentTo = QuantityPoint && QuantityPointOf; @@ -100,6 +110,11 @@ concept QuantityPointEquivalentTo = QuantityPoint && QuantityPointOf concept QuantityKindOf = QuantityKind && Kind && equivalent; +/** + * @brief A concept matching two equivalent quantity kinds + * + * Satisfied by quantity kinds having equivalent kinds. + */ template concept QuantityKindEquivalentTo = QuantityKind && QuantityKindOf; @@ -112,6 +127,11 @@ concept QuantityKindEquivalentTo = QuantityKind && QuantityKindOf concept QuantityPointKindOf = QuantityPointKind && PointKind && equivalent; +/** + * @brief A concept matching two equivalent quantity point kinds + * + * Satisfied by quantity point kinds having equivalent kinds. + */ template concept QuantityPointKindEquivalentTo = QuantityPointKind && QuantityPointKindOf; diff --git a/src/include/units/customization_points.h b/src/include/units/customization_points.h index 8fffaf26..43feba27 100644 --- a/src/include/units/customization_points.h +++ b/src/include/units/customization_points.h @@ -78,7 +78,7 @@ struct quantity_values { * The type trait should provide the following nested type aliases: @c dimension, @c unit, @c rep, * and a static member function @c count(T) that will return the raw value of the quantity. * - * Usage example can be found in units/chrono.h header file. + * Usage example can be found in @c units/chrono.h header file. * * @tparam T the type to provide support for */