docs: "Scaling overflow prevention" chapter added

This commit is contained in:
Mateusz Pusz
2025-02-06 20:07:05 +01:00
parent 79e88a5ce7
commit ea06827f27

View File

@ -190,6 +190,28 @@ may require an addition of a potentially large offset (the difference between th
which may well be outside the range of one or both quantity types.
## Scaling overflow prevention
In the case of small integral types, it is easy to overflow the representation type for every value
besides `0` while performing simple and popular unit conversions. This is why the library prevents
such invalid conversions at compile-time both for explicit and implicit conversions:
```cpp
quantity q1 = std::int8_t(1) * km;
quantity q2 = q1.force_in(m); // Compile-time error (1)
if(q1 != 1 * m) { /* ... */ } // Compile-time error (2)
```
1. Forced conversion would overflow on scaling.
2. Implicit conversion that brings arguments to a common unit before comparison would overflow on
scaling.
In the above example, the conversion factor between `km` and `m` is `1'000`, which is larger than
the maximum value that can be stored in `std::int8_t`. Even if we want to convert the
smallest possible integral amount (e.g., `1 km`), we will overflow the quantity representation type.
We decided not to allow such conversions for safety reasons despite the value of `0 km` would work.
## Value conversions summary
The table below provides all the value conversion functions that may be run on `x` being the