Merge pull request #939 from cppalliance/misc_improvments

Misc doc improvements

Author: mborland

doc/modules/ROOT/nav.adoc

@@ -1,12 +1,26 @@
 * xref:overview.adoc[]
 * xref:basics.adoc[]
 * xref:examples.adoc[]
+** xref:examples.adoc#examples_construction[Construction]
+** xref:examples.adoc#examples_promotion[Type Promotion]
+** xref:examples.adoc#examples_charconv[`<charconv>`]
+** xref:examples.adoc#examples_rounding_mode[Rounding Mode]
+** xref:examples.adoc#examples_generic_programming[Generic Programming]
+** xref:examples.adoc#examples_literals_constants[Literals and Constants]
+** xref:examples.adoc#examples_bit_conversions[Bit Conversions]
+** xref:examples.adoc#examples_finance[Financial Applications]
+** xref:examples.adoc#examples_boost_math[Boost.Math Integration]
 * xref:api_reference.adoc[]
-* xref:generic_decimal.adoc[]
+** xref:api_reference.adoc#api_ref_types[Types]
+** xref:api_reference.adoc#api_ref_structs[Structs]
+** xref:api_reference.adoc#api_ref_enums[Enums]
+** xref:api_reference.adoc#api_ref_constants[Constants]
+** xref:api_reference.adoc#api_ref_macros[Macros]
+* xref:generic_decimal.adoc[IEEE 754 Decimal Types]
 ** xref:decimal32_t.adoc[]
 ** xref:decimal64_t.adoc[]
 ** xref:decimal128_t.adoc[]
-* xref:fast_types.adoc[]
+* xref:fast_types.adoc[Non-IEEE 754 Decimal Types]
 ** xref:decimal_fast32_t.adoc[]
 ** xref:decimal_fast64_t.adoc[]
 ** xref:decimal_fast128_t.adoc[]
@@ -27,6 +41,9 @@
 * xref:limits.adoc[]
 * xref:config.adoc[]
 * xref:benchmarks.adoc[]
+** xref:benchmarks.adoc#comparisons[Comparisons]
+** xref:benchmarks.adoc#basic_operations[Add, Sub, Mul, Div]
+** xref:benchmarks.adoc#benchmark_charconv[`<charconv>`]
 * xref:design.adoc[]
 * xref:reference.adoc[]
 * xref:copyright.adoc[]

doc/modules/ROOT/pages/api_reference.adoc

@@ -11,6 +11,7 @@ https://www.boost.org/LICENSE_1_0.txt
 This section is a complete cross-reference to all the types, structures,
 enums, constants and macros that are provided in this library.
 
+[#api_ref_types]
 == Types
 
 === IEEE 754 Compliant Types
@@ -25,20 +26,24 @@ enums, constants and macros that are provided in this library.
 - xref:decimal_fast64_t.adoc[decimal_fast64_t]
 - xref:decimal_fast128_t.adoc[decimal_fast128_t]
 
+[#api_ref_structs]
 == Structures
 
 - xref:charconv.adoc#to_chars_result[to_chars_result]
 - xref:charconv.adoc#from_chars_result[from_chars_result]
 
+[#api_ref_enums]
 == Enums
 
 - xref:charconv.adoc#chars_format[chars_format]
 
+[#api_ref_constants]
 == Constants
 
 - xref:charconv.adoc#charconv_limits[limits]
 - xref:numbers.adoc[numbers]
 
+[#api_ref_macros]
 == Macros
 
 See: xref:config.adoc[configuration]

doc/modules/ROOT/pages/basics.adoc

@@ -58,6 +58,33 @@ boost::decimal::decimal128_t pi {3.14};
 
 NOTE: Due to the differences in decimal and binary floating point numbers there may be a difference in the resulting representation in decimal format, and thus it is not recommended to construct from binary floating point numbers
 
+== Fundamental Operations
+
+The fundamental operations of numerical type (e.g. `>`, `==`, `+`, etc.) are overloaded.
+
+[source, c++]
+----
+#include <boost/decimal.hpp>
+#include <cassert>
+
+int main()
+{
+    constexpr boost::decimal::decimal32_t lhs {5};
+    constexpr boost::decimal::decimal32_t rhs {1, -1};
+
+    assert(lhs > rhs);
+    assert(lhs != rhs);
+    assert(lhs + rhs > lhs);
+
+    auto new_lhs {lhs}; // Using auto is safe when constructring from existing decimal values
+    new_lhs += lhs;
+
+    assert(lhs < new_lhs);
+
+    return 0;
+}
+----
+
 == Using the Library
 
 The entire library can be accessed using the convenience header `<boost/decimal.hpp>`.

doc/modules/ROOT/pages/benchmarks.adoc

@@ -20,6 +20,7 @@ IMPORTANT: On nearly all platforms there is hardware support for binary floating
 To run the benchmarks yourself, navigate to the test folder and define `BOOST_DECIMAL_RUN_BENCHMARKS` when running the tests.
 An example on Linux with b2: `../../../b2 cxxstd=20 toolset=gcc-13 define=BOOST_DECIMAL_RUN_BENCHMARKS benchmarks -a release` .
 
+[#comparisons]
 == Comparisons
 
 The benchmark for comparisons generates a random vector containing 20,000,000 elements and does operations `>`, `>=`, `<`, `\<=`, `==`, and `!=` between `vec[i] and vec[i + 1]`.
@@ -130,6 +131,7 @@ Run using a Macbook pro with M4 Max chipset running macOS Sequoia 15.5 and homeb
 | 11.563
 |===
 
+[#basic_operations]
 == Basic Operations
 
 The benchmark for these operations generates a random vector containing 20,000,000 elements and does operations `+`, `-`, `*`, `/` between `vec[i] and vec[i + 1]`.
@@ -547,6 +549,7 @@ Run using a Macbook pro with M4 Max chipset running macOS Sequoia 15.5 and homeb
 | 458.320
 |===
 
+[#benchmark_charconv]
 == `<charconv>`
 
 Parsing and serializing number exactly is one of the key features of decimal floating point types, so we must compare the performance of `<charconv>`. For all the following the results compare against STL provided `<charconv>` for 20,000,000 conversions.

doc/modules/ROOT/pages/cfenv.adoc

@@ -10,17 +10,17 @@ https://www.boost.org/LICENSE_1_0.txt
 
 == <cfenv>
 
-As opposed to binary floating point types IEEE 754 defined 5 rounding modes instead of 4. They are:
+IEEE 754 defines 5 rounding modes for Decimal Floating Point Types.
 
 1. Downward
 2. To nearest
 3. To nearest from zero
 4. Toward zero
 5. Upward
 
-The default rounding mode is to nearest from zero.
+NOTE: The default rounding mode is to nearest from zero (#3).
 
-IMPORTANT: The rounding mode can only be changed at runtime. All constexpr calculations will use the default of to nearest from zero.
+IMPORTANT: The rounding mode can only be changed at runtime. All `constexpr` calculations will use the default of to nearest from zero.
 
 [source, c++]
 ----

doc/modules/ROOT/pages/cfloat.adoc

@@ -14,19 +14,19 @@ The following macros analogous to those from `<cfloat>` for the decimal floating
 ----
 
 // Number of digits in the coefficient
-#define BOOST_DECIMAL_DEC32_MANT_DIG  7
-#define BOOST_DECIMAL_DEC64_MANT_DIG  16
-#define BOOST_DECIMAL_DEC128_MANT_DIG 34
+#define BOOST_DECIMAL_DEC32_MANT_DIG  std::numeric_limits<boost::decimal::decimal32_t>:digits10
+#define BOOST_DECIMAL_DEC64_MANT_DIG  std::numeric_limits<boost::decimal::decimal64_t>:digits10
+#define BOOST_DECIMAL_DEC128_MANT_DIG std::numeric_limits<boost::decimal::decimal128_t>:digits10
 
 // Minimum exponent
-#define BOOST_DECIMAL_DEC32_MIN_EXP  -94
-#define BOOST_DECIMAL_DEC64_MIN_EXP  -382
-#define BOOST_DECIMAL_DEC128_MIN_EXP -6142
+#define BOOST_DECIMAL_DEC32_MIN_EXP  std::numeric_limits<boost::decimal::decimal32_t>:min_exponent
+#define BOOST_DECIMAL_DEC64_MIN_EXP  std::numeric_limits<boost::decimal::decimal64_t>:min_exponent
+#define BOOST_DECIMAL_DEC128_MIN_EXP std::numeric_limits<boost::decimal::decimal128_t>:min_exponent
 
 // Maximum exponent
-#define BOOST_DECIMAL_DEC32_MAX_EXP  97
-#define BOOST_DECIMAL_DEC64_MAX_EXP  385
-#define BOOST_DECIMAL_DEC128_MAX_EXP 6145
+#define BOOST_DECIMAL_DEC32_MAX_EXP  std::numeric_limits<boost::decimal::decimal32_t>:max_exponent
+#define BOOST_DECIMAL_DEC64_MAX_EXP  std::numeric_limits<boost::decimal::decimal64_t>:max_exponent
+#define BOOST_DECIMAL_DEC128_MAX_EXP std::numeric_limits<boost::decimal::decimal128_t>:max_exponent
 
 // Maximum Finite Value
 #define BOOST_DECIMAL_DEC32_MAX  std::numeric_limits<boost::decimal::decimal32_t>::max()

doc/modules/ROOT/pages/config.adoc

@@ -23,13 +23,24 @@ This option is not recommended, but can be useful if you want to use specific fu
 
 [source, c++]
 ----
+#define BOOST_DECIMAL_ALLOW_IMPLICIT_CONVERSIONS
+#include <boost/decimal.hpp>
+#include <complex>
+
 constexpr decimal64_t half {5, -1};
 std::complex<decimal64_t> test_val {half, half};
 const auto res = std::acos(test_val);
 ----
 
 - `BOOST_DECIMAL_FAST_MATH` performs optimizations similar to that of the `-ffast-math` compiler flag such as removing all checks for non-finite values.
 This flag increases the performance of the basis operations (e.g. add, sub, mul, div, and comparisons) by up to 20%.
+Again, it must be defined before inclusion of decimal headers like so:
+
+[source, c++]
+----
+#define BOOST_DECIMAL_FAST_MATH
+#include <boost/decimal.hpp>
+----
 
 - `BOOST_DECIMAL_DEC_EVAL_METHOD`: See <cfloat> section for explanation
 

doc/modules/ROOT/pages/conversions.adoc

@@ -19,10 +19,10 @@ namespace decimal {
 
 namespace detail {
 
-struct uint128
+struct uint128_t
 {
-    std::uint64_t hi;
-    std::uint64_t lo;
+    std::uint64_t high;
+    std::uint64_t low;
 };
 
 } // namespace detail
@@ -56,9 +56,9 @@ constexpr decimal128_t from_bid_d128(unsigned __int128 bits) noexcept;
 
 #endif // BOOST_DECIMAL_HAS_INT128
 
-constexpr detail::uint128 to_bid_d128f(decimal_fast128_t val) noexcept;
+constexpr detail::uint128_t to_bid_d128f(decimal_fast128_t val) noexcept;
 
-constexpr decimal128_t from_bid_d128f(detail::uint128 bits) noexcept;
+constexpr decimal128_t from_bid_d128f(detail::uint128_t bits) noexcept;
 
 #ifdef BOOST_DECIMAL_HAS_INT128
 

doc/modules/ROOT/pages/copyright.adoc

@@ -8,5 +8,5 @@ https://www.boost.org/LICENSE_1_0.txt
 = Copyright and License
 :idprefix: license_
 
-This documentation is copyright 2023 Matt Borland and is distributed under
+This documentation is copyright 2023 - 2025 Matt Borland and Chris Kormanyos, and is distributed under
 the http://www.boost.org/LICENSE_1_0.txt[Boost Software License, Version 1.0].

doc/modules/ROOT/pages/cstdio.adoc

@@ -28,7 +28,7 @@ int printf(const char* format, Dec... values) noexcept;
 } //namespace boost
 ----
 
-=== Type Modifiers
+== Type Modifiers
 
 The type modifiers to be used are:
 
@@ -45,10 +45,10 @@ The remaining specifications of cstdio are the same as usual:
 
 NOTE: The uppercase format will return with all applicable values in uppercase (e.g. 3.14E+02 vs 3.14e+02)
 
-=== Examples
+== Examples
 
 Here are some example formats:
 
 - "%Hg" will print a `decimal32_t` in general format
-- "%.3De" will print a `decimal64_t` in scientific format with 3 digits of precision
-- "%.5DDA" will print a `decimal128_t` in hex format with 5 digits of precision and all letters will be capitalized (e.g. 1.F2CP+2 vs 1.f2cp+2)
+- "%.3De" will print a `decimal64_t` in scientific format with 3 digits of precision (e.g. 1.234e+05)
+- "%.5DDA" will print a `decimal128_t` in hex format with 5 digits of precision and all letters will be capitalized (e.g. 1.F2C34P+02 vs 1.f2c34p+02)