diff --git a/docs/users_guide/examples/avg_speed.md b/docs/users_guide/examples/avg_speed.md index 397cafc1..313725df 100644 --- a/docs/users_guide/examples/avg_speed.md +++ b/docs/users_guide/examples/avg_speed.md @@ -7,7 +7,7 @@ tags: # `avg_speed` -!!! example "[Try it on Compiler Explorer](https://godbolt.org/z/TnqGa4sdn)" +!!! example "[Try it on Compiler Explorer](https://godbolt.org/z/v9c5T6bc4)" Let's continue the previous example. This time, our purpose will not be to showcase as many library features as possible, but we will scope on different interfaces one can provide @@ -18,28 +18,28 @@ First, we either import a module or include all the necessary header files and i the identifiers from the `mp_units` namespace: ```cpp title="avg_speed.cpp" linenums="1" ---8<-- "example/avg_speed.cpp:28:42" +--8<-- "example/avg_speed.cpp:28:46" ``` Next, we define two functions calculating average speed based on quantities of fixed units and integral and floating-point representation types, respectively, and a third function that we introduced in the [previous example](hello_units.md): -```cpp title="avg_speed.cpp" linenums="16" ---8<-- "example/avg_speed.cpp:44:58" +```cpp title="avg_speed.cpp" linenums="20" +--8<-- "example/avg_speed.cpp:48:62" ``` We also added a simple utility to print our results: -```cpp title="avg_speed.cpp" linenums="31" ---8<-- "example/avg_speed.cpp:60:66" +```cpp title="avg_speed.cpp" linenums="35" +--8<-- "example/avg_speed.cpp:64:70" ``` Now, let's analyze how those three utility functions behave with different sets of arguments. First, we are going to use quantities of SI units and integral representation: -```cpp title="avg_speed.cpp" linenums="38" ---8<-- "example/avg_speed.cpp:68:82" +```cpp title="avg_speed.cpp" linenums="42" +--8<-- "example/avg_speed.cpp:72:86" ``` The above provides the following output: @@ -61,8 +61,8 @@ 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: -```cpp title="avg_speed.cpp" linenums="53" ---8<-- "example/avg_speed.cpp:84:95" +```cpp title="avg_speed.cpp" linenums="57" +--8<-- "example/avg_speed.cpp:88:99" ``` Conversion from floating-point to integral representation types is @@ -82,8 +82,8 @@ 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 international mile: -```cpp title="avg_speed.cpp" linenums="65" ---8<-- "example/avg_speed.cpp:97:129" +```cpp title="avg_speed.cpp" linenums="69" +--8<-- "example/avg_speed.cpp:101:132" ``` One important difference here is the fact that as it is not possible to make a lossless conversion @@ -108,8 +108,8 @@ 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="97" ---8<-- "example/avg_speed.cpp:131:161" +```cpp title="avg_speed.cpp" linenums="101" +--8<-- "example/avg_speed.cpp:134:165" ``` Again, we observe `value_cast` being used in the same places and consistent truncation errors @@ -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="128" ---8<-- "example/avg_speed.cpp:163:" +```cpp title="avg_speed.cpp" linenums="133" +--8<-- "example/avg_speed.cpp:167:" ``` diff --git a/docs/users_guide/examples/hello_units.md b/docs/users_guide/examples/hello_units.md index dd69fcf4..a434e086 100644 --- a/docs/users_guide/examples/hello_units.md +++ b/docs/users_guide/examples/hello_units.md @@ -6,32 +6,32 @@ tags: # `hello_units` -!!! example "[Try it on Compiler Explorer](https://godbolt.org/z/bT4GGPbef)" +!!! example "[Try it on Compiler Explorer](https://godbolt.org/z/MYn5qjPzh)" This is a really simple example showcasing the features of the **mp-units** library. First, we either import the `mp_units` module or include the headers for: -- 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 +- 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:41" +--8<-- "example/hello_units.cpp:28:45" ``` Also, to shorten the definitions, we "import" all the symbols from the `mp_units` namespace. -```cpp title="hello_units.cpp" linenums="14" ---8<-- "example/hello_units.cpp:42:43" +```cpp title="hello_units.cpp" linenums="18" +--8<-- "example/hello_units.cpp:46:47" ``` 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="15" ---8<-- "example/hello_units.cpp:44:47" +```cpp title="hello_units.cpp" linenums="19" +--8<-- "example/hello_units.cpp:48:51" ``` The above function template takes any quantities implicitly convertible to `isq::length` @@ -45,37 +45,37 @@ that its quantity type is implicitly convertible to `isq::speed`. 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="19" ---8<-- "example/hello_units.cpp:49:52" +```cpp title="hello_units.cpp" linenums="23" +--8<-- "example/hello_units.cpp:53:56" ``` 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. -```cpp title="hello_units.cpp" linenums="23" ---8<-- "example/hello_units.cpp:54:60" +```cpp title="hello_units.cpp" linenums="27" +--8<-- "example/hello_units.cpp:58:64" ``` -- Lines `23` & `24` create a quantity of kind `isq::length / isq::time` with the numbers +- Lines `27` & `28` 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 `25` calls our function template with quantities of kind `isq::length` and +- Line `29` calls our function template with quantities of kind `isq::length` and `isq::time` and number and units provided. -- Line `26` explicitly provides quantity types of the quantities passed to a function template. +- Line `30` 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 `27` changes the unit of a quantity `v3` to `m / s` in a +- Line `31` 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 `28` does a similar operation, but this time, it would also succeed for +- Line `32` does a similar operation, but this time, it would also succeed for [value-truncating cases](../framework_basics/value_conversions.md#value-truncating-conversions) (if that was the case). -- Line `29` does a [value-truncating conversion](../framework_basics/value_conversions.md#value-truncating-conversions) +- Line `33` 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="30" ---8<-- "example/hello_units.cpp:62" +```cpp title="hello_units.cpp" linenums="34" +--8<-- "example/hello_units.cpp:66" ``` The above presents [various ways to print a quantity](../framework_basics/text_output.md). @@ -86,3 +86,6 @@ Both stream insertion operations and `std::format` facilities are supported. `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. + + More about it can be found in the [Wide Compatibility](../use_cases/wide_compatibility.md#mp_units_std_fmt) + chapter. diff --git a/docs/users_guide/examples/si_constants.md b/docs/users_guide/examples/si_constants.md index 05dbfbc2..f5feb153 100644 --- a/docs/users_guide/examples/si_constants.md +++ b/docs/users_guide/examples/si_constants.md @@ -6,7 +6,7 @@ tags: # `si_constants` -!!! example "[Try it on Compiler Explorer](https://godbolt.org/z/MevcK8vYT)" +!!! example "[Try it on Compiler Explorer](https://godbolt.org/z/eGqbW5d8K)" The next example presents all the seven defining constants of the SI system. We can observe how [Faster-than-lightspeed Constants](../framework_basics/faster_than_lightspeed_constants.md) @@ -22,15 +22,20 @@ the simplicity of this example, we to be able to express vector quantities with simple scalar types. ```cpp title="si_constants.cpp" linenums="14" ---8<-- "example/si_constants.cpp:42:" +--8<-- "example/si_constants.cpp:42:44" ``` -The main part of the example prints all of the SI-defining constants. While analyzing the output of -this program (provided below), we can easily notice that a direct printing of the quantity provides -just a value `1` with a proper constant symbol. This is the main power of the -[Faster-than-lightspeed Constants](../framework_basics/faster_than_lightspeed_constants.md) feature. -Only after we explicitly convert the unit of a quantity to proper SI units we get an actual numeric -value of the constant. +The main part of the example prints all of the SI-defining constants: + +```cpp title="si_constants.cpp" linenums="17" +--8<-- "example/si_constants.cpp:45:" +``` + +While analyzing the output of this program (provided below), we can easily notice that a direct +printing of the quantity provides just a value `1` with a proper constant symbol. This is the main +power of the [Faster-than-lightspeed Constants](../framework_basics/faster_than_lightspeed_constants.md) +feature. Only after we explicitly convert the unit of a quantity to proper SI units we get an +actual numeric value of the constant. ```text The seven defining constants of the SI and the seven corresponding units they define: