forked from mpusz/mp-units
docs: Documentation updated
This commit is contained in:
Mateusz Pusz
@@ -45,7 +45,7 @@ The most important concepts in the library are `Unit`, `Dimension`,
|
||||
|
||||
[<abstract>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
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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<height, dim_length> {};
|
||||
struct rate_of_climb : derived_kind<rate_of_climb, height, dim_speed> {};
|
||||
|
||||
quantity_kind h(height{}, 100 * m);
|
||||
quantity_point_kind rate = h / (25 * s);
|
||||
// `quantity_point_kind<rate_of_climb, si::metre_per_second, int>(4 * m / s)`
|
||||
// quantity_point_kind<rate_of_climb, si::metre_per_second, int>(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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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<radius, si::dim_length> {};
|
||||
|
||||
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<radius, si::kilometre, double> 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<x_coordinate, si::metre, int> auto x_pos(123 * m);
|
||||
// `QuantityPointKindOf<x_coordinate>` with `x_pos.relative()`
|
||||
// equal to `quantity_kind<width, si::metre, int>(123 * m)`
|
||||
quantity_point_kind<x_coordinate, si::metre, int> auto x_pos(123 * m); // QuantityPointKindOf<x_coordinate>
|
||||
auto x = x_pos.relative(); // quantity_kind<width, si::metre, int>(123 * m)
|
||||
|
||||
.. seealso::
|
||||
|
||||
Please refer to :ref:`examples/glide_computer:glide_computer` example for more
|
||||
information on the quantity kinds usage.
|
||||
|
||||
@@ -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<si::dim_length, si::kilometre, double> 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)
|
||||
|
||||
@@ -16,8 +16,7 @@ Output Streams
|
||||
|
||||
.. tip::
|
||||
|
||||
The streaming support is provided via the ``<units/quantity_io.h>`` header
|
||||
file.
|
||||
The streaming support is provided via the ``<units/quantity_io.h>`` 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 ``<units/format.h>`` header file.
|
||||
|
||||
The **mp-units** via ``fmt::format`` provides a fine-grained control over what
|
||||
and how is being printed on the text output.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user