From 8cd7f5084e3fa1f3db6ca7595ffa1eb606cb81cf Mon Sep 17 00:00:00 2001 From: Mateusz Pusz Date: Tue, 29 Oct 2024 10:18:57 +0100 Subject: [PATCH] docs: quantity arithmetics chapter updated with improved quantity compoud assignment --- .../framework_basics/quantity_arithmetics.md | 30 ++++++++----------- 1 file changed, 12 insertions(+), 18 deletions(-) diff --git a/docs/users_guide/framework_basics/quantity_arithmetics.md b/docs/users_guide/framework_basics/quantity_arithmetics.md index 929f0877..f386e564 100644 --- a/docs/users_guide/framework_basics/quantity_arithmetics.md +++ b/docs/users_guide/framework_basics/quantity_arithmetics.md @@ -89,29 +89,23 @@ static_assert(isq::radius(1 * m) - 0.5 * m == isq::radius(0.5 * m)); !!! note - Please note that for the compound assignment operators, both arguments have to either be of - the same type or the RHS has to be implicitly convertible to the LHS, as the type of - LHS is always the result of such an operation: + Please note that for the compound assignment operators, we always need to end up with the + left-hand-side argument type: ```cpp - static_assert((1 * m += 1 * km) == 1001 * m); + static_assert((1 * m += 1.5 * m) == 2 * m); + static_assert((1 * m += 1.5 * km) == 1501 * m); + static_assert((isq::length(1 * m) += isq::height(1 * m)) == isq::length(1 * m)); static_assert((isq::height(1.5 * m) -= 1 * m) == isq::height(0.5 * m)); ``` - If we break those rules, the following code will not compile: + If we will break typical library's convertibility rules, the following code will not compile: ```cpp - static_assert((1 * m -= 0.5 * m) == 0.5 * m); // Compile-time error(1) - static_assert((1 * km += 1 * m) == 1001 * m); // Compile-time error(2) - static_assert((isq::height(1 * m) += isq::length(1 * m)) == 2 * m); // Compile-time error(3) + quantity q1 = 1 * km += 1 * m; // Compile-time error + quantity q2 = isq::height(1 * m) += isq::length(1 * m) // Compile-time error ``` - 1. The floating-point to integral representation type is [considered narrowing](value_conversions.md). - 2. Conversion of quantity with integral representation type from a unit of a higher resolution to the one - with a lower resolution is [considered narrowing](value_conversions.md). - 3. Conversion from a more generic quantity type to a more specific one is - [considered unsafe](simple_and_typed_quantities.md#quantity_cast-to-force-unsafe-conversions). - ## Multiplication and division @@ -124,14 +118,14 @@ static_assert(isq::height(3 * m) * 0.5 == isq::height(1.5 * m)); !!! note - Unless we use a compound assignment operator, in which case truncating operations are again not allowed: + Unless we use a compound assignment operator, in which case we will always result with the type + of the left-hand-side argument and the value consistent to the behavior of the underlying + representation types: ```cpp - static_assert((isq::height(3 * m) *= 0.5) == isq::height(1.5 * m)); // Compile-time error(1) + static_assert((isq::height(3 * m) *= 0.5) == isq::height(1 * m)); ``` - 1. The floating-point to integral representation type is [considered narrowing](value_conversions.md). - However, suppose we multiply or divide quantities of the same or different types or we divide a raw number by a quantity. In that case, we most probably will end up in a quantity of yet another type: