Skip to content

Commit

Permalink
docs: "Symbols of scaled units" chapter added + minor updates to scal…
Browse files Browse the repository at this point in the history
…ed and common units chapters
  • Loading branch information
mpusz committed Oct 5, 2024
1 parent 569f27a commit 21d07a4
Show file tree
Hide file tree
Showing 2 changed files with 35 additions and 6 deletions.
3 changes: 2 additions & 1 deletion docs/users_guide/framework_basics/systems_of_units.md
Original file line number Diff line number Diff line change
Expand Up @@ -278,7 +278,8 @@ the library returns a special type that denotes that we are dealing with a commo
an equation:

```cpp
quantity q = 1 * km + 1 * mi; // quantity<common_unit<international::mile, si::kilo_<si::metre>>{}, int>
quantity q1 = 1 * km + 1 * mi; // quantity<common_unit<international::mile, si::kilo_<si::metre>>{}, int>
quantity q2 = 1. * rad + 1. * deg; // quantity<common_unit<si::degree, si::radian>, double>{}>
```

!!! note
Expand Down
38 changes: 33 additions & 5 deletions docs/users_guide/framework_basics/text_output.md
Original file line number Diff line number Diff line change
Expand Up @@ -268,25 +268,53 @@ The above prints:
kg⋅m⋅s⁻²
```


## Symbols of scaled units

In most cases [scaled units are hidden behind named units](systems_of_units.md#scaled-units).
However, there are a few real-life where a user directly faces a scaled unit. For example:

```cpp
constexpr Unit auto l_per_100km = l / (mag<100> * km);
```

The above is a derived unit of litre divided by a scaled unit of 100 kilometers. As we can
see a scaled unit has a magnitude and a reference unit. To denote the scope of such
a unit, we enclose it in `[...]`. For example, the following:

```cpp
std::cout << 6.7 * l_per_100km << "\n";
```

prints:

```text
6.7 l/[100 km]
```


## Symbols of common units

Some [common units](systems_of_units.md#common-units) expressed with a specialization of the
`common_unit` class template need special printing rules for their symbols. As they represent
a minimum set of equivalent common units resulting from the addition or subtraction of multiple
quantities, we print all of them as a scaled version of the source unit. For example the following:
quantities, we print all of them as a scaled version of the source unit. For example,
the following:

```cpp
std::cout << 1 * km + 1 * mi << "\n";
std::cout << 1 * nmi + 1 * mi << "\n";
std::cout << 1 * km / h + 1 * m / s << "\n";
std::cout << 1 * rad + 1 * deg << "\n";
```

will print:
prints:

```text
40771 EQUIV{[1/25146] mi, [1/15625] km}
108167 EQUIV{[1/50292] mi, [1/57875] nmi}
23 EQUIV{[1/5] km/h, [1/18] m/s}
40771 EQUIV{[1/25146 mi], [1/15625 km]}
108167 EQUIV{[1/50292 mi], [1/57875 nmi]}
23 EQUIV{[1/5 km/h], [1/18 m/s]}
183.142 EQUIV{[1/𝜋°], [1/180 rad]}
```

Thanks to the above, it might be easier for the user to reason about the magnitude of the resulting
Expand Down

0 comments on commit 21d07a4

Please sign in to comment.