Merge remote-tracking branch 'upstream/master' into feature/fixed-poi…

…nt-multiplication-for-integral-conversion

.github/workflows/ci-clang-tidy.yml

@@ -24,9 +24,13 @@ name: clang-tidy CI
 
 on:
   push:
+    branches:
+      - '**'
     paths-ignore:
       - "docs/**"
   pull_request:
+    branches:
+      - '**'
     paths-ignore:
       - "docs/**"
 

.github/workflows/ci-freestanding.yml

@@ -24,9 +24,13 @@ name: Freestanding CI
 
 on:
   push:
+    branches:
+      - '**'
     paths-ignore:
       - "docs/**"
   pull_request:
+    branches:
+      - '**'
     paths-ignore:
       - "docs/**"
 

.github/workflows/ci-test-package-cmake.yml

@@ -24,11 +24,15 @@ name: CMake Test Package CI
 
 on:
   push:
+    branches:
+      - '**'
     paths-ignore:
       - "docs/**"
       - "example/**"
       - "test/**"
   pull_request:
+    branches:
+      - '**'
     paths-ignore:
       - "docs/**"
       - "example/**"

.github/workflows/documentation.yml

@@ -27,6 +27,13 @@ on:
     branches:
       - master
       - main
+    tags:
+      - v*
+    paths:
+      - "docs/**"
+      - "CHANGELOG.md"
+      - "CONTRIBUTING.md"
+      - "mkdocs.yml"
 permissions:
   contents: write
 jobs:

CHANGELOG.md

@@ -2,7 +2,9 @@
 
 ## mp-units
 
-### 2.4.0 <small>WIP</small> { id="2.4.0" }
+### 2.5.0 <small>WIP</small> { id="2.5.0" }
+
+### 2.4.0 <small>November 5, 2024</small> { id="2.4.0" }
 
 - (!) feat: `phase_velocity` and `group_velocity` aliases removed from ISQ by ISO
 - feat: `iec::bit` using-declared in `iec::unit_symbols`
@@ -13,7 +15,7 @@
 - feat: tag types are now required to be empty
 - feat: magnitude text now obeys formatting parameters and knows how to print constants
 - feat: added support for printing powers of magnitude constants
-- feat: `TagType` concept added
+- feat: `SymbolicConstant` concept added
 - feat: `common_unit` selection algorithm improved to make `rev + rad` return `rad`
 - feat: litre text symbol changed from `l` to `L` to avoid ambiguity with `1`
 - feat: alternative litre unit symbol `L` added to prevent ambiguities with `1`
@@ -23,13 +25,17 @@
 - feat: `DerivedDimensionExpr`, `DerivedQuantitySpecExpr` and `DerivedUnitExpr` removed
 - feat: `MagnitudeSpecExpr` and `PowerVBase` removed and some functions renamed to limit possible ambiguity in overload resolution
 - feat: `std::is_object` constraint applied to `value_type_t`
+- feat: `quantity_values` are now defined on top of `std::chrono::duration_values`
+- feat: from now on truncation is not allowed in compound assignment
 - feat(example): currency example now uses `chrono::time_point` and has better interfaces
 - feat(example): `treat_as_floating_point` specializations for examples' types removed
 - (!) refactor: all `iec` quantity specifications are now deprecated and moved to `isq`
 - (!) refactor: `mag_constant` now takes a symbol and a value and the class deriving from it must be final
 - (!) refactor: `op==(U1, U2)` now checks for the same type (old behavior available as `equivalent(U1, U2)`) + `convertible` now verifies associated `quantity_spec` as well
 - (!) refactor: `ascii` -> `portable`, `unicode` -> `utf8`, 'A' -> 'P'
-- (!) refactor: :boom: `char_traits` removed from `fixed_string`
+- (!) refactor: `char_traits` removed from `fixed_string`
+- (!) refactor: convertibility traits and concepts refactored to use `bool` flags instead of wrappers
+- (!) refactor: tag types should not expose their members
 - refactor: `convertible(U1, U2)` implementation simplified
 - refactor: `abs` moved to `constexpr_math.h`
 - refactor: `unit_symbol_impl` simplified
@@ -45,6 +51,13 @@
 - refactor: `treat_as_floating_point` simplified and extended to use `std::chrono::treat_as_floating_point_v`
 - refactor: `wrapped_type_t` reuses `std::indirectly_readable_traits`
 - refactor: `expr_fractions` takes direct `OneType` type now instead of a trait
+- refactor: Unicode symbols description reworked based on the latest SG16 recommendations
+- refactor: `Mutable` concept applied to `quantity` and `quantity_point`
+- refactor: `explicit` cleanup for deduction guides of `quantity` and `quantity_point`
+- refactor: `point_origin_interface::op-` cleanup
+- refactor: `QuantityLikeImpl` refactored to conform to API Reference by @JohelEGP
+- refactor: `get_complexity` refactored to be 0-based and not account for a number of arguments in a list
+- refactor: `get_complexity` refactored to returned maximum complexity of an element (instead of the sum of elements)
 - refactor(test): `derived_quantity` refactored to `child_quantity`
 - fix: missing `are_ingredients_convertible` overloads added
 - fix: constraints for magnitude added for `scaled_unit` and fixed `common_unit` instantiating it incorrectly
@@ -56,25 +69,34 @@
 - fix: `operator*(M, U u)` fixed for `U` being `scaled_unit`
 - fix: subsumption of `QuantityKindSpec` fixed
 - fix: `ValuePreservingTo` fixed to apply `std::remove_cvref_t` on `FromRep`
+- fix: compound assignment operations on quantities now behave the same as on the underlying representation types
+- fix: `QuantityConvertibleTo` used in `quantity_point` compound assignment
+- fix: `convertible_kinds` implementation fixed
 - fix(tests): freestanding build fixed
 - test: unit tests for the inverse of `mag_constant` added
 - test: Unicode symbols used in unit tests
 - test: more `std::chrono` tests added
 - test: commutativity tests added to ISQ
 - test: one `kind_of` test added to reference tests
 - test: `pow<0>` and `pow<1>` tests added for dimensions
+- test: more `get_common_quantity_spec` tests added
 - build: setting of some test_package CMake options enabled only for a `cxx_modules` build
 - ci: `sudo apt update` added for documentation.yml in hope that it will resolve missing system packages issue
 - ci: MSVC added to the CI
+- ci: the latest not-released docs will use "HEAD" as a version from now on
+- ci: documentation action should run on a new tag as well
+- ci: documentation action limited only to commits that change documentation files
+- ci: non-documentation actions should not run on tags
 - docs: missing systems added to the "Project Structure" chapter
 - docs: graphs of ISQ kind hierarchies improved
 - docs: category of the ISO meeting reports changed to "WG21 Updates"
 - docs: blog comments support added
-- docs: articles of the ISQ series added
+- docs: Part 1-5 articles of the ISQ series added
 - docs: "Symbols of scaled units" chapter added + minor updates to scaled and common units chapters
 - docs: conan profile updated to present gcc-14 instead of gcc-12 which is no longer supported
 - docs: "Why derived units order is not preserved from the multiplication?" chapter added to FAQ
 - docs: "Many shades of the same unit" extended with a note about the derived units order
+- docs: API Reference now presents _index.html_ instead of _full.hml_
 
 ### 2.3.0 <small>September 27, 2024</small> { id="2.3.0" }
 

CITATION.cff

@@ -40,9 +40,9 @@ repository-code: "https://github.com/mpusz/mp-units"
 url: "https://mpusz.github.io/mp-units"
 repository-artifact: "https://conan.io/center/mp-units"
 
-version: 2.3.0
-date-released: "2024-09-27"
+version: 2.4.0
+date-released: "2024-11-05"
 identifiers:
-  - description: "The GitHub release URL of tag 2.3.0"
+  - description: "The GitHub release URL of tag 2.4.0"
     type: url
-    value: "https://github.com/mpusz/mp-units/releases/tag/v2.3.0"
+    value: "https://github.com/mpusz/mp-units/releases/tag/v2.4.0"

README.md

@@ -11,7 +11,7 @@
 [![GitHub Workflow Documentation](https://img.shields.io/github/actions/workflow/status/mpusz/mp-units/documentation.yml?branch=master&label=Documentation)](https://github.com/mpusz/mp-units/actions?query=workflow%3ADocumentation+branch%3Amaster)
 
 [![Conan stable](https://img.shields.io/conan/v/mp-units?label=ConanCenter&color=blue)](https://conan.io/center/mp-units)
-[![Conan testing](https://img.shields.io/badge/mpusz.jfrog.io-2.4.0%3Atesting-blue)](https://mpusz.jfrog.io/ui/packages/conan:%2F%2Fmp-units/2.4.0)
+[![Conan testing](https://img.shields.io/badge/mpusz.jfrog.io-2.5.0%3Atesting-blue)](https://mpusz.jfrog.io/ui/packages/conan:%2F%2Fmp-units/2.5.0)
 
 
 # `mp-units` - The quantities and units library for C++

docs/blog/posts/2.4.0-released.md

@@ -1,6 +1,5 @@
 ---
-draft: true
-date: 2024-10-27
+date: 2024-11-05
 authors:
  - mpusz
 categories:
@@ -18,7 +17,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,24 +31,24 @@ 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
 
     The quantities in `iec` namespace are now deprecated and will be removed in future releases.
 
 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 +73,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 +86,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 +96,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 +155,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 +189,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 +211,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.

docs/getting_started/installation_and_usage.md

@@ -265,7 +265,7 @@ The following steps may be performed to obtain an official library release:
 
     ```ini title="conanfile.txt"
     [requires]
-    mp-units/2.3.0
+    mp-units/2.4.0
 
     [options]
 
@@ -323,7 +323,7 @@ with the following differences:
 
     ```ini title="conanfile.txt" hl_lines="2"
     [requires]
-    mp-units/2.4.0@mpusz/testing
+    mp-units/2.5.0@mpusz/testing
 
     [options]
 

src/CMakeLists.txt

@@ -21,7 +21,7 @@
 # SOFTWARE.
 
 cmake_minimum_required(VERSION 3.25)
-project(mp-units VERSION 2.4.0 LANGUAGES CXX)
+project(mp-units VERSION 2.5.0 LANGUAGES CXX)
 
 set(projectPrefix MP_UNITS_)