refactor: example applications refactored to a new formatting syntax

README.md

@@ -58,15 +58,15 @@ analysis and unit/quantity manipulation.
 Here is a small example of possible operations:
 
 ```cpp
-#include <mp-units/systems/si/si.h>
+import mp_units;
 
 using namespace mp_units;
 using namespace mp_units::si::unit_symbols;
 
 // simple numeric operations
 static_assert(10 * km / 2 == 5 * km);
 
-// unit conversions
+// conversions to common units
 static_assert(1 * h == 3600 * s);
 static_assert(1 * km + 1 * m == 1001 * m);
 
@@ -90,12 +90,9 @@ and dimensional analysis can be performed without sacrificing on runtime perform
 accuracy. Please see the below example for a quick preview of basic library features:
 
 ```cpp
-#include <mp-units/format.h>
-#include <mp-units/ostream.h>
-#include <mp-units/systems/international/international.h>
-#include <mp-units/systems/isq/isq.h>
-#include <mp-units/systems/si/si.h>
+#include <iomanip>
 #include <iostream>
+import mp_units;
 
 using namespace mp_units;
 
@@ -118,13 +115,13 @@ int main()
   constexpr quantity v6 = value_cast<m / s>(v4);
   constexpr quantity v7 = value_cast<int>(v6);
 
-  std::cout << v1 << '\n';                                  // 110 km/h
-  std::cout << v2 << '\n';                                  // 70 mi/h
-  std::cout << std::format("{}", v3) << '\n';               // 110 km/h
-  std::cout << std::format("{:*^14}", v4) << '\n';          // ***70 mi/h****
-  std::cout << std::format("{:%Q in %q}", v5) << '\n';      // 30.5556 in m/s
-  std::cout << std::format("{0:%Q} in {0:%q}", v6) << '\n'; // 31.2928 in m/s
-  std::cout << std::format("{:%Q}", v7) << '\n';            // 31
+  std::cout << v1 << '\n';                                        // 110 km/h
+  std::cout << std::setw(10) << std::setfill('*') << v2 << '\n';  // ***70 mi/h
+  std::cout << std::format("{:*^10}\n", v3);                      // *110 km/h*
+  std::cout << std::format("{:%N in %U}\n", v4);                  // 70 in mi/h
+  std::cout << std::format("{:{%N:.2f}%?%U}\n", v5);              // 30.56 in m/s
+  std::cout << std::format("{:{%N:.2f}%?{%U:n}}\n", v6);          // 31.29 in m s⁻¹
+  std::cout << std::format("{:%N}\n", v7);                        // 31
 }
 ```
 

docs/getting_started/look_and_feel.md

@@ -13,7 +13,7 @@ Here is a small example of operations possible on scalar quantities:
     // simple numeric operations
     static_assert(10 * km / 2 == 5 * km);
 
-    // unit conversions
+    // conversions to common units
     static_assert(1 * h == 3600 * s);
     static_assert(1 * km + 1 * m == 1001 * m);
 
@@ -40,7 +40,7 @@ Here is a small example of operations possible on scalar quantities:
     // simple numeric operations
     static_assert(10 * km / 2 == 5 * km);
 
-    // unit conversions
+    // conversions to common units
     static_assert(1 * h == 3600 * s);
     static_assert(1 * km + 1 * m == 1001 * m);
 
@@ -56,7 +56,7 @@ Here is a small example of operations possible on scalar quantities:
     static_assert(1000 / (1 * s) == 1 * kHz);
     ```
 
-!!! example "[Try it on Compiler Explorer](https://godbolt.org/z/81Ev7qhTd)"
+!!! example "[Try it on Compiler Explorer](https://godbolt.org/z/ox8a8dGTz)"
 
 
 This library requires some C++20 features ([concepts and constraints](https://en.cppreference.com/w/cpp/language/constraints),
@@ -69,6 +69,7 @@ performed without sacrificing accuracy. Please see the below example for a quick
 === "C++ modules"
 
     ```cpp
+    #include <iomanip>
     #include <iostream>
     import mp_units;
 
@@ -93,13 +94,13 @@ performed without sacrificing accuracy. Please see the below example for a quick
       constexpr quantity v6 = value_cast<m / s>(v4);
       constexpr quantity v7 = value_cast<int>(v6);
 
-      std::cout << v1 << '\n';                                  // 110 km/h
-      std::cout << v2 << '\n';                                  // 70 mi/h
-      std::cout << std::format("{}", v3) << '\n';               // 110 km/h
-      std::cout << std::format("{:*^14}", v4) << '\n';          // ***70 mi/h****
-      std::cout << std::format("{:%Q in %q}", v5) << '\n';      // 30.5556 in m/s
-      std::cout << std::format("{0:%Q} in {0:%q}", v6) << '\n'; // 31.2928 in m/s
-      std::cout << std::format("{:%Q}", v7) << '\n';            // 31
+      std::cout << v1 << '\n';                                        // 110 km/h
+      std::cout << std::setw(10) << std::setfill('*') << v2 << '\n';  // ***70 mi/h
+      std::cout << std::format("{:*^10}\n", v3);                      // *110 km/h*
+      std::cout << std::format("{:%N in %U}\n", v4);                  // 70 in mi/h
+      std::cout << std::format("{:{%N:.2f}%?%U}\n", v5);              // 30.56 in m/s
+      std::cout << std::format("{:{%N:.2f}%?{%U:n}}\n", v6);          // 31.29 in m s⁻¹
+      std::cout << std::format("{:%N}\n", v7);                        // 31
     }
     ```
 
@@ -111,6 +112,7 @@ performed without sacrificing accuracy. Please see the below example for a quick
     #include <mp-units/systems/international/international.h>
     #include <mp-units/systems/isq/isq.h>
     #include <mp-units/systems/si/si.h>
+    #include <iomanip>
     #include <iostream>
 
     using namespace mp_units;
@@ -134,13 +136,13 @@ performed without sacrificing accuracy. Please see the below example for a quick
       constexpr quantity v6 = value_cast<m / s>(v4);
       constexpr quantity v7 = value_cast<int>(v6);
 
-      std::cout << v1 << '\n';                                  // 110 km/h
-      std::cout << v2 << '\n';                                  // 70 mi/h
-      std::cout << std::format("{}", v3) << '\n';               // 110 km/h
-      std::cout << std::format("{:*^14}", v4) << '\n';          // ***70 mi/h****
-      std::cout << std::format("{:%Q in %q}", v5) << '\n';      // 30.5556 in m/s
-      std::cout << std::format("{0:%Q} in {0:%q}", v6) << '\n'; // 31.2928 in m/s
-      std::cout << std::format("{:%Q}", v7) << '\n';            // 31
+      std::cout << v1 << '\n';                                        // 110 km/h
+      std::cout << std::setw(10) << std::setfill('*') << v2 << '\n';  // ***70 mi/h
+      std::cout << std::format("{:*^10}\n", v3);                      // *110 km/h*
+      std::cout << std::format("{:%N in %U}\n", v4);                  // 70 in mi/h
+      std::cout << std::format("{:{%N:.2f}%?%U}\n", v5);              // 30.56 in m/s
+      std::cout << std::format("{:{%N:.2f}%?{%U:n}}\n", v6);          // 31.29 in m s⁻¹
+      std::cout << std::format("{:%N}\n", v7);                        // 31
     }
     ```
 

docs/users_guide/examples/hello_units.md

@@ -18,20 +18,20 @@ First, we either import the `mp_units` module or include the headers for:
 - text formatting and stream output support
 
 ```cpp title="hello_units.cpp" linenums="1"
---8<-- "example/hello_units.cpp:28:39"
+--8<-- "example/hello_units.cpp:28:40"
 ```
 
 Also, to shorten the definitions, we "import" all the symbols from the `mp_units` namespace.
 
-```cpp title="hello_units.cpp" linenums="12"
---8<-- "example/hello_units.cpp:40:41"
+```cpp title="hello_units.cpp" linenums="13"
+--8<-- "example/hello_units.cpp:41:42"
 ```
 
 Next, we define a simple function that calculates the average speed based on the provided
 arguments of length and time:
 
-```cpp title="hello_units.cpp" linenums="13"
---8<-- "example/hello_units.cpp:42:45"
+```cpp title="hello_units.cpp" linenums="14"
+--8<-- "example/hello_units.cpp:43:46"
 ```
 
 The above function template takes any quantities implicitly convertible to `isq::length`
@@ -45,16 +45,16 @@ that its quantity type is implicitly convertible to `isq::speed`.
     type is beneficial for users of such a function as it provides more information
     of what to expect from a function than just using `auto`.
 
-```cpp title="hello_units.cpp" linenums="17"
---8<-- "example/hello_units.cpp:47:50"
+```cpp title="hello_units.cpp" linenums="18"
+--8<-- "example/hello_units.cpp:48:51"
 ```
 
 The above lines explicitly opt into using unit symbols from two systems of units.
 As this introduces a lot of short identifiers into the current scope, it is not done
 implicitly while including a header file.
 
-```cpp title="hello_units.cpp" linenums="21"
---8<-- "example/hello_units.cpp:52:58"
+```cpp title="hello_units.cpp" linenums="22"
+--8<-- "example/hello_units.cpp:53:59"
 ```
 
 - Lines `21` & `22` create a quantity of kind `isq::length / isq::time` with the numbers
@@ -74,8 +74,8 @@ implicitly while including a header file.
 - Line `27` does a [value-truncating conversion](../framework_basics/value_conversions.md#value-truncating-conversions)
   of changing the underlying representation type from `double` to `int`.
 
-```cpp title="hello_units.cpp" linenums="28"
---8<-- "example/hello_units.cpp:60"
+```cpp title="hello_units.cpp" linenums="29"
+--8<-- "example/hello_units.cpp:61"
 ```
 
 The above presents [various ways to print a quantity](../framework_basics/text_output.md).

example/clcpp_response.cpp

@@ -118,7 +118,7 @@ void calcs_comparison()
   const auto L1A = 2.f * fm;
   const auto L2A = 3.f * fm;
   const auto LrA = L1A + L2A;
-  std::cout << MP_UNITS_STD_FMT::format("{:%.30Q %q}\n + {:%.30Q %q}\n   = {:%.30Q %q}\n\n", L1A, L2A, LrA);
+  std::cout << MP_UNITS_STD_FMT::format("{:{%N:.30} %U}\n + {:{%N:.30} %U}\n   = {:{%N:.30} %U}\n\n", L1A, L2A, LrA);
 
   std::cout << "The single unit method must convert large\n"
                "or small values in other units to the base unit.\n"
@@ -127,17 +127,17 @@ void calcs_comparison()
   const auto L1B = L1A.in(m);
   const auto L2B = L2A.in(m);
   const auto LrB = L1B + L2B;
-  std::cout << MP_UNITS_STD_FMT::format("{:%.30eQ %q}\n + {:%.30eQ %q}\n   = {:%.30eQ %q}\n\n", L1B, L2B, LrB);
+  std::cout << MP_UNITS_STD_FMT::format("{:{%N:.30e} %U}\n + {:{%N:.30e} %U}\n   = {:{%N:.30e} %U}\n\n", L1B, L2B, LrB);
 
   std::cout << "In multiplication and division:\n\n";
 
   const quantity<isq::area[square(fm)], float> ArA = L1A * L2A;
-  std::cout << MP_UNITS_STD_FMT::format("{:%.30Q %q}\n * {:%.30Q %q}\n   = {:%.30Q %q}\n\n", L1A, L2A, ArA);
+  std::cout << MP_UNITS_STD_FMT::format("{:{%N:.30} %U}\n * {:{%N:.30} %U}\n   = {:{%N:.30} %U}\n\n", L1A, L2A, ArA);
 
   std::cout << "similar problems arise\n\n";
 
   const quantity<isq::area[m2], float> ArB = L1B * L2B;
-  std::cout << MP_UNITS_STD_FMT::format("{:%.30eQ %q}\n * {:%.30eQ %q}\n   = {:%.30eQ %q}\n\n", L1B, L2B, ArB);
+  std::cout << MP_UNITS_STD_FMT::format("{:{%N:.30e} %U}\n * {:{%N:.30e} %U}\n   = {:{%N:.30e} %U}\n\n", L1B, L2B, ArB);
 }
 
 }  // namespace

example/conversion_factor.cpp

@@ -58,7 +58,7 @@ int main()
 
   std::cout << MP_UNITS_STD_FMT::format("therefore ratio lengthA / lengthB == {}\n\n", lengthA / lengthB);
 
-  std::cout << MP_UNITS_STD_FMT::format("conversion factor from lengthA::unit of {:%q} to lengthB::unit of {:%q}:\n\n",
+  std::cout << MP_UNITS_STD_FMT::format("conversion factor from lengthA::unit of {:%U} to lengthB::unit of {:%U}:\n\n",
                                         lengthA, lengthB)
             << MP_UNITS_STD_FMT::format("lengthB.value( {} ) == lengthA.value( {} ) * conversion_factor( {} )\n",
                                         lengthB.numerical_value_ref_in(lengthB.unit),

example/glide_computer.cpp

@@ -87,8 +87,8 @@ void print(const R& gliders)
     std::cout << "- Polar:\n";
     for (const auto& p : g.polar) {
       const auto ratio = glide_ratio(g.polar[0]).force_in(one);
-      std::cout << MP_UNITS_STD_FMT::format("  * {:%.4Q %q} @ {:%.1Q %q} -> {:%.1Q %q} ({:%.1Q %q})\n", p.climb, p.v,
-                                            ratio,
+      std::cout << MP_UNITS_STD_FMT::format("  * {:{%N:.4} %U} @ {:{%N:.1} %U} -> {:{%N:.1} %U} ({:{%N:.1} %U})\n",
+                                            p.climb, p.v, ratio,
                                             // TODO is it possible to make ADL work below (we need another set of trig
                                             // functions for strong angle in a different namespace)
                                             si::asin(1 / ratio).force_in(si::degree));
@@ -106,8 +106,8 @@ void print(const R& conditions)
   for (const auto& c : conditions) {
     std::cout << "- " << c.first << "\n";
     const auto& w = c.second;
-    std::cout << "  * Cloud base:        " << MP_UNITS_STD_FMT::format("{:%.0Q %q}", w.cloud_base) << " AGL\n";
-    std::cout << "  * Thermals strength: " << MP_UNITS_STD_FMT::format("{:%.1Q %q}", w.thermal_strength) << "\n";
+    std::cout << "  * Cloud base:        " << MP_UNITS_STD_FMT::format("{:{%N:.0} %U}", w.cloud_base) << " AGL\n";
+    std::cout << "  * Thermals strength: " << MP_UNITS_STD_FMT::format("{:{%N:.1} %U}", w.thermal_strength) << "\n";
     std::cout << "\n";
   }
 }
@@ -119,7 +119,7 @@ void print(const R& waypoints)
   std::cout << "Waypoints:\n";
   std::cout << "==========\n";
   for (const auto& w : waypoints)
-    std::cout << MP_UNITS_STD_FMT::format("- {}: {} {}, {:%.1Q %q}\n", w.name, w.pos.lat, w.pos.lon, w.alt);
+    std::cout << MP_UNITS_STD_FMT::format("- {}: {} {}, {:{%N:.1} %U}\n", w.name, w.pos.lat, w.pos.lon, w.alt);
   std::cout << "\n";
 }
 
@@ -130,12 +130,12 @@ void print(const task& t)
 
   std::cout << "- Start: " << t.get_start().name << "\n";
   std::cout << "- Finish: " << t.get_finish().name << "\n";
-  std::cout << "- Length:  " << MP_UNITS_STD_FMT::format("{:%.1Q %q}", t.get_distance()) << "\n";
+  std::cout << "- Length:  " << MP_UNITS_STD_FMT::format("{:{%N:.1} %U}", t.get_distance()) << "\n";
 
   std::cout << "- Legs: "
             << "\n";
   for (const auto& l : t.get_legs())
-    std::cout << MP_UNITS_STD_FMT::format("  * {} -> {} ({:%.1Q %q})\n", l.begin().name, l.end().name,
+    std::cout << MP_UNITS_STD_FMT::format("  * {} -> {} ({:{%N:.1} %U})\n", l.begin().name, l.end().name,
                                           l.get_distance());
   std::cout << "\n";
 }
@@ -144,7 +144,7 @@ void print(const safety& s)
 {
   std::cout << "Safety:\n";
   std::cout << "=======\n";
-  std::cout << "- Min AGL separation: " << MP_UNITS_STD_FMT::format("{:%.0Q %q}", s.min_agl_height) << "\n";
+  std::cout << "- Min AGL separation: " << MP_UNITS_STD_FMT::format("{:{%N:.0} %U}", s.min_agl_height) << "\n";
   std::cout << "\n";
 }
 
@@ -153,8 +153,8 @@ void print(const aircraft_tow& tow)
   std::cout << "Tow:\n";
   std::cout << "====\n";
   std::cout << "- Type:        aircraft\n";
-  std::cout << "- Height:      " << MP_UNITS_STD_FMT::format("{:%.0Q %q}", tow.height_agl) << "\n";
-  std::cout << "- Performance: " << MP_UNITS_STD_FMT::format("{:%.1Q %q}", tow.performance) << "\n";
+  std::cout << "- Height:      " << MP_UNITS_STD_FMT::format("{:{%N:.0} %U}", tow.height_agl) << "\n";
+  std::cout << "- Performance: " << MP_UNITS_STD_FMT::format("{:{%N:.1} %U}", tow.performance) << "\n";
   std::cout << "\n";
 }
 

example/glide_computer_lib/glide_computer_lib.cpp

@@ -82,7 +82,8 @@ void print(std::string_view phase_name, timestamp start_ts, const glide_computer
            const glide_computer::flight_point& new_point)
 {
   std::cout << MP_UNITS_STD_FMT::format(
-    "| {:<12} | {:>9%.1Q %q} (Total: {:>9%.1Q %q}) | {:>8%.1Q %q} (Total: {:>8%.1Q %q}) | {:>7%.0Q %q} ({:>6%.0Q %q}) "
+    "| {:<12} | {:>9{%N:.1} %U} (Total: {:>9{%N:.1} %U}) | {:>8{%N:.1} %U} (Total: {:>8{%N:.1} %U}) | {:>7{%N:.0} %U} "
+    "({:>6{%N:.0} %U}) "
     "|\n",
     phase_name, value_cast<si::minute>(new_point.ts - point.ts), value_cast<si::minute>(new_point.ts - start_ts),
     new_point.dist - point.dist, new_point.dist, new_point.alt - point.alt, new_point.alt);

example/hello_units.cpp

@@ -26,6 +26,7 @@
 // !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
 #include <mp-units/compat_macros.h>
+#include <iomanip>
 #include <iostream>
 #ifdef MP_UNITS_MODULES
 import mp_units;
@@ -57,11 +58,11 @@ int main()
   constexpr quantity v6 = value_cast<m / s>(v4);
   constexpr quantity v7 = value_cast<int>(v6);
 
-  std::cout << v1 << '\n';                                                // 110 km/h
-  std::cout << v2 << '\n';                                                // 70 mi/h
-  std::cout << MP_UNITS_STD_FMT::format("{}", v3) << '\n';                // 110 km/h
-  std::cout << MP_UNITS_STD_FMT::format("{:*^14}", v4) << '\n';           // ***70 mi/h****
-  std::cout << MP_UNITS_STD_FMT::format("{:%Q in %q}", v5) << '\n';       // 30.5556 in m/s
-  std::cout << MP_UNITS_STD_FMT::format("{0:%Q} in {0:%q}", v6) << '\n';  // 31.2928 in m/s
-  std::cout << MP_UNITS_STD_FMT::format("{:%Q}", v7) << '\n';             // 31
+  std::cout << v1 << '\n';                                             // 110 km/h
+  std::cout << std::setw(10) << std::setfill('*') << v2 << '\n';       // ***70 mi/h
+  std::cout << MP_UNITS_STD_FMT::format("{:*^10}\n", v3);              // *110 km/h*
+  std::cout << MP_UNITS_STD_FMT::format("{:%N in %U}\n", v4);          // 70 in mi/h
+  std::cout << MP_UNITS_STD_FMT::format("{:{%N:.2f}%?%U}\n", v5);      // 30.56 in m/s
+  std::cout << MP_UNITS_STD_FMT::format("{:{%N:.2f}%?{%U:n}}\n", v6);  // 31.29 in m s⁻¹
+  std::cout << MP_UNITS_STD_FMT::format("{:%N}\n", v7);                // 31
 }