mpusz/mp-units
1
0
Fork 1
mirror of https://github.com/mpusz/mp-units.git synced 2025-07-29 18:07:16 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: example apllications documentation updated for modules

Browse Source
This commit is contained in:
Mateusz Pusz
2024-01-06 08:51:01 +01:00
parent edb7de4b11
commit aaa60e0573
3 changed files with 40 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/users_guide/examples/avg_speed.md
View File

@ -14,8 +14,8 @@ library features as possible, but we will scope on different interfaces one can
with the **mp-units**. We will also describe some advantages and disadvantages of presented
solutions.
First, we include all the necessary header files and import all the identifiers from the
`mp_units` namespace:
First, we either import a module or include all the necessary header files and import all
the identifiers from the `mp_units` namespace:
```cpp title="avg_speed.cpp" linenums="1"
--8<-- "example/avg_speed.cpp:28:42"
@ -52,11 +52,11 @@ Average speed of a car that makes 220 km in 2 h is 110 km/h.
```
Please note that in the first two cases, we must convert length from `km` to `m` and
time from `h` to `s`. The converted values are used to calculate speed in `m / s` which
is then again converted to the one in `km / h`. Those conversions not only impact the
application's runtime performance but may also affect the final result. Such truncation
can be easily observed in the first case where we deal with integral representation types
(the resulting speed is `108 km / h`).
time from `h` to `s`. The converted values are used to calculate speed in `m/s` which
is then again converted to the one in `km/h`. Those conversions not only impact the
application's runtime performance but may also affect the precision of the final result.
Such truncation can be easily observed in the first case where we deal with integral
representation types (the resulting speed is `108 km/h`).
The second scenario is really similar to the previous one, but this time, function arguments
have floating-point representation types:
@ -80,7 +80,7 @@ Average speed of a car that makes 220 km in 2 h is 110 km/h.
```
Next, let's do the same for integral and floating-point representations, but this time
using US Customary units:
using international mile:
```cpp title="avg_speed.cpp" linenums="65"
--8<-- "example/avg_speed.cpp:97:129"
@ -88,17 +88,17 @@ using US Customary units:
One important difference here is the fact that as it is not possible to make a lossless conversion
of miles to meters on a quantity using an integral representation type, so this time, we need a
`value_cast<si::metre>` to force it.
`value_cast<m, int>` to force it.
If we check the text output of the above, we will see the following:
```text
US Customary Units with 'int' as representation
International mile with 'int' as representation
Average speed of a car that makes 140 mi in 2 h is 111 km/h.
Average speed of a car that makes 140 mi in 2 h is 112.654 km/h.
Average speed of a car that makes 140 mi in 2 h is 112 km/h.
US Customary Units with 'double' as representation
International mile with 'double' as representation
Average speed of a car that makes 140 mi in 2 h is 111 km/h.
Average speed of a car that makes 140 mi in 2 h is 112.654 km/h.
Average speed of a car that makes 140 mi in 2 h is 112.654 km/h.
@ -108,7 +108,7 @@ Please note how the first and third results get truncated using integral represe
In the end, we repeat the scenario for CGS units:
```cpp title="avg_speed.cpp" linenums="98"
```cpp title="avg_speed.cpp" linenums="97"
--8<-- "example/avg_speed.cpp:131:161"
```
@ -129,6 +129,6 @@ Average speed of a car that makes 2.2e+07 cm in 7200 s is 110 km/h.
The example file ends with a simple `main()` function:
```cpp title="avg_speed.cpp" linenums="129"
```cpp title="avg_speed.cpp" linenums="128"
--8<-- "example/avg_speed.cpp:163:"
```

46
docs/users_guide/examples/hello_units.md
View File

@ -10,24 +10,24 @@ tags:
This is a really simple example showcasing the features of the **mp-units** library.
First, we include the headers for:
First, we either import the `mp_units` module or include the headers for:
- a system of quantities (ISQ)
- symbols of SI units
- symbols of international units
- text and stream output support
- an International System of Quantities (ISQ)
- an International System of units (SI)
- units derived from the International Yard and Pound
- text formatting and stream output support
```cpp title="hello_units.cpp" linenums="1"
--8<-- "example/hello_units.cpp:28:39"
```
Also, to shorten the definitions, we "import" `mp_units` namespace.
Also, to shorten the definitions, we "import" all the symbols from the `mp_units` namespace.
```cpp title="hello_units.cpp" linenums="12"
--8<-- "example/hello_units.cpp:40:41"
```
Next we define a simple function that calculates average speed based on the provided
Next, we define a simple function that calculates the average speed based on the provided
arguments of length and time:
```cpp title="hello_units.cpp" linenums="13"
@ -35,21 +35,21 @@ arguments of length and time:
```
The above function template takes any quantities implicitly convertible to `isq::length`
and `isq::time` respectively. Those quantities can use any compatible unit and a
representation type. The function returns a result of a really simple equation and ensures
and `isq::time`, respectively. Those quantities can use any compatible unit and a
representation type. The function returns a result of a straightforward equation and ensures
that its quantity type is implicitly convertible to `isq::speed`.
!!! tip
Besides verifying the type returned from the function, constraining a generic return
type is really useful for users of such a function as it provides more information
type is beneficial for users of such a function as it provides more information
of what to expect from a function than just using `auto`.
```cpp title="hello_units.cpp" linenums="17"
--8<-- "example/hello_units.cpp:47:50"
```
The above lines explicitly opt-in to use unit symbols from two systems of units.
The above lines explicitly opt into using unit symbols from two systems of units.
As this introduces a lot of short identifiers into the current scope, it is not done
implicitly while including a header file.
@ -57,21 +57,21 @@ implicitly while including a header file.
--8<-- "example/hello_units.cpp:52:58"
```
- Lines `16` & `17` create a quantity of kind `isq::length / isq::time` with the numbers
- Lines `21` & `22` create a quantity of kind `isq::length / isq::time` with the numbers
and units provided. Such quantities can be converted or assigned to any other quantity
with a matching kind.
- Line `18` calls our function template with quantities of kind `isq::length` and
- Line `23` calls our function template with quantities of kind `isq::length` and
`isq::time` and number and units provided.
- Line `19` explicitly provides quantity types of the quantities passed to a function template.
This time those will not be quantity kinds anymore and will have
- Line `24` explicitly provides quantity types of the quantities passed to a function template.
This time, those will not be quantity kinds anymore and will have
[more restrictive conversion rules](../framework_basics/simple_and_typed_quantities.md#quantity_cast-to-force-unsafe-conversions).
- Line `20` changes the unit of a quantity `v3` to `m / s` in a
- Line `25` changes the unit of a quantity `v3` to `m / s` in a
[value-preserving way](../framework_basics/value_conversions.md#value-preserving-conversions)
(floating-point representations are considered to be value-preserving).
- Line `21` does a similar operation but this time it would succeed also for
- Line `26` does a similar operation, but this time, it would also succeed for
[value-truncating cases](../framework_basics/value_conversions.md#value-truncating-conversions)
(if it was the case).
- Line `22` does a [value-truncating conversion](../framework_basics/value_conversions.md#value-truncating-conversions)
(if that was the case).
- Line `27` does a [value-truncating conversion](../framework_basics/value_conversions.md#value-truncating-conversions)
of changing the underlying representation type from `double` to `int`.
```cpp title="hello_units.cpp" linenums="28"
@ -79,10 +79,10 @@ implicitly while including a header file.
```
The above presents [various ways to print a quantity](../framework_basics/text_output.md).
Both stream insertion operations and `std::format` are supported.
Both stream insertion operations and `std::format` facilities are supported.
!!! tip
`MP_UNITS_STD_FMT` is used for compatibility reasons. In case a specific compiler
does not support `std::format` or a user prefers to use `{fmt}` library, this macro
will resolve to `fmt` namespace. Otherwise, `std` namespace will be used.
`MP_UNITS_STD_FMT` is used for compatibility reasons. If a specific compiler
does not support `std::format` or a user prefers to use the `{fmt}` library, this macro
will resolve to `fmt` namespace. Otherwise, the `std` namespace will be used.

8
example/avg_speed.cpp
View File

@ -94,14 +94,14 @@ void example()
print_result(distance, duration, avg_speed(distance, duration));
}
// Customary Units (int)
// International mile (int)
{
using namespace mp_units::international::unit_symbols;
constexpr auto distance = 140 * mi;
constexpr auto duration = 2 * h;
std::cout << "\nUS Customary Units with 'int' as representation\n";
std::cout << "\nInternational mile with 'int' as representation\n";
// it is not possible to make a lossless conversion of miles to meters on an integral type
// (explicit cast needed)
@ -110,14 +110,14 @@ void example()
print_result(distance, duration, avg_speed(distance, duration));
}
// Customary Units (double)
// International mile (double)
{
using namespace mp_units::international::unit_symbols;
constexpr auto distance = 140. * mi;
constexpr auto duration = 2. * h;
std::cout << "\nUS Customary Units with 'double' as representation\n";
std::cout << "\nInternational mile with 'double' as representation\n";
// conversion from a floating-point to an integral type is a truncating one so an explicit cast is needed
// also it is not possible to make a lossless conversion of miles to meters on an integral type