feedc0de/mp-units
1
0
Fork 0
forked from mpusz/mp-units
Code Pull Requests Activity

docs: Documentation now prefers refrences over UDLs

Browse Source
This commit is contained in:
Mateusz Pusz
2021-04-02 13:11:20 +02:00
parent 7cc34646b9
commit c4e9ff7f66
12 changed files with 211 additions and 175 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/framework/text_output.rst
+64 -63
View File
@@ -21,10 +21,10 @@ Output Streams
The easiest way to print a quantity is to provide its object to the output
stream::
using namespace units::isq::si::literals;
using namespace units::isq::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);
using namespace units::isq::si::references;
using namespace units::isq::si::international::references;
constexpr Speed auto v1 = avg_speed(220. * km, 2 * h);
constexpr Speed auto v2 = avg_speed(140. * mi, 2 * h);
std::cout << v1 << '\n'; // 110 km/h
std::cout << v2 << '\n'; // 70 mi/h
@@ -46,9 +46,9 @@ 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|
os << "|" << std::setw(10) << 123 * m << "|"; // | 123 m|
os << "|" << std::setw(10) << std::left << 123 * m << "|"; // |123 m |
os << "|" << std::setw(10) << std::setfill('*') << 123 * m << "|"; // |*****123 m|
fmt::format
@@ -100,9 +100,9 @@ In case it is left empty the default formatting of ``{:%Q %q}`` is applied. The
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);
std::cout << "Distance: " << 123 * km << "\n";
fmt::print("Distance: {}\n", 123 * km);
fmt::print("Distance: {:%Q %q}\n", 123 * km);
Quantity Value, Symbol, or Both?
@@ -111,9 +111,9 @@ 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
fmt::print("{:%Q}", 123 * km); // 123
fmt::print("{:%q}", 123 * km); // km
fmt::print("{:%Q%q}", 123 * km); // 123km
Controlling Width, Fill, and Alignment
@@ -123,14 +123,14 @@ To control width, fill, and alignment the C++ standard grammar tokens ``fill-and
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***|
fmt::print("|{:0}|", 123 * m); // |123 m|
fmt::print("|{:10}|", 123 * m); // | 123 m|
fmt::print("|{:<10}|", 123 * m); // |123 m |
fmt::print("|{:>10}|", 123 * m); // | 123 m|
fmt::print("|{:^10}|", 123 * m); // | 123 m |
fmt::print("|{:*<10}|", 123 * m); // |123 m*****|
fmt::print("|{:*>10}|", 123 * m); // |*****123 m|
fmt::print("|{:*^10}|", 123 * m); // |**123 m***|
ASCII-only Quantity Symbols
@@ -142,12 +142,13 @@ this by default. From the engineering point of view sometimes Unicode text migh
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
fmt::print("{}", 10 * R); // 10 Ω
fmt::print("{:%Q %Aq}", 10 * R); // 10 ohm
fmt::print("{}", 125 * us); // 125 µs
fmt::print("{:%Q %Aq}", 125 * us); // 125 us
inline constexpr auto s2 = s * s;
fmt::print("{}", 9.8 * (m / s2)); // 9.8 m/s²
fmt::print("{:%Q %Aq}", 9.8 * (m / s2)); // 9.8 m/s^2
Controlling on How the Quantity Value Is Being Printed
@@ -155,8 +156,8 @@ 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
fmt::print("{0:%Q %q},{0:%+Q %q},{0:%-Q %q},{0:% Q %q}", 1 * m); // 1 m,+1 m,1 m, 1 m
fmt::print("{0:%Q %q},{0:%+Q %q},{0:%-Q %q},{0:% Q %q}", -1 * m); // -1 m,-1 m,-1 m,-1 m
where:
@@ -168,47 +169,47 @@ where:
``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
fmt::print("{:%.0Q %q}", 1.2345 * m); // 1 m
fmt::print("{:%.1Q %q}", 1.2345 * m); // 1.2 m
fmt::print("{:%.2Q %q}", 1.2345 * 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
fmt::print("{:%bQ %q}", 42 * m); // 101010 m
fmt::print("{:%BQ %q}", 42 * m); // 101010 m
fmt::print("{:%dQ %q}", 42 * m); // 42 m
fmt::print("{:%oQ %q}", 42 * m); // 52 m
fmt::print("{:%xQ %q}", 42 * m); // 2a m
fmt::print("{:%XQ %q}", 42 * 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
fmt::print("{:%#bQ %q}", 42 * m); // 0b101010 m
fmt::print("{:%#BQ %q}", 42 * m); // 0B101010 m
fmt::print("{:%#oQ %q}", 42 * m); // 052 m
fmt::print("{:%#xQ %q}", 42 * m); // 0x2a m
fmt::print("{:%#XQ %q}", 42 * 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
fmt::print("{:%aQ %q}", 1.2345678 * m); // 0x9.e065152d8eae841p-3 m
fmt::print("{:%.3aQ %q}", 1.2345678 * m); // 0x9.e06p-3 m
fmt::print("{:%AQ %q}", 1.2345678 * m); // 0X9.E065152D8EAE841P-3 m
fmt::print("{:%.3AQ %q}", 1.2345678 * m); // 0X9.E06P-3 m
fmt::print("{:%eQ %q}", 1.2345678 * m); // 1.234568e+00 m
fmt::print("{:%.3eQ %q}", 1.2345678 * m); // 1.235e+00 m
fmt::print("{:%EQ %q}", 1.2345678 * m); // 1.234568E+00 m
fmt::print("{:%.3EQ %q}", 1.2345678 * m); // 1.235E+00 m
fmt::print("{:%gQ %q}", 1.2345678 * m); // 1.23457 m
fmt::print("{:%gQ %q}", 1.2345678e8 * m); // 1.23457e+08 m
fmt::print("{:%.3gQ %q}", 1.2345678 * m); // 1.23 m
fmt::print("{:%.3gQ %q}", 1.2345678e8 * m); // 1.23e+08 m
fmt::print("{:%GQ %q}", 1.2345678 * m); // 1.23457 m
fmt::print("{:%GQ %q}", 1.2345678e8 * m); // 1.23457E+08 m
fmt::print("{:%.3GQ %q}", 1.2345678 * m); // 1.23 m
fmt::print("{:%.3GQ %q}", 1.2345678e8 * m); // 1.23E+08 m
Special Signs
@@ -217,7 +218,7 @@ 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
fmt::print("{:%Q_%q}", 123 * km); // 123_km
fmt::print("{:%Q%t%q}", 123 * km); // 123\tkm <tab>
fmt::print("{:%Q%n%q}", 123 * km); // 123\nkm <new line>
fmt::print("{:%Q%% %q}", 123 * km); // 123% km