From 746ac178e4adc8b733f8901a54ebe8e605dc01cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johel=20Ernesto=20Guerrero=20Pe=C3=B1a?= Date: Mon, 17 Aug 2020 22:23:11 -0400 Subject: [PATCH] docs: mention quantity_point where appropriate --- docs/framework/basic_concepts.rst | 8 +++--- docs/framework/conversions_and_casting.rst | 11 ++++++-- docs/framework/dimensions.rst | 31 ++++++++++++++++++++++ docs/framework/quantity_points.rst | 2 ++ docs/framework/text_output.rst | 4 +++ docs/use_cases/legacy_interfaces.rst | 14 ++++++++-- 6 files changed, 63 insertions(+), 7 deletions(-) diff --git a/docs/framework/basic_concepts.rst b/docs/framework/basic_concepts.rst index e1f73cb4..036b60b1 100644 --- a/docs/framework/basic_concepts.rst +++ b/docs/framework/basic_concepts.rst @@ -3,13 +3,13 @@ Basic Concepts ============== -The most important concepts in the library are `Unit`, `Dimension`, and -`Quantity`: +The most important concepts in the library are `Unit`, `Dimension`, +`Quantity` and `QuantityPoint`: .. image:: /_static/img/concepts.png :align: center -.. +.. http://www.nomnoml.com [Dimension| @@ -37,3 +37,5 @@ derived dimensions. `Quantity` is a concrete amount of a unit for a specified dimension with a specific representation. + +`QuantityPoint` is an absolute `Quantity` with respect to some origin. diff --git a/docs/framework/conversions_and_casting.rst b/docs/framework/conversions_and_casting.rst index 19674e8b..71712d9f 100644 --- a/docs/framework/conversions_and_casting.rst +++ b/docs/framework/conversions_and_casting.rst @@ -55,8 +55,9 @@ Implicit conversions are allowed only across quantities of the same dimension: Explicit -------- -Explicit conversions are available with a `quantity_cast` function template. They -are especially useful to force a truncating conversion across quantities of the same +Explicit conversions are available with +the `quantity_cast` and `quantity_point_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:: si::length d1 = quantity_cast(1km + 1m); // OK @@ -88,6 +89,12 @@ once and leave the rest intact: - line #2 forces only a specific destination unit type, - line #3 sets only a representation type to the type provided by the user. +`quantity_point_cast` takes anything that works for `quantity_point` +or a specific target `quantity_point`: + + std::cout << "Point: " << quantity_point_cast(d) + << '\n'; + .. seealso:: For more information on conversion and casting and on how to extend the above "integral" diff --git a/docs/framework/dimensions.rst b/docs/framework/dimensions.rst index 2f07fe33..35354605 100644 --- a/docs/framework/dimensions.rst +++ b/docs/framework/dimensions.rst @@ -61,6 +61,37 @@ dimension, than we will end up with just a scalar type: Scalar auto v1 = dur1 / dur2; // 5 Scalar auto v2 = dur1 * fr1; // 50 +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. +The result will always be a quantity point of the same dimension: + +.. code-block:: + :emphasize-lines: 3-4 + + Length auto dist1 = 2q_m; + Length auto dist2 = 1q_m; + QuantityPoint auto res1 = quantity_point{dist1} + dist2; + 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:: + Length auto dist1 = 2q_m; + Length auto dist2 = 1q_m; + auto res1 = dist1 - quantity_point{dist2}; // ERROR + +We can also substract two quantity points. +The result is a relative quantity of the same dimension: + + Length auto dist1 = 2q_m; + Length auto dist2 = 1q_m; + Length auto res1 = quantity_point{dist1} - quantity_point{dist2}; + +That's it! You can't multiply nor divide quantity points with anything else. Base Dimensions --------------- diff --git a/docs/framework/quantity_points.rst b/docs/framework/quantity_points.rst index 158859b8..58d95e56 100644 --- a/docs/framework/quantity_points.rst +++ b/docs/framework/quantity_points.rst @@ -36,3 +36,5 @@ Unlike `quantity`, the library provides - no UDLs for quantity points, - 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:`Conversions and Casting` chapter) diff --git a/docs/framework/text_output.rst b/docs/framework/text_output.rst index a127b9dd..61d97798 100644 --- a/docs/framework/text_output.rst +++ b/docs/framework/text_output.rst @@ -6,6 +6,10 @@ Text Output Beside providing dimensional analysis and units conversions, the library also tries really hard to print any quantity in the most user friendly way. +.. note:: + + The library provides no text output for quantity points. + Output Streams -------------- diff --git a/docs/use_cases/legacy_interfaces.rst b/docs/use_cases/legacy_interfaces.rst index 2f01632c..96bcf029 100644 --- a/docs/use_cases/legacy_interfaces.rst +++ b/docs/use_cases/legacy_interfaces.rst @@ -4,8 +4,9 @@ Working with Legacy Interfaces ============================== In case we are working with a legacy/unsafe interface we may be forced to -extract a :term:`value of a quantity` with :func:`quantity::count()` and -pass it to the library's output: +extract the :term:`value of a quantity` with :func:`quantity::count()` or to +extract the :term:`value of a quantity_point` with :func:`quantity_point::relative()` +and pass it to the library's output: .. code-block:: :caption: legacy.h @@ -13,6 +14,7 @@ pass it to the library's output: namespace legacy { void print_eta(double speed_in_mps); + void set_path_position(double meter); } // namespace legacy @@ -20,6 +22,7 @@ pass it to the library's output: #include "legacy.h" #include + #include using namespace units::physical; @@ -34,6 +37,13 @@ pass it to the library's output: legacy::print_eta(quantity_cast(v).count()); } + template + requires Length + void set_path_position(QP p) + { + legacy::set_path_position(quantity_point_cast(p).relative().count()); + } + .. important:: When dealing with a quantity of an unknown ``auto`` type please remember