mp-units/docs/framework/text_output.rst

.. namespace:: units

Text Output
===========

Beside providing dimensional analysis and units conversions, the library
also tries really hard to print any quantity in the most user friendly way.

.. note::

    The library provides no text output for quantity points.

Output Streams
--------------

The easiest way to print a quantity is to provide its object to the output
stream::

    using namespace units::physical::si::literals;
    using namespace units::physical::si::international::literals;
    constexpr Speed auto v1 = avg_speed(220._q_km, 2_q_h);
    constexpr Speed auto v2 = avg_speed(140._q_mi, 2_q_h);
    std::cout << v1 << '\n';  // 110 km/h
    std::cout << v2 << '\n';  // 70 mi/h

The text output will always print the :term:`value of a quantity` followed
by a space and then the symbol of a :term:`unit` associated with this quantity.

.. important::

    Remember that it is a good practice to always `quantity_cast()` a quantity
    of an unknown ``auto`` type before passing it to the text output::

        std::cout << quantity_cast<si::kilometre_per_hour>(v1) << '\n';  // 110 km/h
        std::cout << quantity_cast<si::metre_per_second>(v1) << '\n';    // 30.5556 m/s


Stream Output Formatting
^^^^^^^^^^^^^^^^^^^^^^^^

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

    os << "|" << std::setw(10) << 123_q_m << "|";                       // |     123 m|
    os << "|" << std::setw(10) << std::left << 123_q_m << "|";          // |123 m     |
    os << "|" << std::setw(10) << std::setfill('*') << 123_q_m << "|";  // |*****123 m|


fmt::format
-----------

The **mp-units** via ``fmt::format`` provides a fine-grained control over what
and how is being printed on the text output.


Grammar
^^^^^^^

.. productionlist::
    units-format-spec: [fill-and-align] [width] [units-specs]
    units-specs: conversion-spec
               : units-specs conversion-spec
               : units-specs literal-char
    literal-char: any character other than '{' or '}'
    conversion-spec: '%' units-type
    units-type: [units-rep-modifier] 'Q'
              : [units-unit-modifier] 'q'
              : one of "nt%"
    units-rep-modifier: [sign] [#] [precision] [L] [units-rep-type]
    units-rep-type: one of "aAbBdeEfFgGoxX"
    units-unit-modifier: 'A'

In the above grammar:

- ``fill-and-align``, ``width``, ``sign``, ``#``, and ``precision`` tokens and
  individual tokens of :token:`units-rep-type` are defined in the
  `format.string.std <https://wg21.link/format.string.std>`_ chapter of the C++
  standard specification,
- tokens ``Q``, ``q``, ``n``, ``t``, and ``%`` of :token:`units-type` are described
  in the `time.format <https://wg21.link/time.format>`_ chapter of the C++ standard
  specification,
- ``A`` token of :token:`units-unit-modifier` forces ASCII-only output (instead of the
  default Unicode symbols defined by the :term:`SI` specification).


Default formatting
^^^^^^^^^^^^^^^^^^

To format `quantity` values the formatting facility uses :token:`units-format-spec`.
In case it is left empty the default formatting of ``{:%Q %q}`` is applied. The same
default formatting is also applied to the output streams. This is why the following
code lines produce the same output::

    std::cout << "Distance: " << 123_q_km << "\n";
    fmt::print("Distance: {}\n", 123_q_km);
    fmt::print("Distance: {:%Q %q}\n", 123_q_km);


Quantity Value, Symbol, or Both?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The user can easily decide to either print a whole quantity (value and symbol) or
only its parts. Also a different quantity formatting might be applied::

    fmt::print("{:%Q}", 123_q_km);    // 123
    fmt::print("{:%q}", 123_q_km);    // km
    fmt::print("{:%Q%q}", 123_q_km);  // 123km


Controlling Width, Fill, and Alignment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To control width, fill, and alignment the C++ standard grammar tokens ``fill-and-align``
and ``width`` are being used and they treat a quantity value and symbol as a contiguous
text::

    fmt::print("|{:0}|", 123_q_m);     // |123 m|
    fmt::print("|{:10}|", 123_q_m);    // |     123 m|
    fmt::print("|{:<10}|", 123_q_m);   // |123 m     |
    fmt::print("|{:>10}|", 123_q_m);   // |     123 m|
    fmt::print("|{:^10}|", 123_q_m);   // |  123 m   |
    fmt::print("|{:*<10}|", 123_q_m);  // |123 m*****|
    fmt::print("|{:*>10}|", 123_q_m);  // |*****123 m|
    fmt::print("|{:*^10}|", 123_q_m);  // |**123 m***|


ASCII-only Quantity Symbols
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Unit symbols of some quantities are specified to use Unicode signs by the :term:`SI`
standard (i.e. ``Ω`` symbol for the resistance quantity). **mp-units** library follows
this by default. From the engineering point of view sometimes Unicode text  might
not be a 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::

    fmt::print("{}", 10_q_R);                 // 10 Ω
    fmt::print("{:%Q %Aq}", 10_q_R);          // 10 ohm
    fmt::print("{}", 125_q_us);               // 125 µs
    fmt::print("{:%Q %Aq}", 125_q_us);        // 125 us
    fmt::print("{}", 9.8_q_m_per_s2);         // 9.8 m/s²
    fmt::print("{:%Q %Aq}", 9.8_q_m_per_s2);  // 9.8 m/s^2


Controlling on How the Quantity Value Is Being Printed
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

    fmt::print("{0:%Q %q},{0:%+Q %q},{0:%-Q %q},{0:% Q %q}", 1_q_m);   // 1 m,+1 m,1 m, 1 m
    fmt::print("{0:%Q %q},{0:%+Q %q},{0:%-Q %q},{0:% Q %q}", -1_q_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::

    fmt::print("{:%.0Q %q}", 1.2345_q_m);  // 1 m
    fmt::print("{:%.1Q %q}", 1.2345_q_m);  // 1.2 m
    fmt::print("{:%.2Q %q}", 1.2345_q_m);  // 1.23 m


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

    fmt::print("{:%bQ %q}", 42_q_m);    // 101010 m
    fmt::print("{:%BQ %q}", 42_q_m);    // 101010 m
    fmt::print("{:%dQ %q}", 42_q_m);    // 42 m
    fmt::print("{:%oQ %q}", 42_q_m);    // 52 m
    fmt::print("{:%xQ %q}", 42_q_m);    // 2a m
    fmt::print("{:%XQ %q}", 42_q_m);    // 2A m

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

    fmt::print("{:%#bQ %q}", 42_q_m);   // 0b101010 m
    fmt::print("{:%#BQ %q}", 42_q_m);   // 0B101010 m
    fmt::print("{:%#oQ %q}", 42_q_m);   // 052 m
    fmt::print("{:%#xQ %q}", 42_q_m);   // 0x2a m
    fmt::print("{:%#XQ %q}", 42_q_m);   // 0X2A m

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

    fmt::print("{:%aQ %q}",   1.2345678_q_m);      // 0x9.e065152d8eae841p-3 m
    fmt::print("{:%.3aQ %q}", 1.2345678_q_m);      // 0x9.e06p-3 m
    fmt::print("{:%AQ %q}",   1.2345678_q_m);      // 0X9.E065152D8EAE841P-3 m
    fmt::print("{:%.3AQ %q}", 1.2345678_q_m);      // 0X9.E06P-3 m
    fmt::print("{:%eQ %q}",   1.2345678_q_m);      // 1.234568e+00 m
    fmt::print("{:%.3eQ %q}", 1.2345678_q_m);      // 1.235e+00 m
    fmt::print("{:%EQ %q}",   1.2345678_q_m);      // 1.234568E+00 m
    fmt::print("{:%.3EQ %q}", 1.2345678_q_m);      // 1.235E+00 m
    fmt::print("{:%gQ %q}",   1.2345678_q_m);      // 1.23457 m
    fmt::print("{:%gQ %q}",   1.2345678e8_q_m);    // 1.23457e+08 m
    fmt::print("{:%.3gQ %q}", 1.2345678_q_m);      // 1.23 m
    fmt::print("{:%.3gQ %q}", 1.2345678e8_q_m);    // 1.23e+08 m
    fmt::print("{:%GQ %q}",   1.2345678_q_m);      // 1.23457 m
    fmt::print("{:%GQ %q}",   1.2345678e8_q_m);    // 1.23457E+08 m
    fmt::print("{:%.3GQ %q}", 1.2345678_q_m);      // 1.23 m
    fmt::print("{:%.3GQ %q}", 1.2345678e8_q_m);    // 1.23E+08 m


Special Signs
^^^^^^^^^^^^^

Beside adding any list of regular characters as a separator between the value and the
symbol, it is possible to type a few special signs there too::

    fmt::print("{:%Q_%q}", 123_q_km);    // 123_km
    fmt::print("{:%Q%t%q}", 123_q_km);   // 123\tkm  <tab>
    fmt::print("{:%Q%n%q}", 123_q_km);   // 123\nkm  <new line>
    fmt::print("{:%Q%% %q}", 123_q_km);  // 123% km