diff --git a/docs/blog/posts/2.4.0-released.md b/docs/blog/posts/2.4.0-released.md index 4b8f3520..714379b4 100644 --- a/docs/blog/posts/2.4.0-released.md +++ b/docs/blog/posts/2.4.0-released.md @@ -1,6 +1,6 @@ --- draft: true -date: 2024-10-27 +date: 2024-11-05 authors: - mpusz categories: @@ -18,7 +18,7 @@ This release was unexpected. We planned a significant new feature to happen next preparing for it, and also while writing API Reference documentation, we made so many vital fixes and improvements that we decided that they deserve a dedicated release first. -This post describes the most significant improvements, while a much longer list of the changes +This post describes the most significant improvements while a much longer list of the changes introduced by the new version can be found in our [Release Notes](../../release_notes.md#2.4.0). @@ -32,7 +32,7 @@ in this release, we moved all of them to the `isq` namespace (:boom: **breaking From now on, `iec` namespace does not provide any quantities and serves purely as a system of units definition. It contains binary prefixes (based on the powers of two) and some units introduced -by IEC (e.g. `var`, `erlang`, `bit`, or ``baud`). +by IEC (e.g., `var`, `erlang`, `bit`, or ``baud`). !!! note @@ -40,16 +40,16 @@ by IEC (e.g. `var`, `erlang`, `bit`, or ``baud`). Also, it turns out that the latest ISO 80000-3 revision makes a small cleanup to the `phase_speed` and `group_speed` quantities. Those were always defined as scalar quantities but also had -alternative names `phase_velocity` and `group_velocity`. Those were misleading as _velocity_ is -typically considered a vector quantity. This is why those `XXX_velocity` aliases were -removed (:boom: **breaking change** :boom:). +alternative names `phase_velocity` and `group_velocity`. This is misleading as _velocity_ is +typically considered a vector quantity. It is why those `XXX_velocity` aliases were removed from +the ISO standard and from **mp-units** library (:boom: **breaking change** :boom:). ## Units equality Previously we assumed that units like `J`, `N m`, and `kg m²/s²` are equal. In some cases, -this might not be entirely correct. Some quantities require a derived unit instead of a unit with -a special name. For example: +this might not be entirely correct. Some quantities require a specific derived unit instead of +a unit with a special name. For example: - `N m` should be used for _moment of force_ (instead of `J`), - `V A` should be used for _apparent power_ (instead of `W`). @@ -74,10 +74,10 @@ From the very beginning, the text output of symbols could be formatted in two di Even though those terms are widely understood in the C++ community, they are technically incorrect. -During the recent SG16 (WG21 Unicode Study Group) meeting, we looked for proper alternatives -and ended up with the "portable" and "UTF-8" terms (:boom: **breaking change** :boom:). +During the recent SG16 meeting, we looked for proper alternatives and ended up with the "portable" +and "UTF-8" terms (:boom: **breaking change** :boom:). -From now on we will provide the following: +From now on, we will provide the following: - `text_encoding::utf8`, `symbol_text::utf8()`, and `U` formatting option, - `text_encoding::portable`, `symbol_text::portable()`, and `P` formatting option. @@ -87,6 +87,8 @@ From now on we will provide the following: The old identifiers and formatting options are now deprecated and will be removed in future releases. +*[SG16]: WG21 Unicode Study Group + ## `char_traits` removed from `fixed_string` @@ -95,7 +97,7 @@ During the same SG16 meeting, the room was strongly against providing `char_trai (:boom: **breaking change** :boom:). -## Improved units text output +## Improved units' text output In the previous release, we introduced common unit abstraction. Initially, all its components were printed in parenthesis which contained a list of all the scaled units separated with `=`. @@ -154,7 +156,7 @@ prints: 6.7 × 10⁻² l/km ``` -One more change that we can see above is that litres now use "L" instead of "l" for the symbol. +One more change that we can see above is that litre now use 'L' instead of 'l' for its symbol. The latter one too often is confused with the number `1`. The next improvement adds proper formatting support for magnitudes. All of the formatting options @@ -188,7 +190,9 @@ The example above introduced something interesting: a `π` identifier for a vari latest changes to the C++ language, we can officially use Unicode symbols as identifiers in the C++ code. -In this release, we've added support for those not only for `π` but also for unit symbols. +In this release, we've added Unicode identifiers support not only for `π` magnitude constant +but also for unit symbols. + Now we can type the following: === "With UTF-8 glyphs" @@ -208,3 +212,90 @@ Now we can type the following: This might make the source code easier to understand, but typing those identifiers can be tricky. Sometimes, the best solution to type it might be a copy-paste approach. If we do not like this idea, we can still use old portable identifiers for those as well. + + +## Convertibility with `QuantityLike` and `QuantityPointLike` entities + +In this release, we decided to fine-tune further the traits that customize the conversion between +custom quantity and quantity point types and the ones provided with **mp-units** +(:boom: **breaking change** :boom:). + +Previously, `to_numerical_value` and `from_numerical_value` returned a type wrapped in a special +tag type describing the conversion type (explicit or implicit). + +This was a novel and experimental approach. Finally, we decided not to do it and used a bit more +verbose but a more standard solution. From now on, we need to provide two additional static data +members of type `bool`: + +- `explicit_import` - `true` means that the conversion to the **mp-units** abstraction is explicit, +- `explicit_export` - `true` means that the conversion from the **mp-units** abstraction is + explicit. + +=== "Now" + + ```cpp + template<> + struct mp_units::quantity_point_like_traits { + static constexpr auto reference = si::second; + static constexpr auto point_origin = default_point_origin(reference); + static constexpr bool explicit_import = false; + static constexpr bool explicit_export = true; + using rep = decltype(Timestamp::seconds); + + static constexpr rep to_numerical_value(Timestamp ts) + { + return ts.seconds; + } + + static constexpr Timestamp from_numerical_value(rep v) + { + return Timestamp(v); + } + }; + ``` + +=== "Before" + + ```cpp + template<> + struct mp_units::quantity_point_like_traits { + 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); + } + }; + ``` + + +## Symbolic constants implementation should be _implementation-defined_ + +In the process of writing API Reference, we decided to hide all the metadata associated with +symbolic constants - tag types used to define units, dimensions, quantity specification, etc. +(:boom: **breaking change** :boom:). + +All the types and values exposed by such types are needed only in the implementation details +of the library. Users should not need them. Hiding those and making them +_implementation-defined_ gives other vendors the freedom to choose different ways to implement +features of this library in their codebases. + +!!! important + + Based on [Hyrum's Law](https://www.hyrumslaw.com/) some users may depend on this + information already, and this release will break their code. + + If that is the case for you, we would love to hear about your use case and its rationale. + It may mean that we should either: + + - extend the library's functionality to support your use case out of the box and keep those + members hidden, + - restore public visibility of such members and enforce this in the API Reference so that all + the users of various library implementations may use them in the same way as you.