mpusz/mp-units
1
0
Fork 1
mirror of https://github.com/mpusz/mp-units.git synced 2025-08-05 21:24:27 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: "UDLs vs Unit Constants" chapter extended

Browse Source
This commit is contained in:
Mateusz Pusz
2021-02-17 17:54:12 +01:00
parent 8193065feb
commit 86584dbfe2
1 changed files with 54 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

93
docs/framework/quantities.rst
View File

@@ -118,63 +118,78 @@ UDLs vs Unit Constants
UDLs are helpful but they also have some disadvantages compared to Unit Constants: UDLs are helpful but they also have some disadvantages compared to Unit Constants:
1. UDLs are only for compile-time known values and do not work for runtime variables 1. UDLs are only for compile-time known values and do not work for runtime variables
- UDLs::
using namespace units::physical::si::literals; - UDLs::
auto v1 = 120_q_km / 2_q_h;
auto v2 = length<kilometre>(distance) / time<hour>(duration);
- Unit Constants:: using namespace units::physical::si::literals;
auto v1 = 120_q_km / 2_q_h;
auto v2 = length<kilometre>(distance) / time<hour>(duration);
using namespace units::physical::si::unit_constants; - Unit Constants::
auto v1 = 120 * km / (2 * h);
auto v2 = distance * km / (duration * h);
Constants treat both cases in a unified way. It is also worth to notice that we work mostly with runtime variables using namespace units::physical::si::unit_constants;
and compile-time known values mostly appear only in physical constants and unit tests. auto v1 = 120 * km / (2 * h);
auto v2 = distance * km / (duration * h);
Constants treat both cases in a unified way. It is also worth to notice that we work
mostly with runtime variables and compile-time known values mostly appear only in physical
constants and unit tests.
2. UDLs cannot be disambiguated with a namespace name 2. UDLs cannot be disambiguated with a namespace name
- UDLs::
using namespace units::physical::si::literals; - UDLs::
using namespace units::physical::si::cgs::literals;
auto d = 1_q_cm; // FAILS TO COMPILE
- Unit Constants:: using namespace units::physical::si::literals;
using namespace units::physical::si::cgs::literals;
auto d = 1_q_cm; // FAILS TO COMPILE
inline constexpr auto si_cm = units::physical::si::unit_constants::cm; - Unit Constants::
inline constexpr auto cgs_cm = units::physical::si::cgs::unit_constants::cm;
auto d1 = 1. * si_cm; // si::length<si::centimetre> inline constexpr auto si_cm = units::physical::si::unit_constants::cm;
auto d2 = 1. * cgs_cm; // si::cgs::length<si::centimetre> inline constexpr auto cgs_cm = units::physical::si::cgs::unit_constants::cm;
3. Poor control over the representation types as UDLs return only ``std::int64_t`` or ``long double`` auto d1 = 1. * si_cm; // si::length<si::centimetre>
- UDLs:: auto d2 = 1. * cgs_cm; // si::cgs::length<si::centimetre>
using namespace units::physical::si::literals; 3. Poor control over the representation types as UDLs return only ``std::int64_t`` or
auto d1 = 123._q_km; // si::length<si::kilometre, long double> ``long double``
auto d2 = 123_q_km; // si::length<si::kilometre, std::int64_t>
No possibility to obtain any other representation type. - UDLs::
- Unit Constants:: using namespace units::physical::si::literals;
auto d1 = 123._q_km; // si::length<si::kilometre, long double>
auto d2 = 123_q_km; // si::length<si::kilometre, std::int64_t>
using namespace units::physical::si::unit_constants; No possibility to obtain any other representation type.
auto d1 = 123. * km; // si::length<si::kilometre, double>
auto d2 = 123 * km; // si::length<si::kilometre, int> - Unit Constants::
auto d3 = 123.f * km; // si::length<si::kilometre, float>
auto d4 = 123.L * km; // si::length<si::kilometre, long double> using namespace units::physical::si::unit_constants;
auto d5 = 123ul * km; // si::length<si::kilometre, unsigned long> auto d1 = 123. * km; // si::length<si::kilometre, double>
auto d6 = 123ll * km; // si::length<si::kilometre, long long> auto d2 = 123 * km; // si::length<si::kilometre, int>
auto d3 = 123.f * km; // si::length<si::kilometre, float>
auto d4 = 123.L * km; // si::length<si::kilometre, long double>
auto d5 = 123ul * km; // si::length<si::kilometre, unsigned long>
auto d6 = 123ll * km; // si::length<si::kilometre, long long>
4. UDLs are verbose to define and standardize 4. UDLs are verbose to define and standardize
- UDLs:
- for each unit an integral and a floating-point UDL have to be defined
- have to be provided for unnamed derived units (i.e. ``_q_km_per_h``)
- Unit Constants: - UDLs:
- one constant per unit
- unnamed derived units constructed from base constants (i.e. ``km / h``) - for each unit an integral and a floating-point UDL have to be defined
- have to be provided for unnamed derived units (i.e. ``_q_km_per_h``)
- Unit Constants:
- one constant per unit
- unnamed derived units constructed from base constants (i.e. ``km / h``)
5. Typical UDL definition for quantities when compiled with a ``-Wsign-conversion``
flag results in a compilation warning. This warning could be silenced with a
``static_cast<std::int64_t>(value)`` in every UDL, but in a such case other safety
and security issues could be silently introduced.
Unit Constants, on the opposite, always use the exact representation type provided
by the user so there is no chance for a truncating conversion on a quantity construction.
The only issue we are aware of with Unit Constants is a potential problem of specifying The only issue we are aware of with Unit Constants is a potential problem of specifying
a quantity in denominator:: a quantity in denominator::