mpusz/mp-units
1
0
Fork 1
mirror of https://github.com/mpusz/mp-units.git synced 2025-08-06 05:34:27 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: q.force_in(U) documentation added

Browse Source
This commit is contained in:
Mateusz Pusz
2023-09-13 10:44:50 +02:00
parent a6284aa293
commit bf954cfcaf
3 changed files with 11 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/users_guide/framework_basics/generic_interfaces.md
View File

@@ -65,11 +65,11 @@ some issues start to be clearly visible:
Trying to use an integral type in this scenario will work only for `s1`, while `s2` and `s3`
will fail to compile. Failing to compile is a good thing here as the library tries to prevent
the user from doing a clearly wrong thing. To make the code compile, the user needs to use
a dedicated [`value_cast`](value_conversions.md#value-truncating-conversions) like this:
dedicated [`value_cast` or `force_in`](value_conversions.md#value-truncating-conversions) like this:
```cpp
quantity<isq::speed[mi / h]> s2 = avg_speed(value_cast<km>(140 * mi), 2 * h);
quantity<isq::speed[m / s]> s3 = avg_speed(value_cast<km>(20 * m), value_cast<h>(2 * s));
quantity<isq::speed[m / s]> s3 = avg_speed((20 * m).force_in(km), (2 * s).force_in(h));
```
but the above will obviously provide an incorrect behavior (i.e. division by `0` in the evaluation

2
docs/users_guide/framework_basics/text_output.md
View File

@@ -74,7 +74,7 @@ associated with this quantity.
```cpp
std::cout << v1.in(km / h) << '\n'; // 110 km/h
std::cout << value_cast<m / s>(v1) << '\n'; // 30.5556 m/s
std::cout << v1.force_in(m / s) << '\n'; // 30.5556 m/s
```

8
docs/users_guide/framework_basics/value_conversions.md
View File

@@ -59,12 +59,18 @@ The second solution is to force a truncating conversion:
```cpp
auto q1 = 5 * m;
std::cout << value_cast<km>(q1) << '\n';
quantity<si::kilo<si::metre>, int> q2 = value_cast<km>(q1);
quantity<si::kilo<si::metre>, int> q2 = q1.force_in(km);
```
This explicit cast makes it clear that something unsafe is going on. It is easy to spot in code
reviews or while chasing a bug in the source code.
!!! note
`q.force_in(U)` is just a shortcut to run `value_cast<U>(q)`. There is no difference in behavior
between those two interfaces. `q.force_in(U)` was added for consistency with `q.in(U)` and
`q.force_numerical_value_in(U)`.
Another place where this cast is useful is when a user wants to convert a quantity with
a floating-point representation to the one using an integral one. Again this is a truncating
conversion, so an explicit cast is needed: