From 9da39070ed00bfc60885b50ad244eae7742e9298 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johel=20Ernesto=20Guerrero=20Pe=C3=B1a?= Date: Thu, 18 Mar 2021 18:36:44 -0400 Subject: [PATCH] docs: update for reference --- README.md | 8 +-- docs/CHANGELOG.md | 2 +- docs/CMakeLists.txt | 2 +- docs/framework/quantities.rst | 74 +++++++------------- docs/framework/quantity_kinds.rst | 2 +- docs/quick_start.rst | 6 +- docs/reference/core/types/reference.rst | 6 ++ docs/reference/core/types/representation.rst | 6 -- 8 files changed, 43 insertions(+), 63 deletions(-) create mode 100644 docs/reference/core/types/reference.rst delete mode 100644 docs/reference/core/types/representation.rst diff --git a/README.md b/README.md index 02c730b2..243693bf 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ static_assert(10_q_km / 5_q_km == 2); static_assert(1000 / 1_q_s == 1_q_kHz); ``` -_Try it on the [Compiler Explorer](https://godbolt.org/z/YWch6d)._ +_Try it on the [Compiler Explorer](https://godbolt.org/z/shcohY)._ This library requires some C++20 features (concepts, classes as NTTPs, ...). Thanks to them the user gets a powerful but still easy to use interface and all unit conversions @@ -77,9 +77,9 @@ constexpr Speed auto avg_speed(Length auto d, Time auto t) int main() { using namespace units::isq::si::literals; - using namespace units::isq::si::unit_constants; + using namespace units::isq::si::references; - constexpr Speed auto v1 = 110 * km / h; + constexpr Speed auto v1 = 110 * (km / h); constexpr Speed auto v2 = avg_speed(220_q_km, 2_q_h); constexpr Speed auto v3 = avg_speed(si::length(140), si::time(2)); constexpr Speed auto v4 = quantity_cast>(v2); @@ -95,4 +95,4 @@ int main() } ``` -_Try it on the [Compiler Explorer](https://godbolt.org/z/eca49d)._ +_Try it on the [Compiler Explorer](https://godbolt.org/z/dY1dEd)._ diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index f1fac7e8..34c955aa 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -8,7 +8,7 @@ - refactor: basic concepts, `quantity` and `quantity_cast` refactored - refactor: `abs()` definition refactored to be more explicit about the return type - feat: quantity (point) kind support added (thanks [@johelegp](https://github.com/johelegp)) - - feat: unit constants support added (thanks [@johelegp](https://github.com/johelegp)) + - feat: quantity references support added (thanks [@johelegp](https://github.com/johelegp)) - feat: interoperability with `std::chrono::duration` and other units libraries - feat: CTAD for dimensionless quantity added - perf: preconditions check do not influence the runtime performance of a Release build diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index b830eb1e..0186da94 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -98,11 +98,11 @@ set(unitsSphinxDocs "${CMAKE_CURRENT_SOURCE_DIR}/reference/core/types/dimensions.rst" "${CMAKE_CURRENT_SOURCE_DIR}/reference/core/types/kinds.rst" "${CMAKE_CURRENT_SOURCE_DIR}/reference/core/types/prefixes.rst" + "${CMAKE_CURRENT_SOURCE_DIR}/reference/core/types/reference.rst" "${CMAKE_CURRENT_SOURCE_DIR}/reference/core/types/quantity.rst" "${CMAKE_CURRENT_SOURCE_DIR}/reference/core/types/quantity_kind.rst" "${CMAKE_CURRENT_SOURCE_DIR}/reference/core/types/quantity_point_kind.rst" "${CMAKE_CURRENT_SOURCE_DIR}/reference/core/types/quantity_point.rst" - "${CMAKE_CURRENT_SOURCE_DIR}/reference/core/types/representation.rst" "${CMAKE_CURRENT_SOURCE_DIR}/reference/core/types/units.rst" "${CMAKE_CURRENT_SOURCE_DIR}/reference/core/types/utilities.rst" "${CMAKE_CURRENT_SOURCE_DIR}/reference/core/types/utilities/basic_fixed_string.rst" diff --git a/docs/framework/quantities.rst b/docs/framework/quantities.rst index f7003143..c8660688 100644 --- a/docs/framework/quantities.rst +++ b/docs/framework/quantities.rst @@ -83,39 +83,40 @@ Thanks to them the same code can be as simple as:: ``_q_`` prefix was consistently applied to all the UDLs. -Unit Constants -++++++++++++++ +Quantity References ++++++++++++++++++++ -Unit Constants provide an alternative way to simplify quantities creation. -They are defined using a special `one_rep` representation type:: +Quantity References provide an alternative way to simplify quantities creation. +They are defined using the `reference` class template:: - namespace unit_constants { + namespace references { - inline constexpr auto km = length{}; - inline constexpr auto h = time{}; + inline constexpr auto km = reference{}; + inline constexpr auto h = reference{}; } With the above our code can look as follows:: - using namespace units::isq::si::unit_constants; + using namespace units::isq::si::references; auto d = 123. * km; // si::length - auto v = 70 * km / h; // si::speed + auto v = 70 * (km / h); // si::speed .. important:: ``km * 3`` or ``s / 4`` syntax is not allowed. + Neither is ``70 * km / h``, but ``70 * (km / h)`` is. -It is also allowed to easily define custom unit constants from existing ones:: +It is also allowed to easily define custom quantity references from existing ones:: inline constexpr auto Nm = N * m; inline constexpr auto km_per_h = km / h; inline constexpr auto mph = mi / h; -UDLs vs Unit Constants -++++++++++++++++++++++ +UDLs vs Quantity References ++++++++++++++++++++++++++++ -UDLs are helpful but they also have some disadvantages compared to Unit Constants: +UDLs are helpful but they also have some disadvantages compared to Quantity References: 1. UDLs are only for compile-time known values and do not work for runtime variables @@ -125,13 +126,13 @@ UDLs are helpful but they also have some disadvantages compared to Unit Constant auto v1 = 120_q_km / 2_q_h; auto v2 = length(distance) / time(duration); - - Unit Constants:: + - Quantity References:: - using namespace units::isq::si::unit_constants; + using namespace units::isq::si::references; auto v1 = 120 * km / (2 * h); - auto v2 = distance * km / (duration * h); + auto v2 = distance * (1 * km) / (duration * (1 * h)); - Constants treat both cases in a unified way. It is also worth to notice that we work + References 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. @@ -143,10 +144,10 @@ UDLs are helpful but they also have some disadvantages compared to Unit Constant using namespace units::isq::si::cgs::literals; auto d = 1_q_cm; // FAILS TO COMPILE - - Unit Constants:: + - Quantity References:: - inline constexpr auto si_cm = units::isq::si::unit_constants::cm; - inline constexpr auto cgs_cm = units::isq::si::cgs::unit_constants::cm; + inline constexpr auto si_cm = units::isq::si::references::cm; + inline constexpr auto cgs_cm = units::isq::si::cgs::references::cm; auto d1 = 1. * si_cm; // si::length auto d2 = 1. * cgs_cm; // si::cgs::length @@ -162,9 +163,9 @@ UDLs are helpful but they also have some disadvantages compared to Unit Constant No possibility to obtain any other representation type. - - Unit Constants:: + - Quantity References:: - using namespace units::isq::si::unit_constants; + using namespace units::isq::si::references; auto d1 = 123. * km; // si::length auto d2 = 123 * km; // si::length auto d3 = 123.f * km; // si::length @@ -179,39 +180,18 @@ UDLs are helpful but they also have some disadvantages compared to Unit Constant - 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: + - Quantity References: - - one constant per unit - - unnamed derived units constructed from base constants (i.e. ``km / h``) + - one reference per unit + - unnamed derived units constructed from base references (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(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 + Quantity References, 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 -a quantity in denominator:: - - using namespace units::isq::si::unit_constants; - Speed auto v = 220 * km / 2 * h; // FAILS TO COMPILE (not a quantity of a speed dimension) - -The above code can be fixed in one of the below ways: - -- braces around quantities in denominator:: - - Speed auto v = 220 * km / (2 * h); - -- inverting an operator for quantities in denominator:: - - Speed auto v = 220 * km / 2 / h; - -- creating a custom unit constant for a derived quantity:: - - inline constexpr auto km_per_h = km / h; - Speed auto v = 220 / 2 * km_per_h; - Dimension-specific Concepts --------------------------- diff --git a/docs/framework/quantity_kinds.rst b/docs/framework/quantity_kinds.rst index 36b67913..b04352dc 100644 --- a/docs/framework/quantity_kinds.rst +++ b/docs/framework/quantity_kinds.rst @@ -45,7 +45,7 @@ The library provides: - no kinds, such as ``radius`` or ``width``, therefore - * no UDLs or unit constants, + * no UDLs or quantity references, * no kind-specific concepts, such as ``Radius``, (there's the generic `QuantityKind` and kind-specifiable `QuantityKindOf`), diff --git a/docs/quick_start.rst b/docs/quick_start.rst index 9155501e..79497e09 100644 --- a/docs/quick_start.rst +++ b/docs/quick_start.rst @@ -29,7 +29,7 @@ Here is a small example of possible operations:: .. admonition:: Try it on Compiler Explorer - `Example #1 `_ + `Example #1 `_ This library requires some C++20 features (concepts, classes as :abbr:`NTTP (Non-Type Template Parameter)`, ...). Thanks to them the user gets a powerful @@ -55,7 +55,7 @@ of basic library features:: using namespace units::isq::si::literals; using namespace units::isq::si::unit_constants; - constexpr Speed auto v1 = 110 * km / h; + constexpr Speed auto v1 = 110 * (km / h); constexpr Speed auto v2 = avg_speed(220_q_km, 2_q_h); constexpr Speed auto v3 = avg_speed(si::length(140), si::time(2)); constexpr Speed auto v4 = quantity_cast>(v2); @@ -72,7 +72,7 @@ of basic library features:: .. admonition:: Try it on Compiler Explorer - `Example #2 `_ + `Example #2 `_ .. seealso:: diff --git a/docs/reference/core/types/reference.rst b/docs/reference/core/types/reference.rst new file mode 100644 index 00000000..752314a9 --- /dev/null +++ b/docs/reference/core/types/reference.rst @@ -0,0 +1,6 @@ +Quantity Reference +================== + +.. doxygenstruct:: units::reference + :members: + :undoc-members: diff --git a/docs/reference/core/types/representation.rst b/docs/reference/core/types/representation.rst deleted file mode 100644 index b3dd8fbb..00000000 --- a/docs/reference/core/types/representation.rst +++ /dev/null @@ -1,6 +0,0 @@ -Representation Types -==================== - -.. doxygenstruct:: units::one_rep - :members: - :undoc-members: \ No newline at end of file