Merge branch 'master' into feature/more-value-casts

This commit is contained in:
Yves Delley
2024-06-02 08:03:30 +02:00
97 changed files with 2063 additions and 941 deletions

View File

@@ -31,12 +31,12 @@ the C++ modules' support is still really limited.
To benefit from C++ modules, we need at least:
- CMake 3.28.1
- CMake 3.29.3
- Ninja 1.11
- clang-17
In the upcoming months, hopefully, the situation will improve with the gcc-14 release and
bug fixes in MSVC.
In the upcoming months, hopefully, the situation will improve with the bug fixes in
CMake, gcc-14, and MSVC.
!!! note
@@ -64,6 +64,11 @@ flowchart TD
The easiest way to use them is just to `import mp_units;` at the beginning of your translation unit
(see the [Quick Start](../../getting_started/quick_start.md) chapter for some usage examples).
!!! note
C++20 modules support still have some issues when imported from the installed CMake target.
See the following [GitLab issue for more details](https://gitlab.kitware.com/cmake/cmake/-/issues/25909#note_1525377).
In this release, we also highly limited the number of CMake targets (:boom: **breaking change** :boom:).
Now, they correspond exactly to the C++ modules they provide. This means that many smaller partial
targets were removed. We also merged text output targets with the core library's definition.
@@ -93,9 +98,9 @@ In version 2.2, the following headers have a new location or contents:
Benefiting from this opportunity, we also cleaned up core and systems definitions
(:boom: **breaking change** :boom:).
Regarding the library's core, we exposed only one header `framework.h` that exposes all of
the library's framework so the user does not have to enumerate files like `unit.h`, `quantity.h`,
and `quantity_point.h` anymore. Those headers are not gone, they were put to
Regarding the library's core, we removed `core.h` and exposed only one header `framework.h` that
provides all of the library's framework so the user does not have to enumerate files like `unit.h`,
`quantity.h`, and `quantity_point.h` anymore. Those headers are not gone, they were put to
the `mp-units/framework` subheader. So they are still there if you really need them.
Regarding the changes in systems definitions, we moved the wrapper header files with the entire
@@ -161,6 +166,21 @@ Additionally, some CMake options were renamed to better express the impact on ou
- `MP_UNITS_DEV_*` - options primarily useful for the project developers or people who want to
compile our unit tests and examples.
## Configurable contracts checking
Before this release, the library always depended on [gsl-lite](https://github.com/gsl-lite/gsl-lite)
to perform runtime contract and asserts checking. In this release we introduced new options
to control if contract checking should be based on [gsl-lite](https://github.com/gsl-lite/gsl-lite),
[ms-gsl](https://github.com/microsoft/GSL), or maybe completely disabled.
## Freestanding support
From this release it is possible to configure the library in the
[freestanding](https://en.cppreference.com/w/cpp/freestanding) mode. This limits the functionality
and interface of the library to be compatible with the freestanding implementations.
!!! info
To learn more, please refer to the [Build options](../../getting_started/installation_and_usage.md#build-options)
@@ -191,7 +211,7 @@ origins. For example:
```
As we can see above, the new design allows
[direct-initialization](https://en.cppreference.com/w/cpp/language/direct_initialization) of a
[direct-initializing](https://en.cppreference.com/w/cpp/language/direct_initialization)
`quantity_point` class template from a `quantity`, but only if the former one is defined in terms
of the implicit point origin. Otherwise, an explicit origin still always has to be provided during
initialization.
@@ -199,7 +219,7 @@ initialization.
Also, we introduced the possibility of specifying a default point origin in the unit definition.
With that, we could provide proper temperature scales without forcing the user to always use
the origins explicitly. Also, a new member function, `.quantity_from_zero(),` was introduced
that always returns the quantity from the unit's specific point origin or from the absolute
that always returns the quantity from the unit's specific point origin or from the implicit
point origin otherwise.
=== "Now"
@@ -244,20 +264,30 @@ named with its corresponding unit and with the `si::zeroth_degree_Celsius`
about potential ABI issues when different translation units are compiled with different ordinary
literal encodings. Those issues were resolved with a change to units definitions
(:boom: **breaking change** :boom:). It affects only units that specify both Unicode and ASCII
symbols. The new design requires the Unicode symbol to be provided as a UTF-8 literal:
symbols. The new design requires the Unicode symbol to be provided as a UTF-8 literal.
This also means that the `basic_symbol_text` has fixed character types for both symbols. This
is why it was renamed to `symbol_text` (:boom: **breaking change** :boom:).
=== "Now"
```cpp
inline constexpr struct ohm : named_unit<{u8"Ω", "ohm"}, volt / ampere> {} ohm;
inline constexpr struct ohm : named_unit<symbol_text{u8"Ω", "ohm"}, volt / ampere> {} ohm;
```
=== "Before"
```cpp
inline constexpr struct ohm : named_unit<{"Ω", "ohm"}, volt / ampere> {} ohm;
inline constexpr struct ohm : named_unit<basic_symbol_text{"Ω", "ohm"}, volt / ampere> {} ohm;
```
!!! note
On C++20-compliant compilers it should be enough to type the following in the unit's definition:
```cpp
inline constexpr struct ohm : named_unit<{u8"Ω", "ohm"}, volt / ampere> {} ohm;
```
## Improved text output
@@ -333,7 +363,7 @@ Example 1 (clang):
61 | concept QuantityOf = Quantity<Q> && QuantitySpecOf<std::remove_const_t<decltype(Q::quantity_spec)>, QS>;
| ^
note: because 'implicitly_convertible(kind_of_<derived_quantity_spec<isq::time, per<isq::length> > >{}, struct speed{{{}}})' evaluated to false
147 | QuantitySpec<T> && QuantitySpec<std::remove_const_t<decltype(QS)>> && implicitly_convertible(T{}, QS) &&
147 | QuantitySpec<T> && QuantitySpec<decltype(QS)> && implicitly_convertible(T{}, QS) &&
| ^
1 error generated.
Compiler returned: 1
@@ -356,7 +386,7 @@ Example 1 (clang):
61 | concept QuantityOf = Quantity<Q> && QuantitySpecOf<std::remove_const_t<decltype(Q::quantity_spec)>, QS>;
| ^
note: because 'implicitly_convertible(kind_of_<derived_quantity_spec<isq::time, per<isq::length> >{{}, {{}}}>{}, struct speed{{{}}})' evaluated to false
147 | QuantitySpec<T> && QuantitySpec<std::remove_const_t<decltype(QS)>> && implicitly_convertible(T{}, QS) &&
147 | QuantitySpec<T> && QuantitySpec<decltype(QS)> && implicitly_convertible(T{}, QS) &&
| ^
1 error generated.
Compiler returned: 1

View File

@@ -13,13 +13,13 @@
The table below provides the minimum compiler version required to compile the code using a specific
C++ feature:
| C++ Feature | C++ version | gcc | clang | apple-clang | MSVC |
|-----------------------------------------------------------|:-----------:|:---:|:-----:|:-----------:|:----:|
| **Minimum support** | 20 | 12 | 16 | 15 | None |
| **`std::format`** | 20 | 13 | 17 | None | None |
| **C++ modules** | 20 | 14 | 17 | None | None |
| **Static `constexpr` variables in `constexpr` functions** | 23 | 13 | 17 | None | None |
| **Explicit `this` parameter** | 23 | 14 | 18 | None | None |
| C++ Feature | C++ version | gcc | clang | apple-clang | MSVC |
|-----------------------------------------------------------|:-----------:|:----:|:-----:|:-----------:|:----:|
| **Minimum support** | 20 | 12 | 16 | 15 | None |
| **`std::format`** | 20 | 13 | 17 | None | None |
| **C++ modules** | 20 | None | 17 | None | None |
| **Static `constexpr` variables in `constexpr` functions** | 23 | 13 | 17 | None | None |
| **Explicit `this` parameter** | 23 | 14 | 18 | None | None |
!!! important
@@ -29,7 +29,7 @@ C++ feature:
## `std::format`
- Provides [powerful text formatting capabilities](../users_guide/framework_basics/text_output.md#stdformat)
- Provides [powerful text formatting capabilities](../users_guide/framework_basics/text_output.md#text-formatting)
for C++.
- An alternative [fmtlib](https://github.com/fmtlib/fmt) library can be used instead if
- the C++ language feature is not supported,

View File

@@ -176,7 +176,7 @@ we have to obey the rules and be consistent with ISO specifications.
!!! note
We do understand engineering reality and the constraints of some environments. This is why the library
has the option of [ASCII-only Quantity Symbols](../users_guide/framework_basics/text_output.md#unit-symbol-formatting).
has the option of [ASCII-only Quantity Symbols](../users_guide/framework_basics/text_output.md#unit_symbol_formatting).
## Why don't we have CMake options to disable the building of tests and examples?

View File

@@ -18,8 +18,8 @@ projects:
- in case this library becomes part of the C++ standard, it will have no external dependencies
but until then, it depends on the following:
- [gsl-lite](https://github.com/gsl-lite/gsl-lite) to verify runtime contracts with
the `gsl_Expects` macro,
- [gsl-lite](https://github.com/gsl-lite/gsl-lite) or [ms-gsl](https://github.com/microsoft/GSL)
to verify runtime contracts (if contract checking is enabled),
- [{fmt}](https://github.com/fmtlib/fmt) to provide text formatting of quantities
(if `std::format` is not supported yet on a specific compiler).
@@ -56,7 +56,7 @@ projects:
handle the dependencies.
To learn more about the rationale, please check our
[FAQ](faq.md#why-dont-we-have-cmake-options-to-disable-building-of-tests-and-examples).
[FAQ](faq.md#why-dont-we-have-cmake-options-to-disable-the-building-of-tests-and-examples).
### Modules
@@ -229,7 +229,7 @@ tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"}
### Conan options
[cxx_modules](#cxx_modules){ #cxx_modules }
[`cxx_modules`](#cxx_modules){ #cxx_modules }
: [:octicons-tag-24: 2.2.0][conan C++ modules support] · :octicons-milestone-24: `auto`/`True`/`False` (Default: `auto`)
@@ -237,7 +237,7 @@ tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"}
[conan C++ modules support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[std_format](#std_format){ #std_format }
[`std_format`](#std_format){ #std_format }
: [:octicons-tag-24: 2.2.0][conan std::format support] · :octicons-milestone-24: `auto`/`True`/`False` (Default: `auto`)
@@ -247,7 +247,7 @@ tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"}
[conan std::format support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[string_view_ret](#string_view_ret){ #string_view_ret }
[`string_view_ret`](#string_view_ret){ #string_view_ret }
: [:octicons-tag-24: 2.2.0][conan returning string_view] · :octicons-milestone-24: `auto`/`True`/`False` (Default: `auto`)
@@ -259,7 +259,7 @@ tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"}
[conan returning string_view]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[no_crtp](#no_crtp){ #no_crtp }
[`no_crtp`](#no_crtp){ #no_crtp }
: [:octicons-tag-24: 2.2.0][conan no crtp support] · :octicons-milestone-24: `auto`/`True`/`False` (Default: `auto`)
@@ -268,6 +268,24 @@ tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"}
[conan no crtp support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[`contracts`](#contracts){ #contracts }
: [:octicons-tag-24: 2.2.0][conan contracts] · :octicons-milestone-24: `none`/`gsl-lite`/`ms-gsl` (Default: `gsl-lite`)
Enables checking of preconditions and additional asserts in the code.
[conan contracts]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[`freestanding`](#freestanding){ #freestanding }
: [:octicons-tag-24: 2.2.0][conan freestanding] · :octicons-milestone-24: `True`/`False` (Default: `False`)
Configures the library in the [freestanding](https://en.cppreference.com/w/cpp/freestanding)
mode. When enabled, the library's source code should build with the compiler's
[`-ffreestanding`](https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html) compilation option
without any issues.
[conan freestanding]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
### Conan configuration properties
@@ -276,7 +294,7 @@ tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"}
: [:octicons-tag-24: 2.2.0][conan build all support] · :octicons-milestone-24: `True`/`False` (Default: `False`)
Enables compilation of all the source code, including tests and examples. To support this, it requires some additional Conan build dependencies described in
[Repository Structure and Dependencies](#repository-structure-and-dependencies).
[Repository directory tree and dependencies](#repository-directory-tree-and-dependencies).
It also runs unit tests during Conan build (unless
[`tools.build:skip_test`](https://docs.conan.io/2/reference/commands/config.html?highlight=tools.build:skip_test#conan-config-list)
configuration property is set to `True`).
@@ -296,6 +314,14 @@ tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"}
[conan skip la support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[`user.mp-units.analyze:clang-tidy`](#user.mp-units.analyze-clang-tidy){ #user.mp-units.analyze-clang-tidy }
: [:octicons-tag-24: 2.2.0][conan clang-tidy support] · :octicons-milestone-24: `True`/`False` (Default: `False`)
Enables clang-tidy analysis.
[conan clang-tidy support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
### CMake options
[`MP_UNITS_BUILD_AS_SYSTEM_HEADERS`](#MP_UNITS_BUILD_AS_SYSTEM_HEADERS){ #MP_UNITS_BUILD_AS_SYSTEM_HEADERS }
@@ -345,24 +371,50 @@ tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"}
[cmake no crtp support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[`MP_UNITS_API_CONTRACTS`](#MP_UNITS_API_CONTRACTS){ #MP_UNITS_API_CONTRACTS }
: [:octicons-tag-24: 2.2.0][cmake contracts] · :octicons-milestone-24: `NONE`/`GSL-LITE`/`MS-GSL` (Default: `GSL-LITE`)
Enables checking of preconditions and additional asserts in the code.
[cmake contracts]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[`MP_UNITS_API_FREESTANDING`](#MP_UNITS_API_FREESTANDING){ #MP_UNITS_API_FREESTANDING }
: [:octicons-tag-24: 2.2.0][cmake freestanding] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`)
Configures the library in the [freestanding](https://en.cppreference.com/w/cpp/freestanding)
mode. When enabled, the library's source code should build with the compiler's
[`-ffreestanding`](https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html) compilation option
without any issues.
[cmake freestanding]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
#### Options for mp-units project developers
[`MP_UNITS_DEV_BUILD_LA`](#MP_UNITS_DEV_BUILD_LA){ #MP_UNITS_DEV_BUILD_LA }
: [:octicons-tag-24: 2.0.0][build la support] · :octicons-milestone-24: `ON`/`OFF` (Default: `ON`)
: [:octicons-tag-24: 2.2.0][cmake build la support] · :octicons-milestone-24: `ON`/`OFF` (Default: `ON`)
Enables building code depending on the linear algebra library.
[build la support]: https://github.com/mpusz/mp-units/releases/tag/v2.0.0
[cmake build la support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[`MP_UNITS_DEV_IWYU`](#MP_UNITS_DEV_IWYU){ #MP_UNITS_DEV_IWYU }
: [:octicons-tag-24: 2.0.0][iwyu support] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`)
: [:octicons-tag-24: 2.2.0][cmake iwyu support] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`)
Enables `include-what-you-use` when compiling with a clang compiler.
Enables include-what-you-use analysis.
[iwyu support]: https://github.com/mpusz/mp-units/releases/tag/v2.0.0
[cmake iwyu support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[`MP_UNITS_DEV_CLANG_TIDY`](#MP_UNITS_DEV_CLANG_TIDY){ #MP_UNITS_DEV_CLANG_TIDY }
: [:octicons-tag-24: 2.2.0][cmake clang-tidy support] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`)
Enables clang-tidy analysis.
[cmake clang-tidy support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
## CMake with presets support

View File

@@ -80,6 +80,6 @@ To achieve this goal, several techniques are applied:
[Highly adjustable text-output formatting]: ../users_guide/framework_basics/text_output.md
[Each entity can be defined with a single line of code]: ../users_guide/framework_basics/interface_introduction.md#new-style-of-definitions
[User can easily extend the systems with custom dimensions, quantities, and units]: ../users_guide/use_cases/extending_the_library.md#new-style-of-definitions
[User can easily extend the systems with custom dimensions, quantities, and units]: ../users_guide/use_cases/extending_the_library.md
[freestanding]: https://en.cppreference.com/w/cpp/freestanding

View File

@@ -150,7 +150,7 @@ performed without sacrificing accuracy. Please see the below example for a quick
}
```
!!! example "[Try it on Compiler Explorer](https://godbolt.org/z/fsdovTcYh)"
!!! example "[Try it on Compiler Explorer](https://godbolt.org/z/nhqhT8Mzb)"
!!! note

View File

@@ -95,7 +95,7 @@ and when `T` is implicitly convertible to `V`.
and is satisfied by:
- All units derived from a `named_unit` class template instantiated with a unique symbol identifier
and a [`QuantitySpec`](#quantityspec) of a [quantity kind](../../appendix/glossary.md#kind).
and a [`QuantitySpec`](#QuantitySpec) of a [quantity kind](../../appendix/glossary.md#kind).
- All units being a result of [unit equations](../../appendix/glossary.md#unit-equation) on other
associated units.

View File

@@ -231,8 +231,8 @@ For example:
A unit can be defined by the user in one of the following ways:
```cpp
template<PrefixableUnit auto U> struct kilo_ : prefixed_unit<"k", mag_power<10, 3>, U> {};
template<PrefixableUnit auto U> inline constexpr kilo_<U> kilo;
template<PrefixableUnit U> struct kilo_ : prefixed_unit<"k", mag_power<10, 3>, U{}> {};
template<PrefixableUnit auto U> inline constexpr kilo_<decltype(U)> kilo;
inline constexpr struct second : named_unit<"s", kind_of<isq::time>> {} second;
inline constexpr struct minute : named_unit<"min", mag<60> * second> {} minute;

View File

@@ -137,8 +137,8 @@ unit magnitude in a more flexible way.
Each prefix is implemented similarly to the following:
```cpp
template<PrefixableUnit auto U> struct quecto_ : prefixed_unit<"q", mag_power<10, -30>, U> {};
template<PrefixableUnit auto U> inline constexpr quecto_<U> quecto;
template<PrefixableUnit U> struct quecto_ : prefixed_unit<"q", mag_power<10, -30>, U{}> {};
template<PrefixableUnit auto U> inline constexpr quecto_<decltype(U)> quecto;
```
and then a [PrefixableUnit](concepts.md#PrefixableUnit) can be prefixed in the following
@@ -153,8 +153,8 @@ efficiently represent any rational magnitude. For example, IEC 80000 prefixes us
IT industry can be implemented as:
```cpp
template<PrefixableUnit auto U> struct yobi_ : prefixed_unit<"Yi", mag_power<2, 80>, U> {};
template<PrefixableUnit auto U> inline constexpr yobi_<U> yobi;
template<PrefixableUnit U> struct yobi_ : prefixed_unit<"Yi", mag_power<2, 80>, U{}> {};
template<PrefixableUnit auto U> inline constexpr yobi_<decltype(U)> yobi;
```
## Scaled units

View File

@@ -62,14 +62,14 @@ and units of derived quantities.
=== "Prefixes"
```cpp
template<PrefixableUnit auto U> struct micro_ : prefixed_unit<{u8"µ", "u"}, mag_power<10, -6>, U> {};
template<PrefixableUnit auto U> struct milli_ : prefixed_unit<"m", mag_power<10, -3>, U> {};
template<PrefixableUnit auto U> struct centi_ : prefixed_unit<"c", mag_power<10, -2>, U> {};
template<PrefixableUnit auto U> struct deci_ : prefixed_unit<"d", mag_power<10, -1>, U> {};
template<PrefixableUnit auto U> struct deca_ : prefixed_unit<"da", mag_power<10, 1>, U> {};
template<PrefixableUnit auto U> struct hecto_ : prefixed_unit<"h", mag_power<10, 2>, U> {};
template<PrefixableUnit auto U> struct kilo_ : prefixed_unit<"k", mag_power<10, 3>, U> {};
template<PrefixableUnit auto U> struct mega_ : prefixed_unit<"M", mag_power<10, 6>, U> {};
template<PrefixableUnit U> struct micro_ : prefixed_unit<{u8"µ", "u"}, mag_power<10, -6>, U{}> {};
template<PrefixableUnit U> struct milli_ : prefixed_unit<"m", mag_power<10, -3>, U{}> {};
template<PrefixableUnit U> struct centi_ : prefixed_unit<"c", mag_power<10, -2>, U{}> {};
template<PrefixableUnit U> struct deci_ : prefixed_unit<"d", mag_power<10, -1>, U{}> {};
template<PrefixableUnit U> struct deca_ : prefixed_unit<"da", mag_power<10, 1>, U{}> {};
template<PrefixableUnit U> struct hecto_ : prefixed_unit<"h", mag_power<10, 2>, U{}> {};
template<PrefixableUnit U> struct kilo_ : prefixed_unit<"k", mag_power<10, 3>, U{}> {};
template<PrefixableUnit U> struct mega_ : prefixed_unit<"M", mag_power<10, 6>, U{}> {};
```
=== "Constants"
@@ -241,7 +241,7 @@ static_assert(unit_symbol<{.solidus = unit_symbol_solidus::never,
`std::string_view` is returned only when C++23 is available. Otherwise, an instance of a
`basic_fixed_string` is being returned. See more in the
[C++ compiler support](../../getting_started/installation_and_usage.md#static-constexpr-variables-in-constexpr-functions)
[C++ compiler support](../../getting_started/cpp_compiler_support.md#static-constexpr-variables-in-constexpr-functions)
chapter.
#### `unit_symbol_to()`

View File

@@ -219,7 +219,7 @@ the origin and the _displacement vector_ measured from it to the point we create
[Why can't I create a quantity by passing a number to a constructor?](../../getting_started/faq.md#why-cant-i-create-a-quantity-by-passing-a-number-to-a-constructor)
chapter.
Similarly to [creation of a quantity](../../getting_started/quick_start.md#creating-a-quantity),
Similarly to [creation of a quantity](../../getting_started/quick_start.md#quantities),
if someone does not like the operator-based syntax to create a `quantity_point`, the same results
can be achieved with a two-parameter constructor:
@@ -403,7 +403,7 @@ inline constexpr struct zeroth_degree_Celsius : decltype(ice_point) {} zeroth_de
namespace usc {
inline constexpr struct zeroth_degree_Fahrenheit :
relative_point_origin<si::zeroth_degree_Celsius - 32 * (mag_ratio<5, 9> * si::degree_Celsius)> {} zeroth_degree_Fahrenheit;
relative_point_origin<quantity_point{-32 * (mag_ratio<5, 9> * si::degree_Celsius)}> {} zeroth_degree_Fahrenheit;
}
```