feedc0de/mp-units
1
0
Fork 0
forked from mpusz/mp-units
Code Pull Requests Activity

docs: various small documentation fixes

Browse Source
This commit is contained in:
Mateusz Pusz
2020-09-14 08:45:36 +02:00
parent 452f1a105d
commit 8cc7a53943
8 changed files with 66 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/design/downcasting.rst
View File

@@ -20,7 +20,7 @@ quantity. Other libraries will do it in the following way::
exponent<si::dim_time, 4>>;
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<units::exponent<units::physical::si::dim_electric_current, 2, 1>,
@@ -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<Downcastable T>
using downcast = decltype(detail::downcast_target_impl<T>());
using downcast = decltype(detail::downcast_impl<T>());
`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<typename T>
constexpr auto downcast_target_impl()
constexpr auto downcast_impl()
{
if constexpr(has_downcast_guide<T>)
return decltype(downcast_guide(std::declval<downcast_base<T>>()))();

12
docs/faq.rst
View File

@@ -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 <https://en.cppreference.com/w/cpp/language/namespace#Using-directives>`_
(i.e. ``using namespace units::physical::si``) are being used, `units::physical::si::time` will
collide with C `time <https://en.cppreference.com/w/c/chrono/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.

7
docs/framework/quantities.rst
View File

@@ -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.

8
docs/framework/quantity_points.rst
View File

@@ -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::

30
docs/framework/units.rst
View File

@@ -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<kilogram_metre_per_second> {};
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<scaled_unit<ratio(1, 36, 1), si::metre>, long double>`. This is caused
``si::length<scaled_unit<ratio(1, 36, 1), si::metre>, 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.

41
docs/glossary.rst
View File

@@ -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 <quantity>`
within that subset.
- `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 <quantity>` 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 <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 <base quantity>`:
length, mass, time, electric current, thermodynamic temperature, amount of substance,
and luminous intensity.
- `System of quantities <system of quantities>` based on the seven
`base quantities <base quantity>`: 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 <base unit>`, is a product of powers of `base units <base unit>` with no
other proportionality factor than one.
- `Derived unit <derived unit>` that, for a given `system of quantities` and for a chosen
set of `base units <base unit>`, is a product of powers of `base units <base unit>` 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 <base unit>`. 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 <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 <base unit>`.
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 <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 <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

12
docs/reference/core/concepts.rst
View File

@@ -32,7 +32,7 @@ Concepts
.. concept:: template<typename T> 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<typename T> Dimension
@@ -48,7 +48,7 @@ Concepts
A concept matching only units of a specified dimension. Satisfied by all unit types that
satisfy :expr:`Unit<U>`, :expr:`Dimension<D>`, and for which :expr:`U::reference` and
:expr:`dimension_unit<D>::reference` denote the same unit type.
``dimension_unit<D>::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<typename T::value_type>` recursively
(i.e. :expr:`std::optional<si::length<si::metre>>`).
(i.e. ``std::optional<si::length<si::metre>>``).
.. concept:: template<typename T> 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 Dim, template<typename...> typename DimTemplate> concept DimensionOfT
.. concept:: template<typename Dim, template<typename...> typename DimTemplate> DimensionOfT
A concept matching all dimensions being the instantiations derived from the provided dimension
class template.
.. concept:: template<typename Q, template<typename...> typename DimTemplate> concept QuantityOfT
.. concept:: template<typename Q, template<typename...> typename DimTemplate> QuantityOfT
A concept matching all quantities with a dimension being the instantiation derived from
the provided dimension class template.
.. concept:: template<typename T, typename Dim> concept QuantityOf
.. concept:: template<typename T, typename Dim> QuantityOf
A concept matching all quantities with a dimension being the instantiation derived from
the provided dimension type.

2
docs/use_cases/extensions.rst
View File

@@ -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<desk, "desk", si::prefix, ratio(3, 10), si::square_metre> {};