mirror of
https://github.com/mpusz/mp-units.git
synced 2025-07-29 18:07:16 +02:00
docs: 2.4.0 release announcement updated
This commit is contained in:
Mateusz Pusz
@ -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).
|
||||
|
||||
<!-- more -->
|
||||
@ -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<N, M>::utf8()`, and `U` formatting option,
|
||||
- `text_encoding::portable`, `symbol_text<N, M>::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<Timestamp> {
|
||||
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<Timestamp> {
|
||||
static constexpr auto reference = si::second;
|
||||
static constexpr auto point_origin = default_point_origin(reference);
|
||||
using rep = decltype(Timestamp::seconds);
|
||||
|
||||
static constexpr convert_implicitly<rep> to_numerical_value(Timestamp ts)
|
||||
{
|
||||
return ts.seconds;
|
||||
}
|
||||
|
||||
static constexpr convert_explicitly<Timestamp> 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.
|
||||
|
||||
Reference in New Issue
Block a user