Merge branch 'develop' into local_metal_benching

Author: ckormanyos

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#x64_linux_benchmarks[x64 Linux]
+** xref:benchmarks.adoc#x64_windows_benchmarks[x64 Windows]
+** xref:benchmarks.adoc#m4_mac_benchmarks[ARM64 macOS]
 * 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>`.