mp-units/docs/users_guide/framework_basics/text_output.md

# Text Output

Besides providing dimensional analysis and unit conversions, the library also tries hard to print
any quantity in the most user-friendly way. We can print the entire quantity or its
selected parts (numerical value, unit, or dimension).

!!! note

    The library does not provide a text output for quantity points. The quantity stored inside
    is just an implementation detail of this type. It is a vector from a specific origin.
    Without the knowledge of the origin, the vector by itself is useless as we can't determine
    which point it describes.

    In the current library design, point origin does not provide any text in its definition.
    Even if we could add such information to the point's definition, we would not
    know how to output it in the text. There may be many ways to do it. For example, should we
    prepend or append the origin part to the quantity text?

    For example, the text output of `42 m` for a quantity point may mean many things. It may be
    an offset from the mountain top, sea level, or maybe the center of Mars.
    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.

    Please let us know if you have a good idea of how to solve this issue.


## Predefined symbols

The definitions of dimensions, units, prefixes, and constants require assigning text symbols
for each entity. Those symbols will be composed by the library's framework to express dimensions
and units of derived quantities.

=== "Dimensions"

    ```cpp
    inline constexpr struct dim_length : base_dimension<"L"> {} dim_length;
    inline constexpr struct dim_mass : base_dimension<"M"> {} dim_mass;
    inline constexpr struct dim_time : base_dimension<"T"> {} dim_time;
    inline constexpr struct dim_electric_current : base_dimension<"I"> {} dim_electric_current;
    inline constexpr struct dim_thermodynamic_temperature : base_dimension<{u8"Θ", "O"}> {} dim_thermodynamic_temperature;
    inline constexpr struct dim_amount_of_substance : base_dimension<"N"> {} dim_amount_of_substance;
    inline constexpr struct dim_luminous_intensity : base_dimension<"J"> {} dim_luminous_intensity;
    ```

=== "Units"

    ```cpp
    inline constexpr struct second : named_unit<"s", kind_of<isq::time>> {} second;
    inline constexpr struct metre : named_unit<"m", kind_of<isq::length>> {} metre;
    inline constexpr struct gram : named_unit<"g", kind_of<isq::mass>> {} gram;
    inline constexpr struct kilogram : decltype(kilo<gram>) {} kilogram;

    inline constexpr struct newton : named_unit<"N", kilogram * metre / square(second)> {} newton;
    inline constexpr struct joule : named_unit<"J", newton * metre> {} joule;
    inline constexpr struct watt : named_unit<"W", joule / second> {} watt;
    inline constexpr struct coulomb : named_unit<"C", ampere * second> {} coulomb;
    inline constexpr struct volt : named_unit<"V", watt / ampere> {} volt;
    inline constexpr struct farad : named_unit<"F", coulomb / volt> {} farad;
    inline constexpr struct ohm : named_unit<{u8"Ω", "ohm"}, volt / ampere> {} ohm;
    ```

=== "Prefixes"

    ```cpp
    template<PrefixableUnit auto U> struct micro_ : prefixed_unit<{u8"µ", "u"}, mag_power<10, -6>, U> {};
    template<PrefixableUnit auto U> struct milli_ : prefixed_unit<"m", mag_power<10, -3>, U> {};
    template<PrefixableUnit auto U> struct centi_ : prefixed_unit<"c", mag_power<10, -2>, U> {};
    template<PrefixableUnit auto U> struct deci_  : prefixed_unit<"d", mag_power<10, -1>, U> {};
    template<PrefixableUnit auto U> struct deca_  : prefixed_unit<"da", mag_power<10, 1>, U> {};
    template<PrefixableUnit auto U> struct hecto_ : prefixed_unit<"h", mag_power<10, 2>, U> {};
    template<PrefixableUnit auto U> struct kilo_  : prefixed_unit<"k", mag_power<10, 3>, U> {};
    template<PrefixableUnit auto U> struct mega_  : prefixed_unit<"M", mag_power<10, 6>, U> {};
    ```

=== "Constants"

    ```cpp
    inline constexpr struct hyperfine_structure_transition_frequency_of_cs : named_unit<{u8"Δν_Cs", "dv_Cs"}, mag<9'192'631'770> * hertz> {} hyperfine_structure_transition_frequency_of_cs;
    inline constexpr struct speed_of_light_in_vacuum : named_unit<"c", mag<299'792'458> * metre / second> {} speed_of_light_in_vacuum;
    inline constexpr struct planck_constant : named_unit<"h", mag<ratio{662'607'015, 100'000'000}> * mag_power<10, -34> * joule * second> {} planck_constant;
    inline constexpr struct elementary_charge : named_unit<"e", mag<ratio{1'602'176'634, 1'000'000'000}> * mag_power<10, -19> * coulomb> {} elementary_charge;
    inline constexpr struct boltzmann_constant : named_unit<"k", mag<ratio{1'380'649, 1'000'000}> * mag_power<10, -23> * joule / kelvin> {} boltzmann_constant;
    inline constexpr struct avogadro_constant : named_unit<"N_A", mag<ratio{602'214'076, 100'000'000}> * mag_power<10, 23> / mole> {} avogadro_constant;
    inline constexpr struct luminous_efficacy : named_unit<"K_cd", mag<683> * lumen / watt> {} luminous_efficacy;
    ```

!!! important

    Two symbols always have to be provided if the primary symbol contains characters outside of
    the [basic literal character set](https://en.cppreference.com/w/cpp/language/charset).
    The first must be provided as a UTF-8 literal and may contain any Unicode characters.
    The second one must provide an alternative spelling and only use characters from within of
    [basic literal character set](https://en.cppreference.com/w/cpp/language/charset).

!!! note

    Unicode provides only a minimal set of characters available as subscripts, which are often used
    to differentiate various constants and quantities of the same kind. To workaround this issue,
    **mp-units** uses the '_' character to specify that the following characters should be considered
    a subscript of the symbol.

!!! tip

    For older compilers, it might be required to specify a `symbol_text` class explicitly
    template name to initialize it with two symbols:

    ```cpp
    inline constexpr struct ohm : named_unit<symbol_text{u8"Ω", "ohm"}, volt / ampere> {} ohm;
    ```


## Symbols for derived entities

### `text_encoding`

[ISQ](../../appendix/glossary.md#isq) and [SI](../../appendix/glossary.md#si) standards always
specify symbols using Unicode encoding. This is why it is a default and primary target for
text output. However, in some applications or environments, a standard ASCII-like text output
using only the characters from the [basic literal character set](https://en.cppreference.com/w/cpp/language/charset)
can be preferred by users.

This is why the library provides an option to change the default encoding to the ASCII one with:

```cpp
enum class text_encoding : std::int8_t {
  unicode,  // µs; m³;  L²MT⁻³
  ascii,    // us; m^3; L^2MT^-3
  default_encoding = unicode
};
```

### Symbols of derived dimensions

#### `dimension_symbol_formatting`

`dimension_symbol_formatting` is a data type describing the configuration of the symbol generation
algorithm.

```cpp
struct dimension_symbol_formatting {
  text_encoding encoding = text_encoding::default_encoding;
};
```

#### `dimension_symbol()`

Returns a `std::string_view` with the symbol of a dimension for the provided configuration:

```cpp
template<dimension_symbol_formatting fmt = dimension_symbol_formatting{}, typename CharT = char, Dimension D>
[[nodiscard]] consteval std::string_view dimension_symbol(D);
```

For example:

```cpp
static_assert(dimension_symbol<{.encoding = text_encoding::ascii}>(isq::power.dimension) == "L^2MT^-3");
```

!!! note

    `std::string_view` is returned only when C++23 is available. Otherwise, an instance of a
    `basic_fixed_string` is being returned.

#### `dimension_symbol_to()`

Inserts the generated dimension symbol into the output text iterator at runtime.

```cpp
template<typename CharT = char, std::output_iterator<CharT> Out, Dimension D>
constexpr Out dimension_symbol_to(Out out, D d, dimension_symbol_formatting fmt = dimension_symbol_formatting{});
```

For example:

```cpp
std::string txt;
dimension_symbol_to(std::back_inserter(txt), isq::power.dimension, {.encoding = text_encoding::ascii});
std::cout << txt << "\n";
```

The above prints:

```text
L^2MT^-3
```


### Symbols of derived units

#### `unit_symbol_formatting`

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

```cpp
enum class unit_symbol_solidus : std::int8_t {
  one_denominator,  // m/s;   kg m⁻¹ s⁻¹
  always,           // m/s;   kg/(m s)
  never,            // m s⁻¹; kg m⁻¹ s⁻¹
  default_denominator = one_denominator
};

enum class unit_symbol_separator : std::int8_t {
  space,          // kg m²/s²
  half_high_dot,  // kg⋅m²/s²  (valid only for unicode encoding)
  default_separator = space
};

struct unit_symbol_formatting {
  text_encoding encoding = text_encoding::default_encoding;
  unit_symbol_solidus solidus = unit_symbol_solidus::default_denominator;
  unit_symbol_separator separator = unit_symbol_separator::default_separator;
};
```

`unit_symbol_solidus` impacts how the division of unit symbols is being presented in the text
output. By default, the '/' will be printed if only one unit component is in the
denominator. Otherwise, the exponent syntax will be used.

`unit_symbol_separator` specifies how multiple multiplied units should be separated from each
other. By default, the space (' ') will be used as a separator.

#### `unit_symbol()`

Returns a `std::string_view` with the symbol of a unit for the provided configuration:

```cpp
template<unit_symbol_formatting fmt = unit_symbol_formatting{}, typename CharT = char, Unit U>
[[nodiscard]] consteval std::string_view unit_symbol(U);
```

For example:

```cpp
static_assert(unit_symbol<{.solidus = unit_symbol_solidus::never,
                           .separator = unit_symbol_separator::half_high_dot}>(kg * m / s2) == "kg⋅m⋅s⁻²");
```

!!! note

    `std::string_view` is returned only when C++23 is available. Otherwise, an instance of a
    `basic_fixed_string` is being returned. See more in the
    [C++ compiler support](../../getting_started/installation_and_usage.md#static-constexpr-variables-in-constexpr-functions)
    chapter.

#### `unit_symbol_to()`

Inserts the generated unit symbol into the output text iterator at runtime.

```cpp
template<typename CharT = char, std::output_iterator<CharT> Out, Unit U>
constexpr Out unit_symbol_to(Out out, U u, unit_symbol_formatting fmt = unit_symbol_formatting{});
```

For example:

```cpp
std::string txt;
unit_symbol_to(std::back_inserter(txt), kg * m / s2,
               {.solidus = unit_symbol_solidus::never, .separator = unit_symbol_separator::half_high_dot});
std::cout << txt << "\n";
```

The above prints:

```text
kg⋅m⋅s⁻²
```

## `space_before_unit_symbol` customization point

The [SI Brochure](../../appendix/references.md#SIBrochure) says:

!!! quote "SI Brochure"

    The numerical value always precedes the unit and a space is always used to separate the unit from
    the number. ... The only exceptions to this rule are for the unit symbols for degree, minute and
    second for plane angle, `°`, `′` and `″`, respectively, for which no space is left between the
    numerical value and the unit symbol.

There are more units with such properties. For example, percent (`%`) and per mille(`‰`).

To support the above and other similar cases, the library exposes `space_before_unit_symbol`
customization point. By default, its value is `true` for all the units, so the space between a number
and a unit will be inserted in the output text. To change this behavior, we have to provide a partial
specialization for a specific unit:

```cpp
template<>
inline constexpr bool space_before_unit_symbol<non_si::degree> = false;
```

!!! note

    The above works only for [the default formatting](#default-formatting) or for the format
    strings that use `%?` placement field (`std::format("{}", q)` is equivalent to
    `std::format("{:%N%?%U}", q)`).

    In case a user provides custom format specification (e.g., `std::format("{:%N %U}", q)`),
    the library will always obey this specification for all the units (no matter what the actual
    value of the `space_before_unit_symbol` customization point is) and the separating space will always
    be used in this case.


## Output streams

!!! tip

    The output streaming support is opt-in and can be enabled by including the `<mp-units/ostream.h>`
    header file.

The easiest way to print a dimension, unit, or quantity is to provide its object to the output stream:

```cpp
const QuantityOf<isq::speed> auto v1 = avg_speed(220. * km, 2 * h);
const QuantityOf<isq::speed> auto v2 = avg_speed(140. * mi, 2 * h);
std::cout << v1 << '\n';            // 110 km/h
std::cout << v2 << '\n';            // 70 mi/h
std::cout << v2.unit << '\n';       // mi/h
std::cout << v2.dimension << '\n';  // LT⁻¹
```

The text output will always print the value using the default formatting for this entity.

!!! important "Important: Don't assume a unit"

    Remember that when we deal with a quantity of an "unknown" (e.g., `auto`) type, it is a good
    practice to always [convert the unit to the expected one](value_conversions.md#value-conversions)
    before passing it to the text output:

    ```cpp
    std::cout << v1.in(km / h) << '\n';       // 110 km/h
    std::cout << v1.force_in(m / s) << '\n';  // 30.5556 m/s
    ```


### Output stream formatting

Only basic formatting can be applied to output streams. It includes control over width, fill,
and alignment.

The numerical value of the quantity will be printed according to the current stream state and standard
manipulators may be used to customize that (assuming that the underlying representation type
respects them).

```cpp
std::cout << "|" << std::setw(10) << 123 * m << "|\n";                       // |     123 m|
std::cout << "|" << std::setw(10) << std::left << 123 * m << "|\n";          // |123 m     |
std::cout << "|" << std::setw(10) << std::setfill('*') << 123 * m << "|\n";  // |123 m*****|
```

!!! note

    To have more control over the formatting of the quantity that is printed with the output
    stream just use `std::cout << std::format(...)`.


## Text formatting

The library provides custom formatters for `std::format` facility, which allows fine-grained control
over what and how it is being printed in the text output.

!!! tip

    The text formatting facility support is opt-in and can be enabled by including the
    `<mp-units/format.h>` header file.

### Controlling width, fill, and alignment

Formatting grammar for all the entities provides control over width, fill, and alignment. The C++
standard grammar tokens `fill-and-align` and `width` are being used. They treat the entity as
a contiguous text to be aligned. For example, here are a few examples of the quantity numerical
value and symbol formatting:

```cpp
std::println("|{:0}|", 123 * m);     // |123 m|
std::println("|{:10}|", 123 * m);    // |     123 m|
std::println("|{:<10}|", 123 * m);   // |123 m     |
std::println("|{:>10}|", 123 * m);   // |     123 m|
std::println("|{:^10}|", 123 * m);   // |  123 m   |
std::println("|{:*<10}|", 123 * m);  // |123 m*****|
std::println("|{:*>10}|", 123 * m);  // |*****123 m|
std::println("|{:*^10}|", 123 * m);  // |**123 m***|
```

It is important to note that in the second line above, the quantity text is aligned to
the right by default, which is consistent with the formatting of numeric types. Units and dimensions behave
as text and, thus, are aligned to the left by default.

!!! note

    [`std::println` is a C++23 facility](https://en.cppreference.com/w/cpp/io/print). In case we
    do not have access to C++23, we can obtain the same output with:

    ```cpp
    std::cout << std::format("<format-string>\n", <format-args>);
    ```

### Dimension formatting

```bnf
dimension-format-spec ::= [fill-and-align] [width] [dimension-spec]
dimension-spec        ::= [text-encoding]
text-encoding         ::= 'U' | 'A'
```

In the above grammar:

- `fill-and-align` and `width` tokens are defined in the [format.string.std](https://wg21.link/format.string.std)
  chapter of the C++ standard specification,
- `text-encoding` token specifies the symbol text encoding:
    - `U` (default) uses the **Unicode** symbols defined by [@ISO80000] (e.g., `LT⁻²`),
    - `A` forces non-standard **ASCII**-only output (e.g., `LT^-2`).

Dimension symbols of some quantities are specified to use Unicode signs by the
[ISQ](../../appendix/glossary.md#isq) (e.g., `Θ` symbol for the _thermodynamic temperature_
dimension). 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
can output only letters from the basic literal character set. In such a case, the dimension
symbol can be forced to be printed using such characters thanks to `text-encoding` token:

```cpp
std::println("{}", isq::dim_thermodynamic_temperature);   // Θ
std::println("{:A}", isq::dim_thermodynamic_temperature); // O
std::println("{}", isq::power.dimension);                 // L²MT⁻³
std::println("{:A}", isq::power.dimension);               // L^2MT^-3
```

### Unit formatting

```bnf
unit-format-spec      ::= [fill-and-align] [width] [unit-spec]
unit-spec             ::= [text-encoding] [unit-symbol-solidus] [unit-symbol-separator] [L]
                          [text-encoding] [unit-symbol-separator] [unit-symbol-solidus] [L]
                          [unit-symbol-solidus] [text-encoding] [unit-symbol-separator] [L]
                          [unit-symbol-solidus] [unit-symbol-separator] [text-encoding] [L]
                          [unit-symbol-separator] [text-encoding] [unit-symbol-solidus] [L]
                          [unit-symbol-separator] [unit-symbol-solidus] [text-encoding] [L]
unit-symbol-solidus   ::= '1' | 'a' | 'n'
unit-symbol-separator ::= 's' | 'd'
```

In the above grammar:

- `fill-and-align` and `width` tokens are defined in the [format.string.std](https://wg21.link/format.string.std)
  chapter of the C++ standard specification,
- `unit-symbol-solidus` token specifies how the division of units should look like:
    - '1' (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⁻¹`)
- `unit-symbol-separator` token specifies 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²`) (requires the Unicode encoding)
- 'L' is reserved for possible future localization use in case the C++ standard library gets access to
  the ICU-like database.

!!! note

    The above grammar intended that the elements of `unit-spec` can appear in
    any order as they have unique characters. Users shouldn't have to remember the order of those tokens
    to control the formatting of a unit symbol.

Unit symbols of some quantities are specified to use Unicode signs by the [SI](../../appendix/glossary.md#si)
(e.g., `Ω` symbol for the _resistance_ quantity). The library follows this by default. From the
engineering point of view, Unicode text might not be the best solution sometimes, as terminals
of many (especially embedded) devices can output only letters from the basic literal character set.
In such a case, the unit symbol can be forced to be printed using such characters thanks to
`text-encoding` token:

```cpp
std::println("{}", si::ohm);      // Ω
std::println("{:A}", si::ohm);    // ohm
std::println("{}", us);           // µs
std::println("{:A}", us);         // us
std::println("{}", m / s2);       // m/s²
std::println("{:A}", m / s2);     // m/s^2
```

Additionally, both ISO 80000 and [SI](../../appendix/glossary.md#si) leave some freedom on how to
print unit symbols. This is why two additional tokens were introduced.

`unit-symbol-solidus` specifies how the division of units should look like. By default,
`/` will be used only when the denominator contains only one unit. However, with the 'a' or 'n'
options, we can force the facility to print the `/` character always (even when there are more units
in the denominator), or never, in which case a parenthesis will be added to enclose all denominator
units.

```cpp
std::println("{}", m / s);          // m/s
std::println("{}", kg / m / s2);    // kg m⁻¹ s⁻²
std::println("{:a}", m / s);        // m/s
std::println("{:a}", kg / m / s2);  // kg/(m s²)
std::println("{:n}", m / s);        // m s⁻¹
std::println("{:n}", kg / m / s2);  // kg m⁻¹ s⁻²
```

Also, there are a few options to separate the units being multiplied. ISO 80000 (part 1) says:

!!! quote "ISO 80000-1"

    When symbols for quantities are combined in a product of two or more quantities, this combination
    is indicated in one of the following ways: `ab`, `a b`, `a · b`, `a × b`

    _NOTE 1_ In some fields, e.g., vector algebra, distinction is made between `a ∙ b` and `a × b`.

The library supports `a b` and `a · b` only. Additionally, we decided that the extraneous space
in the latter case makes the result too verbose, so we decided just to use the `·` symbol as
a separator.

!!! note

    Please let us know if you require more formatting options here.

The `unit-symbol-separator` token allows us to obtain the following outputs:

```cpp
std::println("{}", kg * m2 / s2);    // kg m²/s²
std::println("{:d}", kg * m2 / s2);  // kg⋅m²/s²
```

!!! note

    'd' requires the Unicode encoding to be set.


### Quantity formatting

```bnf
quantity-format-spec        ::= [fill-and-align] [width] [quantity-specs]
quantity-specs              ::= conversion-spec
                                quantity-specs conversion-spec
                                quantity-specs literal-char
literal-char                ::= <any character other than '{', '}', or '%'>
conversion-spec             ::= placement-spec
                                subentity-replacement-field
placement-spec              ::= '%' placement-type
placement-type              ::= 'N' | 'U' | 'D' | '?' | '%'
subentity-replacement-field ::= '{' '%' subentity-id [format-specifier] '}'
subentity-id                ::= literal-char
                                subentity-id literal-char
format-specifier            ::= ':' format-spec
format-spec                 ::= <as specified by the formatter for the argument type; cannot start with '}'>
```

In the above grammar:

- `fill-and-align` and `width` tokens are defined in the [format.string.std](https://wg21.link/format.string.std)
  chapter of the C++ standard specification,
- `placement-type` token specifies which entity should be put and where:
    - 'N' inserts a default-formatted numerical value of the quantity,
    - 'U' inserts a default-formatted unit of the quantity,
    - 'D' inserts a default-formatted dimension of the quantity,
    - '?' inserts an optional separator between the number and a unit based on the value of
      `space_before_unit_symbol` for this unit,
    - '%' just inserts '%' character.
- `subentity-replacement-field` token allows the composition of formatters. The following identifiers
  are recognized by the quantity formatter:
    - 'N' passes `format-spec` to the `formatter` specialization for the quantity representation
      type,
    - 'U' passes `format-spec` to the `formatter` specialization for the unit type,
    - 'D' passes `format-spec` to the `formatter` specialization for the dimension type.

#### Default formatting

To format `quantity` values, the formatting facility uses `quantity-format-spec`. If left empty,
the default formatting is applied. The same default formatting is also applied to the output streams.
This is why the following code lines produce the same output:

```cpp
std::cout << "Distance: " << 123 * km << "\n";
std::cout << std::format("Distance: {}\n", 123 * km);
std::cout << std::format("Distance: {:%N%?%U}\n", 123 * km);
std::cout << std::format("Distance: {:{%N}%?{%U}}\n", 123 * km);
```

!!! note

    For some quantities, the `{:%N %U}` format may provide a different output than the default one,
    as some units have `space_before_unit_symbol` customization point explicitly set to `false`
    (e.g., `%` and `°`).


#### Quantity numerical value, unit symbol, or both?

Thanks to the grammar provided above, the user can easily decide to either:

- print a whole quantity:

    ```cpp
    std::println("Speed: {}", 120 * km / h);
    ```

    ```text
    Speed: 120 km/h
    ```

- provide custom quantity formatting:

    ```cpp
    std::println("Speed: {:%N in %U}", 120 * km / h);
    ```

    ```text
    Speed: 120 in km/h
    ```

- provide custom formatting for components:

    ```cpp
    std::println("Speed: {:{%N:.2f} {%U:n}}", 100. * km / (3 * h));
    ```

    ```text
    Speed: 33.33 km h⁻¹
    ```

- print only specific components (numerical value, unit, or dimension):

    ```cpp
    std::println("Speed:\n- number: {0:%N}\n- unit: {0:%U}\n- dimension: {0:%D}", 120 * km / h);
    ```

    ```text
    Speed:
    - number: 120
    - unit: km/h
    - dimension: LT⁻¹
    ```

!!! note

    The above grammar allows repeating the same field many times, possibly with a different
    format spec. For example:

    ```cpp
    std::println("Speed: {:%N {%N:.4f} {%N:.2f} {%U:n}}", 100. * km / (3 * h));
    ```

    ```text
    Speed: 33.333333333333336 33.3333 33.33 km h⁻¹
    ```


#### Formatting of the quantity numerical value

The representation type used as a numerical value of a quantity must provide its own formatter
specialization. It will be called by the quantity formatter with the format-spec provided
by the user in the `%N` replacement field.

In case we use C++ fundamental arithmetic types with our quantities the standard formatter
specified in [format.string.std](https://wg21.link/format.string.std) will be used. The rest
of this chapter assumes that it is the case and provides some usage examples.

`sign` token allows us to specify how the value's sign is being printed:

```cpp
std::println("{0:%N %U},{0:{%N:+} %U},{0:{%N:-} %U},{0:{%N: } %U}", 1 * m);   // 1 m,+1 m,1 m, 1 m
std::println("{0:%N %U},{0:{%N:+} %U},{0:{%N:-} %U},{0:{%N: } %U}", -1 * m);  // -1 m,-1 m,-1 m,-1 m
```

where:

- `+` indicates that a sign should be used for both non-negative and negative numbers,
- `-` indicates that a sign should be used for negative numbers and negative zero only
  (this is the default behavior),
- `<space>` indicates that a leading space should be used for non-negative numbers other
  than negative zero, and a minus sign for negative numbers and negative zero.

`precision` token is allowed only for floating-point representation types:

```cpp
std::println("{:{%N:.0} %U}", 1.2345 * m);   // 1 m
std::println("{:{%N:.1} %U}", 1.2345 * m);   // 1 m
std::println("{:{%N:.2} %U}", 1.2345 * m);   // 1.2 m
std::println("{:{%N:.3} %U}", 1.2345 * m);   // 1.23 m
std::println("{:{%N:.0f} %U}", 1.2345 * m);  // 1 m
std::println("{:{%N:.1f} %U}", 1.2345 * m);  // 1.2 m
std::println("{:{%N:.2f} %U}", 1.2345 * m);  // 1.23 m
```

`type` specifies how a value of the representation type is being printed.
For integral types:

```cpp
std::println("{:{%N:b} %U}", 42 * m);    // 101010 m
std::println("{:{%N:B} %U}", 42 * m);    // 101010 m
std::println("{:{%N:d} %U}", 42 * m);    // 42 m
std::println("{:{%N:o} %U}", 42 * m);    // 52 m
std::println("{:{%N:x} %U}", 42 * m);    // 2a m
std::println("{:{%N:X} %U}", 42 * m);    // 2A m
```

The above can be printed in an alternate version thanks to the `#` token:

```cpp
std::println("{:{%N:#b} %U}", 42 * m);   // 0b101010 m
std::println("{:{%N:#B} %U}", 42 * m);   // 0B101010 m
std::println("{:{%N:#o} %U}", 42 * m);   // 052 m
std::println("{:{%N:#x} %U}", 42 * m);   // 0x2a m
std::println("{:{%N:#X} %U}", 42 * m);   // 0X2A m
```

For floating-point values, the `type` token works as follows:

```cpp
std::println("{:{%N:a} %U}",   1.2345678 * m);      // 1.3c0ca2a5b1d5dp+0 m
std::println("{:{%N:.3a} %U}", 1.2345678 * m);      // 1.3c1p+0 m
std::println("{:{%N:A} %U}",   1.2345678 * m);      // 1.3C0CA2A5B1D5DP+0 m
std::println("{:{%N:.3A} %U}", 1.2345678 * m);      // 1.3C1P+0 m
std::println("{:{%N:e} %U}",   1.2345678 * m);      // 1.234568e+00 m
std::println("{:{%N:.3e} %U}", 1.2345678 * m);      // 1.235e+00 m
std::println("{:{%N:E} %U}",   1.2345678 * m);      // 1.234568E+00 m
std::println("{:{%N:.3E} %U}", 1.2345678 * m);      // 1.235E+00 m
std::println("{:{%N:g} %U}",   1.2345678 * m);      // 1.23457 m
std::println("{:{%N:g} %U}",   1.2345678e8 * m);    // 1.23457e+08 m
std::println("{:{%N:.3g} %U}", 1.2345678 * m);      // 1.23 m
std::println("{:{%N:.3g} %U}", 1.2345678e8 * m);    // 1.23e+08 m
std::println("{:{%N:G} %U}",   1.2345678 * m);      // 1.23457 m
std::println("{:{%N:G} %U}",   1.2345678e8 * m);    // 1.23457E+08 m
std::println("{:{%N:.3G} %U}", 1.2345678 * m);      // 1.23 m
std::println("{:{%N:.3G} %U}", 1.2345678e8 * m);    // 1.23E+08 m
```