Update our fmt formatting example

Author: mborland

doc/modules/ROOT/pages/examples.adoc

@@ -153,48 +153,95 @@ This example could be extended with the simple moving average to create full ban
 == Formatting
 
 Boost.Decimal allows you to format your output with both `<format>` and `<fmt/format.h>` depending on your compiler support.
+pass:[{fmt}] support is available starting with pass:[C++14] so long as you have the library available, but `<format>` requires pass:[C++20] and compiler support
 
-[#examples_std_format]
-=== `<format>`
+[#examples_fmt_format]
+=== `<fmt/format.hpp>`
 
-If your compiler provides `<format>` you can use that to format the output of your values:
+We also provide support for pass:[{fmt}] so you can easily just swap the namespaces and headers on the above example:
 
 [source, c++]
 ----
-#include <boost/decimal.hpp>
+// Copyright 2025 Matt Borland
+// Distributed under the Boost Software License, Version 1.0.
+// https://www.boost.org/LICENSE_1_0.txt
+//
+// This example demonstrates usage and formatting of decimal types with fmt
+
+#include <boost/decimal/decimal32_t.hpp>    // For type decimal32_t
+#include <boost/decimal/decimal64_t.hpp>    // For type decimal64_t
+#include <boost/decimal/fmt_format.hpp>     // For {fmt} support
 #include <iostream>
-#include <format>
 
 int main()
 {
-    constexpr boost::decimal::decimal64_t val1 {314, -2};
-    constexpr boost::decimal::decimal32_t val2 {3141, -3};
-
-    std::cout << std::format("{:10.3e}", val1) << '\n';
-    std::cout << std::format("{:10.3e}", val2) << std::endl;
+    constexpr boost::decimal::decimal64_t val1 {"3.14"};
+    constexpr boost::decimal::decimal32_t val2 {"3.141"};
+
+    // The easiest is no specification which is general format
+    // Given these values they will print in fixed format
+    std::cout << "Default Format:\n";
+    std::cout << fmt::format("{}", val1) << '\n';
+    std::cout << fmt::format("{}", val2) << "\n\n";
+
+    // Next we can add a type modifier to get scientific formatting
+    std::cout << "Scientific Format:\n";
+    std::cout << fmt::format("{:e}", val1) << '\n';
+    std::cout << fmt::format("{:e}", val2) << "\n\n";
+
+    // Next we can add a type modifier to get scientific formatting
+    // Here this gives one digit of precision rounded according to current rounding mode
+    std::cout << "Scientific Format with Specified Precision:\n";
+    std::cout << fmt::format("{:.1e}", val1) << '\n';
+    std::cout << fmt::format("{:.1e}", val2) << "\n\n";
+
+    // This combines the padding modifier (10), precision (3 digits), and a type modifier (e)
+    std::cout << "Scientific Format with Specified Precision and Padding:\n";
+    std::cout << fmt::format("{:10.3e}", val1) << '\n';
+    std::cout << fmt::format("{:10.3e}", val2) << '\n';
 
     return 0;
 }
 ----
 
-[#examples_fmt_format]
-=== `<fmt/format.hpp>`
+Expected Output:
+----
+Default Format:
+3.14
+3.141
 
-We also provide support for pass:[{fmt}] so you can easily just swap the namespaces and headers on the above example:
+Scientific Format:
+3.14e+00
+3.141e+00
+
+Scientific Format with Specified Precision:
+3.1e+00
+3.1e+00
+
+Scientific Format with Specified Precision and Padding:
+03.140e+00
+03.141e+00
+----
+
+[#examples_std_format]
+=== `<format>`
+
+Taking the above example of pass:[{fmt}] and replacing all instances of `namespace fmt` with `namespace std` gives us another working example.
+This example can be found in the `examples/` folder as https://github.com/cppalliance/decimal/blob/develop/examples/format.cpp[format.cpp]
 
 [source, c++]
 ----
 #include <boost/decimal.hpp>
 #include <iostream>
-#include <fmt/format.h>
+#include <format>
 
 int main()
 {
     constexpr boost::decimal::decimal64_t val1 {314, -2};
     constexpr boost::decimal::decimal32_t val2 {3141, -3};
 
-    std::cout << fmt::format("{:10.3e}", val1) << '\n';
-    std::cout << fmt::format("{:10.3e}", val2) << std::endl;
+    std::cout << std::format("{:10.3e}", val1) << '\n';
+    std::cout << std::format("{:10.3e}", val2) << std::endl;
 
     return 0;
 }

examples/fmt_format.cpp

@@ -1,9 +1,12 @@
 // Copyright 2025 Matt Borland
 // Distributed under the Boost Software License, Version 1.0.
 // https://www.boost.org/LICENSE_1_0.txt
+//
+// This example demonstrates usage and formatting of decimal types with fmt
 
-#include <boost/decimal.hpp>
-#include <boost/decimal/fmt_format.hpp>
+#include <boost/decimal/decimal32_t.hpp>    // For type decimal32_t
+#include <boost/decimal/decimal64_t.hpp>    // For type decimal64_t
+#include <boost/decimal/fmt_format.hpp>     // For {fmt} support
 #include <iostream>
 
 #if defined(BOOST_DECIMAL_HAS_FMTLIB_SUPPORT) && defined(BOOST_DECIMAL_TEST_FMT)