Skip to content

Commit

Permalink
docs: q.force_in(U) documentation added
Browse files Browse the repository at this point in the history
  • Loading branch information
mpusz committed Sep 13, 2023
1 parent a6284aa commit bf954cf
Show file tree
Hide file tree
Showing 3 changed files with 11 additions and 5 deletions.
4 changes: 2 additions & 2 deletions docs/users_guide/framework_basics/generic_interfaces.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions docs/users_guide/framework_basics/text_output.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,8 +73,8 @@ associated with this quantity.
before passing it to the text output:
```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.in(km / h) << '\n'; // 110 km/h
std::cout << v1.force_in(m / s) << '\n'; // 30.5556 m/s
```
Expand Down
8 changes: 7 additions & 1 deletion docs/users_guide/framework_basics/value_conversions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down

0 comments on commit bf954cf

Please sign in to comment.