Skip to content

Commit

Permalink
docs: Text Output grammar cleanup
Browse files Browse the repository at this point in the history
  • Loading branch information
mpusz committed Dec 27, 2023
1 parent 265cabb commit f99a9cd
Showing 1 changed file with 21 additions and 19 deletions.
40 changes: 21 additions & 19 deletions docs/users_guide/framework_basics/text_output.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,22 +5,24 @@ any quantity in the most user-friendly way.

!!! note

The library does not provide a text output for quantity points, as printing just a number and a unit
is not enough to adequately describe a quantity point. Often an additional postfix is required.
The library does not provide a text output for quantity points, as printing just a number and
a unit is not enough to adequately describe a quantity point. Often, an additional postfix is
required.

For example, the text output of `42 m` may mean many things and can also be confused with an output
of a regular quantity. On the other hand, printing `42 m AMSL` for altitudes above mean sea level is
a much better solution, but the library does not have enough information to print it that way by itself.
For example, the text output of `42 m` may mean many things and can also be confused with an
output of a regular quantity. On the other hand, printing `42 m AMSL` for altitudes above mean
sea level is a much better solution, but the library does not have enough information to print
it that way by itself.


## Derived unit symbols generation

Based on the provided definitions for base units, the library creates symbols for derived ones.
The library creates symbols for derived ones based on the provided definitions for base units.

### `unit_symbol_formatting`

`unit_symbol_formatting` is a data type describing the configuration of the symbol generation
algorithm. It contains three orthogonal fields, and each of them has a default value.
algorithm. It contains three orthogonal fields, each with a default value.

```cpp
enum class text_encoding : std::int8_t {
Expand Down Expand Up @@ -119,8 +121,8 @@ inline constexpr bool space_before_unit_symbol<non_si::degree> = false;

!!! note

The above works only for [the default formatting](#default-formatting). In case we provide our own
format specification (e.g., `std::format("{:%Q %q}", q)`), the library will always obey this
The above works only for [the default formatting](#default-formatting). In case we provide our
own format specification (e.g., `std::format("{:%Q %q}", q)`), the library will always obey this
specification for all the units (no matter of what is the actual value of the
`space_before_unit_symbol` customization point) and the separating space will always be present
in this case.
Expand Down Expand Up @@ -164,7 +166,7 @@ associated with this quantity.
#### Output stream formatting
Only basic formatting can be applied for output streams. It includes control over width, fill,
Only basic formatting can be applied to output streams. It includes control over width, fill,
and alignment of the entire quantity and formatting of a quantity numerical value according
to the general C++ rules:
Expand Down Expand Up @@ -232,11 +234,11 @@ In the above grammar:
specification (e.g., ``, `µs`)
- `A` token forces non-standard **ASCII**-only output (e.g., `m^3`, `us`)
- `unit-symbol-solidus` tokens specify how the division of units should look like:
- `o` (default) outputs `/` only when there is only **one** unit in the denominator, otherwise negative
exponents are printed (e.g., `m/s`, `kg m⁻¹ s⁻¹`)
- `o` (default) outputs `/` only when there is only **one** unit in the denominator, otherwise
negative exponents are printed (e.g., `m/s`, `kg m⁻¹ s⁻¹`)
- `a` **always** uses solidus (e.g., `m/s`, `kg/(m s)`)
- `n` **never** prints solidus, which means that negative exponents are always used (e.g., `m s⁻¹`,
`kg m⁻¹ s⁻¹`)
- `n` **never** prints solidus, which means that negative exponents are always used
(e.g., `m s⁻¹`, `kg m⁻¹ s⁻¹`)
- `unit-symbol-separator` tokens specify how multiplied unit symbols should be separated:
- `s` (default) uses **space** as a separator (e.g., `kg m²/s²`)
- `d` uses half-high **dot** (``) as a separator (e.g., `kg⋅m²/s²`)
Expand All @@ -256,8 +258,8 @@ std::cout << std::format("Distance: {:%Q %q}\n", 123 * km);

!!! note

For some quantities the `{:%Q %q}` format may provide a different output than the default one.
It will happen for example for:
For some quantities, the `{:%Q %q}` format may provide a different output than the default one.
It will happen, for example for:

- units for which [`space_before_unit_symbol`](#customization-point) customization point is set
to `false`,
Expand Down Expand Up @@ -378,7 +380,7 @@ Unit symbols of some quantities are specified to use Unicode signs by the
library follows this by default. From the engineering point of view, sometimes Unicode text might
not be the best solution as terminals of many (especially embedded) devices are ASCII-only.
In such a case, the unit symbol can be forced to be printed using ASCII-only characters thanks to
`text-encoding` token:
the `text-encoding` token:
```cpp
std::println("{}", 10 * si::ohm); // 10 Ω
Expand Down Expand Up @@ -416,13 +418,13 @@ Also, there are a few options to separate the units being multiplied:
_NOTE 1_ In some fields, e.g., vector algebra, distinction is made between `a ∙ b` and `a × b`.
As of today, the **mp-units** library provides the support for `a b` and `a · b` only. Additionally,
As of today, the **mp-units** library only supports `a b` and `a · b`. Additionally,
we decided that the extraneous space in the latter case makes the result too verbose, so we decided
to just use the `·` symbol as a separator.
!!! note
Please let us know in case you require more formatting options here.
Please let us know if you require more formatting options here.
The `unit-symbol-separator` token allows us to obtain the following outputs:
Expand Down

0 comments on commit f99a9cd

Please sign in to comment.