diff --git a/docs/blog/posts/2.3.0-released.md b/docs/blog/posts/2.3.0-released.md index 4ce6bd87..b843e1d0 100644 --- a/docs/blog/posts/2.3.0-released.md +++ b/docs/blog/posts/2.3.0-released.md @@ -1,6 +1,5 @@ --- -draft: true -date: 2024-09-24 +date: 2024-09-27 authors: - mpusz categories: @@ -115,7 +114,7 @@ of the affine space abstractions and how they influence temperature handling. After a lengthy discussion on handling such scenarios, we decided to: -- make the above code ill-formed (:boom: **breaking change** :boom:), +- make the above code deprecated (:boom: **breaking change** :boom:), - provide an alternative way to create a `quantity` with the `delta` quantity construction helper. Here are the main points of this new design: @@ -198,12 +197,12 @@ approach required additional types to be introduced for no good reason. static constexpr auto reference = si::second; static constexpr auto point_origin = default_point_origin(reference); using rep = decltype(Timestamp::seconds); - + static constexpr convert_implicitly to_numerical_value(Timestamp ts) { return ts.seconds; } - + static constexpr convert_explicitly from_numerical_value(rep v) { return Timestamp(v); @@ -219,12 +218,12 @@ approach required additional types to be introduced for no good reason. static constexpr auto reference = si::second; static constexpr auto point_origin = default_point_origin(reference); using rep = decltype(Timestamp::seconds); - + static constexpr convert_implicitly> to_quantity(Timestamp ts) { return ts.seconds * si::second; } - + static constexpr convert_explicitly from_quantity(quantity q) { return Timestamp(q.numerical_value_ref_in(si::second)); @@ -232,6 +231,11 @@ approach required additional types to be introduced for no good reason. }; ``` +!!! note + + The old behavior is deprecated and will be removed in future releases. + + ## `mag` With this release, we introduced a new strongly-typed constant to create a magnitude involving @@ -252,6 +256,88 @@ is more consistent: inline constexpr struct degree final : named_unit<{u8"°", "deg"}, mag_pi / mag<180> * si::radian> {} degree; ``` +!!! note + + The old `mag_pi` helper is marked as deprecated and will be removed in future releases. + + +## Common units + +Adding or subtracting two quantities of different units will force the library to find a common +unit for those. This is to prevent data truncation. For the cases when one of the units is an +integral multiple of the another, the resulting quantity will use a "smaller" one in its result. +For example: + +```cpp +static_assert((1 * kg + 1 * g).unit == g); +static_assert((1 * km + 1 * mm).unit == mm); +static_assert((1 * yd + 1 * mi).unit == yd); +``` + +However, in many cases an arithmetic on quantities of different units will result in a yet another +unit. This happens when none of the source units is an integral multiple of another. In such cases, +the library returns a special type that denotes that we are dealing with a common unit of such +an equation. + +Previously we returned a scaled unit calculated against our arbitrarily appointed reference unit. +This resulted often in a long and messy type exposing the prime-factorized magnitude of the unit +(implementation detail). In this release, we introduced a new `common_unit` wrapper for such cases: + +=== "Now" + + ```cpp + quantity q = 1 * km + 1 * mi; // quantity>{}, int> + ``` + +=== "Before" + + ```cpp + quantity q = 1 * km + 1 * mi; // quantity{}, power_v<5, -3>{}>{}, si::metre>{}, int> + ``` + +!!! note + + A user should never explicitly instantiate a `common_unit` class template. The library's + framework will do it based on the provided quantity equation. + +Such units need special printing rules for their symbols. As they represent a minimum set of common +units resulting from the addition or subtraction of multiple quantities, from this release, we +print all of them as a scaled version of the source unit. Previously we were printing them relative +to some arbitrary reference unit (implementation detail) that often was not spelled by the user at +all in the source code. For example the following: + +```cpp +std::cout << 1 * km + 1 * mi << "\n"; +std::cout << 1 * nmi + 1 * mi << "\n"; +std::cout << 1 * km / h + 1 * m / s << "\n"; +``` + +will print: + +=== "Now" + + ```text + 40771 ([1/25146] mi = [1/15625] km) + 108167 ([1/50292] mi = [1/57875] nmi) + 23 ([1/5] km/h = [1/18] m/s) + ``` + +=== "Before" + + ```text + 40771 [8/125] m + 108167 [4/125] m + 23 [1/18] m/s + ``` + +Thanks to the above, it might be easier for the user to reason about the magnitude of the resulting +unit and its impact on the value stored in the quantity. + +!!! info + + In order to provide `common_unit` strong type unit wrapper we had to rename all the + `common_XXX()` functions to `get_common_XXX()` (:boom: **breaking change** :boom:). + ## Superpowers of the unit `one` @@ -266,7 +352,7 @@ In this release, we also added a long-awaited change. From now on a quantity of ```cpp quantity inc(quantity q) { return q + 1; } void legacy(double) { /* ... */ } - + if (auto q = inc(42); q != 0) legacy(static_cast(q)); ``` @@ -365,10 +451,16 @@ From now on, every named unit in the library can be prefixed with the SI or IEC ## `iec80000` system renamed to `iec` As we mentioned IEC already, in this release, we decided to rename the name of the system and its -corresponding namespace from `iec80000` to `iec` (:boom: **breaking change** :boom:). +corresponding namespace from `iec80000` to `iec` (:boom: **breaking change** :boom:). This involves +renaming of a defining header file and of the namespace it provides. -This should be easier to type and is more correct for some quantities and units that are introduced -by IEC but not necessarily in the ISO/IEC 80000 series of documents (e.g., `iec::var`). +Wit this change it should be easier to type and is more correct for some quantities and units that +are introduced by IEC but not necessarily in the ISO/IEC 80000 series of documents (e.g., `iec::var`). + +!!! note + + The old `iec80000` namespace in _iec8000.h_ is marked as deprecated and will be removed in + future releases. ## Error messages-related improvements