Merge pull request #1273 from cppalliance/examples

Add simple arithmetic differences example

Author: mborland

doc/modules/ROOT/pages/examples.adoc

@@ -54,6 +54,21 @@ Wolfram Alpha sqrt(2): 1.414213562373095
 ....
 ====
 
+[#examples_math_results]
+.This https://github.com/cppalliance/decimal/blob/develop/examples/addition.cpp[example] shows the differences in arithmetic results between decimal floating point and binary floating point
+====
+[source,c++]
+----
+include::example$addition.cpp[]
+----
+
+.Expected Output:
+....
+Decimal Result: 100
+  Float Result: 99.999
+....
+====
+
 [#examples_promotion]
 == Promotion and Mixed Decimal Arithmetic
 

examples/addition.cpp

@@ -0,0 +1,37 @@
+// Copyright 2025 Matt Borland
+// Distributed under the Boost Software License, Version 1.0.
+// https://www.boost.org/LICENSE_1_0.txt
+//
+// This example shows the difference in the results of repeated addition
+
+#include <boost/decimal/decimal32_t.hpp>    // For type decimal32_t and std::numeric_limits support
+#include <boost/decimal/iostream.hpp>       // For decimal support to <iostream>
+#include <iostream>
+#include <limits>
+
+int main()
+{
+    using boost::decimal::decimal32_t;
+
+    constexpr decimal32_t decimal_one_tenth {"0.1"}; // Construct constant 0.1 from string for lossless conversion
+    constexpr float float_one_tenth {0.1f};              // Construct floating point constant from literal
+
+    decimal32_t decimal_value {};   // Construct decimal 0 to start from
+    float float_value {};           // Construct float 0 to start from
+
+    // We now add 0.1 1000 times which should result exactly in 100
+    // What we actually find is that the decimal32_t value does result in exactly 100
+    // With type float the result is not 100 due to inexact representation
+    for (int i {}; i < 1000; ++i)
+    {
+        decimal_value += decimal_one_tenth; // Decimal types support compound arithmetic as expected
+        float_value += float_one_tenth;
+    }
+
+    // Each of the decimal types has complete support for std::numeric_limits,
+    // which we leverage here with set precision to show any fractional part of the number (if applicable)
+    std::cout << std::setprecision(std::numeric_limits<decimal32_t>::digits10)
+              << "Decimal Result: " << decimal_value << "\n"
+              << std::setprecision(std::numeric_limits<float>::digits10)
+              << "  Float Result: " << float_value << std::endl;
+}

test/Jamfile

@@ -212,6 +212,7 @@ run ../examples/numerical_parsing.cpp ;
 run ../examples/first_example.cpp ;
 run ../examples/basic_arithmetic.cpp ;
 run ../examples/to_from_file.cpp ;
+run ../examples/addition.cpp ;
 
 # Test compilation of separate headers
 compile compile_tests/bid_conversion.cpp ;