mpusz/mp-units
1
0
Fork 1
mirror of https://github.com/mpusz/mp-units.git synced 2025-08-06 21:54:28 +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` 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 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 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 ```cpp
quantity<isq::speed[mi / h]> s2 = avg_speed(value_cast<km>(140 * mi), 2 * h); 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 but the above will obviously provide an incorrect behavior (i.e. division by `0` in the evaluation

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

@@ -73,8 +73,8 @@ associated with this quantity.
before passing it to the text output: before passing it to the text output:
```cpp ```cpp
std::cout << v1.in(km / h) << '\n'; // 110 km/h 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 ```cpp
auto q1 = 5 * m; auto q1 = 5 * m;
std::cout << value_cast<km>(q1) << '\n'; 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 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. 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 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 a floating-point representation to the one using an integral one. Again this is a truncating
conversion, so an explicit cast is needed: conversion, so an explicit cast is needed: