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

docs: Documentation now prefers refrences over UDLs

Browse Source
This commit is contained in:
Mateusz Pusz committed 2021-04-02 13:11:20 +02:00
1 parent 7cc34646b9
commit c4e9ff7f66
12 files changed
+211 -175
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/framework/conversions_and_casting.rst
+29 -30
View File
@@ -21,9 +21,9 @@ No Conversions
No conversions (either implicit or explicit) are available across quantities of
different dimensions::
si::length<si::metre> d1 = 1_q_s; // Compile-time error
si::length<si::metre> d2(1_q_s); // Compile-time error
auto d3 = quantity_cast<si::metre>(1_q_s); // Compile-time error
si::length<si::metre> d1 = 1 * s; // Compile-time error
si::length<si::metre> d2(1 * s); // Compile-time error
auto d3 = quantity_cast<si::metre>(1 * s); // Compile-time error
Implicit
@@ -33,23 +33,23 @@ Implicit conversions are allowed only across quantities of the same dimension:
- for integral types with ratios that guarantee no precision loss::
si::length<si::metre, int> d1 = 1_q_km + 1_q_m; // OK
si::length<si::millimetre, int> d2 = 1_q_km + 1_q_m; // OK
si::length<si::kilometre, int> d3 = 1_q_km + 1_q_m; // Compile-time error
si::length<si::kilometre, int> d4(1_q_km + 1_q_m); // Compile-time error
si::length<si::metre, int> d5 = 1_q_m + 1_q_ft; // Compile-time error
si::length<si::metre, int> d6(1_q_m + 1_q_ft); // Compile-time error
si::length<si::metre, int> d1 = 1 * km + 1 * m; // OK
si::length<si::millimetre, int> d2 = 1 * km + 1 * m; // OK
si::length<si::kilometre, int> d3 = 1 * km + 1 * m; // Compile-time error
si::length<si::kilometre, int> d4(1 * km + 1 * m); // Compile-time error
si::length<si::metre, int> d5 = 1 * m + 1 * ft; // Compile-time error
si::length<si::metre, int> d6(1 * m + 1 * ft); // Compile-time error
- from an integral to a floating-point representation even in case of a truncating
ratio::
si::length<si::kilometre, double> d7 = 1_q_km + 1_q_m; // OK
si::length<si::metre, double> d8 = 1_q_m + 1_q_ft; // OK
si::length<si::kilometre, double> d7 = 1 * km + 1 * m; // OK
si::length<si::metre, double> d8 = 1 * m + 1 * ft; // OK
- when both sides use a floating-point representation::
si::length<si::metre, int> d9 = 1.23_q_m; // Compile-time error
si::length<si::metre, double> d10 = 1.23_q_m; // OK
si::length<si::metre, int> d9 = 1.23 * m; // Compile-time error
si::length<si::metre, double> d10 = 1.23 * m; // OK
Explicit
@@ -60,8 +60,8 @@ Explicit conversions are available with the `quantity_cast`, `quantity_point_cas
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::
si::length<si::kilometre, int> d1 = quantity_cast<kilometre>(1km + 1m); // OK
si::length<si::kilometre, int> d2 = quantity_cast<kilometre>(1s); // Error
si::length<si::kilometre, int> d1 = quantity_cast<kilometre>(1 * km + 1 * m); // OK
si::length<si::kilometre, int> d2 = quantity_cast<kilometre>(1 * s); // Error
.. seealso::
@@ -97,14 +97,13 @@ once and leave the rest intact:
`quantity_point_cast` takes anything that works for `quantity_point`
or a specific target `quantity_point`::
std::cout << "Point: " << quantity_point_cast<decltype(quantity_point{0_q_m})>(d) << '\n';
std::cout << "Point: " << quantity_point_cast<decltype(quantity_point{0 * m})>(d) << '\n';
For a single explicit template argument,
`quantity_point_kind_cast` is a superset of `quantity_kind_cast`,
which is also a superset of `quantity_cast`.
For a single explicit template argument, `quantity_point_kind_cast` is a superset of
`quantity_kind_cast`, which is also a superset of `quantity_cast`.
For the (dimension, unit) pair of explicit arguments case of `quantity_cast`,
`quantity_point_kind_cast` and `quantity_kind_cast`
accept a `PointKind` and `Kind` instead of a `Dimension`, respectively.
`quantity_point_kind_cast` and `quantity_kind_cast` accept a `PointKind` and `Kind`
instead of a `Dimension`, respectively.
.. seealso::
@@ -121,8 +120,8 @@ As noted in the :ref:`framework/quantities:Dimensionless Quantities` chapter,
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;
const auto d1 = 10 * km;
const auto d2 = 3 * km;
if(d1 / d2 > dimensionless<one>(2)) {
// ...
}
@@ -136,8 +135,8 @@ This is why it was decided to allow the ``dimensionless<one>`` quantity of any
representation type to be implicitly constructible from this representation type.
With that the above examples can be rewritten as follows::
const auto d1 = 10_q_km;
const auto d2 = 3_q_km;
const auto d1 = 10 * km;
const auto d2 = 3 * km;
if(d1 / d2 > 2) {
// ...
}
@@ -155,8 +154,8 @@ could be ambiguous. For example::
return d1 / d2 + 1;
}
As long as we can reason about what such code means for ``foo(10_q_km, 2_q_km)`` it is not that obvious
at all in the case of ``foo(10_q_cm, 2_q_ft)``. To make such code to compile for every case we have to
As long as we can reason about what such code means for ``foo(10 * km, 2 * km)`` it is not that obvious
at all in the case of ``foo(10 * cm, 2 * ft)``. To make such code to compile for every case we have to
either change the type of the resulting unit to the one having ``ratio(1)`` (:term:`coherent derived unit`)::
Dimensionless auto foo(Length auto d1, Length auto d2)
@@ -175,15 +174,15 @@ There is one more important point to note here. As the the dimensionless quantit
a number, it is never implicitly converted back to the representation type. This means that the following
code will not compile::
auto v = std::exp(10_q_m / 5_q_m);
auto v = std::exp(10 * m / (5 * m));
To make it compile fine we have to either explicitly get the value stored in the quantity::
auto v = std::exp(quantity_cast<one>(10_q_m / 5_q_m).number());
auto v = std::exp(quantity_cast<one>(10 * m / (5 * m)).number());
or use a mathematical wrapper function from `units` namespace::
auto v = units::exp(10_q_m / 5_q_m);
auto v = units::exp(10 * m / (5 * m));
.. important::