From bf954cfcaff69df920f184b657ad4e2120a74327 Mon Sep 17 00:00:00 2001 From: Mateusz Pusz Date: Wed, 13 Sep 2023 10:44:50 +0200 Subject: [PATCH] docs: `q.force_in(U)` documentation added --- docs/users_guide/framework_basics/generic_interfaces.md | 4 ++-- docs/users_guide/framework_basics/text_output.md | 4 ++-- docs/users_guide/framework_basics/value_conversions.md | 8 +++++++- 3 files changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/users_guide/framework_basics/generic_interfaces.md b/docs/users_guide/framework_basics/generic_interfaces.md index 3dfbdfc3..df4cc98f 100644 --- a/docs/users_guide/framework_basics/generic_interfaces.md +++ b/docs/users_guide/framework_basics/generic_interfaces.md @@ -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 s2 = avg_speed(value_cast(140 * mi), 2 * h); - quantity s3 = avg_speed(value_cast(20 * m), value_cast(2 * s)); + quantity 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 diff --git a/docs/users_guide/framework_basics/text_output.md b/docs/users_guide/framework_basics/text_output.md index d7899668..3f961b4a 100644 --- a/docs/users_guide/framework_basics/text_output.md +++ b/docs/users_guide/framework_basics/text_output.md @@ -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(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 ``` diff --git a/docs/users_guide/framework_basics/value_conversions.md b/docs/users_guide/framework_basics/value_conversions.md index 5dd8b111..978f7d29 100644 --- a/docs/users_guide/framework_basics/value_conversions.md +++ b/docs/users_guide/framework_basics/value_conversions.md @@ -59,12 +59,18 @@ The second solution is to force a truncating conversion: ```cpp auto q1 = 5 * m; std::cout << value_cast(q1) << '\n'; -quantity, int> q2 = value_cast(q1); +quantity, 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(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: