diff --git a/docs/design/downcasting.rst b/docs/design/downcasting.rst index 43ce635a..13cd66fa 100644 --- a/docs/design/downcasting.rst +++ b/docs/design/downcasting.rst @@ -20,7 +20,7 @@ quantity. Other libraries will do it in the following way:: exponent>; The above solution does provide a good developer's experience but a really poor one for the end -user. If we will get a compilation error message containing `dim_capacitance` in most cases +user. If we will get a compilation error message containing ``dim_capacitance`` in most cases the compiler will print the following type instead of the alias:: units::detail::derived_dimension_base, @@ -29,12 +29,12 @@ the compiler will print the following type instead of the alias:: You can notice that in case of **mp-units** even this long syntax was carefully selected to provide quite good user experience (some other units libraries produce a type that cannot easily -fit on one slide) but it is not questionable less readable than just `dim_capacitance`. +fit on one slide) but it is not questionable less readable than just ``dim_capacitance``. .. note:: To better understand how the framework works and not clutter the text and graphs with - long types in the following examples we will switch from `dim_capacitance` to `dim_area`. + long types in the following examples we will switch from ``dim_capacitance`` to ``dim_area``. The latter one has much shorter definition but the end result for both will be exactly the same - user-friendly, short name printed by the compiler and the debugger. @@ -52,7 +52,7 @@ to use inheritance: This gives us a nice looking strong type when directly used by the user. However, we just got ourselves into problems. The library's framework does not know how to switch from a long -instantiation of a `derived_dimension_base` class template that was generated as a result +instantiation of a ``derived_dimension_base`` class template that was generated as a result of dimensional calculation to a nicely named child class assigned by the user for this instantiation. @@ -87,7 +87,7 @@ In the above example: - ``dim_area`` is a downcasting target (child class) -- `detail::derived_dimension_base` class template instantiation is a downcasting source (base class) +- ``detail::derived_dimension_base`` class template instantiation is a downcasting source (base class) - `downcast_base` is a class that implements :abbr:`CRTP (Curiously Recurring Template Pattern)` idiom, stores the base of a downcasting operation in a ``downcast_base_type`` member type, @@ -137,10 +137,10 @@ Until now we scoped on how we define the base and target of a downcasting operat perform the actual downcasting operation a dedicated alias template is provided:: template - using downcast = decltype(detail::downcast_target_impl()); + using downcast = decltype(detail::downcast_impl()); `downcast` is used to obtain the target type of the downcasting operation registered for a -given instantiation in a base type. `detail::downcast_target_impl` checks if a downcasting +given instantiation in a base type. ``detail::downcast_impl`` checks if a downcasting target is registered for the specific base class. If yes, it returns the registered type, otherwise it works like a regular identity type trait returning a provided base class:: @@ -150,7 +150,7 @@ otherwise it works like a regular identity type trait returning a provided base concept has_downcast_guide = requires(T t) { downcast_guide(t); }; template - constexpr auto downcast_target_impl() + constexpr auto downcast_impl() { if constexpr(has_downcast_guide) return decltype(downcast_guide(std::declval>()))(); diff --git a/docs/faq.rst b/docs/faq.rst index 8c09b563..29b017aa 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -30,12 +30,12 @@ different dimensions (i.e. height, width, and depth) all of them will just be measured in meters. -Why other systems are defined in the `si` namespace? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Why other systems are defined in the `physical::si` namespace? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -All systems defined in the `si` namespace are defined in terms of base units -that are convertible to the :term:`SI` units. This enables conversions of -units of the same physical dimension between different systems. +All systems defined in the `physical::si` namespace are defined in terms of +base units that are convertible to the :term:`SI` units. This enables conversions +of units of the same physical dimension between different systems. .. seealso:: @@ -126,4 +126,4 @@ 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. +``time`` function needs to be prefixed with at least one (or all) namespace names. diff --git a/docs/framework/quantities.rst b/docs/framework/quantities.rst index 56d92be1..c2c675af 100644 --- a/docs/framework/quantities.rst +++ b/docs/framework/quantities.rst @@ -7,9 +7,10 @@ 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: -Quantity Construction ---------------------- +Construction +------------ To create the quantity object from a :term:`scalable number` we just have to pass the value to the `quantity` class template explicit constructor:: @@ -189,7 +190,7 @@ are provided:: There are two special units provided for usage with such a quantity: -- `one` which is the :ref:`coherent unit` of dimensionless quantity and does not +- `one` which is the :term:`coherent derived unit` of dimensionless quantity and does not provide any textual symbol (according to the ISO definition "the measurement units and values of quantities of dimension one are numbers"), - `percent` which has the symbol ``%`` and ``ratio(1, 100)`` of the `one` unit. diff --git a/docs/framework/quantity_points.rst b/docs/framework/quantity_points.rst index 65f1878c..87fea78c 100644 --- a/docs/framework/quantity_points.rst +++ b/docs/framework/quantity_points.rst @@ -3,13 +3,15 @@ Quantity Points =============== -A `quantity point` is an absolute quantity with respect to zero +A quantity point is an absolute quantity with respect to zero (which represents some origin) and is represented in the library with a `quantity_point` class template. -Quantity Point Construction ---------------------------- +.. _quantity-point-construction: + +Construction +------------ To create the quantity point object from a `quantity` we just have to pass the value to the `quantity_point` class template explicit constructor:: diff --git a/docs/framework/units.rst b/docs/framework/units.rst index 1489e184..486959ea 100644 --- a/docs/framework/units.rst +++ b/docs/framework/units.rst @@ -24,7 +24,7 @@ Base Units ``m`` (meter) is a base unit of length, ``s`` (second) is a base unit of time. In each :term:`coherent system of units`, there is only one base unit for each base quantity. This is why a base unit type is required by -the `base_dimension` definition in this library. For example `si::dim_length` +the `base_dimension` definition in this library. For example ``si::dim_length`` can be defined in the following way:: namespace si { @@ -33,7 +33,7 @@ can be defined in the following way:: } -where `si::metre` is defined as:: +where ``si::metre`` is defined as:: namespace si { @@ -43,8 +43,8 @@ where `si::metre` is defined as:: In the above definition ``"m"`` is the unit symbol to be used in the text output, and ``si::prefix`` specifies that the library should allow -definitions of prefixed units using `si::metre` as a reference (i.e. -`si::centimetre`). +definitions of prefixed units using ``si::metre`` as a reference (i.e. +``si::centimetre``). .. seealso:: @@ -81,10 +81,10 @@ The fact that both base dimensions use the same identifier ``"L"`` tells the library that both definitions refer to the same physical dimension of length. The only difference is the measurement unit used to define their base dimensions. Thanks to using the unit that is defined in terms of the -the same reference unit as the one provided to `si::dim_length` definition -(namely `si::centimetre` which is ``1/100`` of `si::metre`) we also enabled +the same reference unit as the one provided to ``si::dim_length`` definition +(namely ``si::centimetre`` which is ``1/100`` of ``si::metre``) we also enabled the ability to easily convert between those 2 base dimensions (as the library -knows how to convert `si::metre` to `si::centimetre` and vice versa). +knows how to convert ``si::metre`` to ``si::centimetre`` and vice versa). .. seealso:: @@ -145,7 +145,7 @@ where ``kilogram_metre_per_second`` is defined as:: struct kilogram_metre_per_second : unit {}; However, the easiest way to define momentum is just to use the -`si::speed` derived dimension in the recipe: +``si::speed`` derived dimension in the recipe: .. code-block:: :emphasize-lines: 3 @@ -217,8 +217,8 @@ and define units like:: Finally, the last of the `named_scaled_unit` class template parameters provide a reference unit for scaling. Please note that it can be a dimension's -base/coherent unit (like `si::second`) or any other unit (i.e. `si::minute`, -`si::hour`) that is a scaled version of the dimension's base/coherent unit. +base/coherent unit (like ``si::second``) or any other unit (i.e. ``si::minute``, +``si::hour``) that is a scaled version of the dimension's base/coherent unit. Prefixed Unit @@ -272,7 +272,7 @@ domain:: } With the definitions like above we can easily define prefixed unit. For -example we can define `si::kilometre` as:: +example we can define ``si::kilometre`` as:: namespace si { @@ -303,7 +303,7 @@ ratio in reference to "metre per second": Whichever, we choose there will always be someone not happy with our choice. Thanks to a `deduced_unit` class template provided by the library this problem -does not exist at all. With it `si::kilometre_per_hour` can be defined as:: +does not exist at all. With it ``si::kilometre_per_hour`` can be defined as:: namespace si { @@ -392,12 +392,12 @@ unknown/undefined unit type like in the below example:: Length auto l = 100_q_km_per_h * 10_q_s; The type of ``l`` above will be -:expr:`si::length, long double>`. This is caused +``si::length, long double>``. This is caused by the fact that the library does not define a unit of a length quantity that has the -ratio ``10/36`` of a `si::metre`. If such a unit was predefined we would see its concrete +ratio ``10/36`` of a ``si::metre``. If such a unit was predefined we would see its concrete type here instead. .. seealso:: To learn more about unknown units please refer to - :ref:`Working with Unknown Units and Dimensions` chapter. + :ref:`Working with Unknown Dimensions and Their Units` chapter. diff --git a/docs/glossary.rst b/docs/glossary.rst index 748feda8..67d2aaaf 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -44,21 +44,21 @@ ISO 80000 [1]_ definitions the Imperial System, etc. base quantity - - `Quantity` in a conventionally chosen subset of a given `system of quantities`, where - no `quantity` in the subset can be expressed in terms of the other `quantities ` - within that subset. + - `Quantity ` in a conventionally chosen subset of a given `system of quantities`, + where no `quantity` in the subset can be expressed in terms of the other + `quantities ` within that subset. - Base quantities are referred to as being mutually independent since a base quantity cannot be expressed as a product of powers of the other base quantities. derived quantity - - `Quantity`, in a `system of quantities`, defined in terms of the base quantities of - that system. + - `Quantity `, in a `system of quantities`, defined in terms of the base + quantities of that system. International System of Quantities ISQ - - `System of quantities` based on the seven `base quantities `: - length, mass, time, electric current, thermodynamic temperature, amount of substance, - and luminous intensity. + - `System of quantities ` based on the seven + `base quantities `: length, mass, time, electric current, thermodynamic + temperature, amount of substance, and luminous intensity. - The International System of Units (SI) is based on the ISQ. dimension of a quantity @@ -130,9 +130,9 @@ ISO 80000 [1]_ definitions - For example, in the `ISQ` Newton, Pascal, and katal are derived units. coherent derived unit - - `Derived unit` that, for a given `system of quantities` and for a chosen set of - `base units `, is a product of powers of `base units ` with no - other proportionality factor than one. + - `Derived unit ` that, for a given `system of quantities` and for a chosen + set of `base units `, is a product of powers of `base units ` with + no other proportionality factor than one. - A power of a `base unit` is the `base unit` raised to an exponent. - Coherence can be determined only with respect to a particular `system of quantities` and a given set of `base units `. That is, if the metre and the second are @@ -145,23 +145,24 @@ ISO 80000 [1]_ definitions coherent system of units - - `System of units`, based on a given `system of quantities`, in which the measurement - unit for each `derived quantity` is a `coherent derived unit`. + - `System of units `, based on a given `system of quantities`, in which + the measurement unit for each `derived quantity` is a `coherent derived unit`. - A `system of units` can be coherent only with respect to a `system of quantities` and the adopted `base units `. off-system measurement unit off-system unit - - `Measurement unit` that does not belong to a given `system of units`. For example, the - electronvolt (:math:`≈ 1,602 18 × 10^{–19} J`) is an off-system measurement unit of energy with - respect to the `SI` or day, hour, minute are off-system measurement units of time with - respect to the `SI`. + - `Measurement unit ` that does not belong to a given `system of units`. + For example, the electronvolt (:math:`≈ 1,602 18 × 10^{–19} J`) is an off-system measurement + unit of energy with respect to the `SI` or day, hour, minute are off-system measurement + units of time with respect to the `SI`. International System of Units SI - - `System of units`, based on the `International System of Quantities`, their names and - symbols, including a series of prefixes and their names and symbols, together with rules - for their use, adopted by the General Conference on Weights and Measures (CGPM) + - `System of units `, based on the `International System of Quantities`, + their names and symbols, including a series of prefixes and their names and symbols, + together with rules for their use, adopted by the General Conference on Weights and + Measures (CGPM) quantity value value of a quantity diff --git a/docs/reference/core/concepts.rst b/docs/reference/core/concepts.rst index 4cd36599..8ebf8b91 100644 --- a/docs/reference/core/concepts.rst +++ b/docs/reference/core/concepts.rst @@ -32,7 +32,7 @@ Concepts .. concept:: template DerivedDimension A concept matching all derived dimensions in the library. Satisfied by all dimension - types derived from the instantiation of :class:`detail::derived_dimension_base`. + types derived from the instantiation of ``detail::derived_dimension_base``. .. concept:: template Dimension @@ -48,7 +48,7 @@ Concepts A concept matching only units of a specified dimension. Satisfied by all unit types that satisfy :expr:`Unit`, :expr:`Dimension`, and for which :expr:`U::reference` and - :expr:`dimension_unit::reference` denote the same unit type. + ``dimension_unit::reference`` denote the same unit type. :tparam U: Type to verify against concept constraints. :tparam D: Dimension type to use for verification. @@ -61,7 +61,7 @@ Concepts A concept matching types that wrap quantity objects. Satisfied by all wrapper types that satisfy :expr:`Quantity` recursively - (i.e. :expr:`std::optional>`). + (i.e. ``std::optional>``). .. concept:: template ScalableNumber @@ -79,17 +79,17 @@ Concepts A concept matching all quantity points in the library. Satisfied by all instantiations of :class:`quantity_point`. -.. concept:: template typename DimTemplate> concept DimensionOfT +.. concept:: template typename DimTemplate> DimensionOfT A concept matching all dimensions being the instantiations derived from the provided dimension class template. -.. concept:: template typename DimTemplate> concept QuantityOfT +.. concept:: template typename DimTemplate> QuantityOfT A concept matching all quantities with a dimension being the instantiation derived from the provided dimension class template. -.. concept:: template concept QuantityOf +.. concept:: template QuantityOf A concept matching all quantities with a dimension being the instantiation derived from the provided dimension type. diff --git a/docs/use_cases/extensions.rst b/docs/use_cases/extensions.rst index 77f62ea1..6a85c5da 100644 --- a/docs/use_cases/extensions.rst +++ b/docs/use_cases/extensions.rst @@ -57,7 +57,7 @@ Enabling a Unit for Prefixing ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In case I decide it is reasonable to express my desks with SI prefixes the only thing I have -to change in the above code is to replace `no_prefix` with `si_prefix`:: +to change in the above code is to replace `no_prefix` with `physical::si::prefix`:: struct desk : named_scaled_unit {};