mirror of
https://github.com/mpusz/mp-units.git
synced 2025-07-29 18:07:16 +02:00
docs: "Scaling overflow prevention" chapter added
This commit is contained in:
@ -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.
|
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
|
## Value conversions summary
|
||||||
|
|
||||||
The table below provides all the value conversion functions that may be run on `x` being the
|
The table below provides all the value conversion functions that may be run on `x` being the
|
||||||
|
Reference in New Issue
Block a user