Merge pull request #1090 from cppalliance/1088

Add notes to basics section on underflow, overflow, and non-finite values handling

Author: mborland

doc/modules/ROOT/pages/basics.adoc

@@ -28,11 +28,19 @@ This is designed to reduce confusion (e.g. what would be the resulting sign of `
 
 [souce, c++]
 ----
-boost::decimal::decimal32_t a {1, 1};          // constructs 1e1 = 10
-boost::decimal::decimal32_t b {-2, -1};        // constructs -2e-2 or -0.2
-boost::decimal::decimal32_t c {2, -1, true};   // also constructs -2e-1 or -0.2
-boost::decimal::decimal32_t e {5, 5};          // constructs 5x10^5
-boost::decimal::decimal32_t f {1234, -3}       // constructs 1.234 or 1234x10^-3
+boost::decimal::decimal32_t a {1, 1};           // constructs 1e1 = 10
+boost::decimal::decimal32_t b {-2, -1};         // constructs -2e-2 or -0.2
+boost::decimal::decimal32_t c {2U, -1, true};   // also constructs -2e-1 or -0.2 (Note: The coefficient must be an unsigned type)
+boost::decimal::decimal32_t e {5, 5};           // constructs 5x10^5
+boost::decimal::decimal32_t f {1234, -3}        // constructs 1.234 or 1234x10^-3
+----
+
+Overflow and underflow are handled the same way that they are with binary floating point numbers i.e. they will construct an infinity or a zero.
+
+[source, c++]
+----
+boost::decimal::decimal64_t oveflow_value {100, 10000}; // Constructs +infinity
+boost::decimal::decimal64_t underflow_value {100, -10000}; // Constructs 0
 ----
 
 === Construction from Integer
@@ -56,6 +64,9 @@ For example:
 boost::decimal::decimal128_t pi {3.14};
 ----
 
+Construction from non-finite values (e.g. `std::numeric_limits<double>::quiet_NaN()`) will yield the same non-finite value in the resulting decimal value.
+Overflow or underflow will construct infinity or 0.
+
 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

examples/basic_construction.cpp

@@ -40,6 +40,25 @@ int main()
         std::cout << "Floats are not equal" << std::endl;
     }
 
+    // Demonstration of the overflow and underflow handling
+    constexpr decimal64_t oveflow_value {100, 10000};
+    if (isinf(oveflow_value))
+    {
+        std::cout << "Overflow constructs infinity" << std::endl;
+    }
+
+    constexpr decimal64_t underflow_value {100, -10000};
+    if (underflow_value == 0)
+    {
+        std::cout << "Underflow constructs zero" << std::endl;
+    }
+
+    const decimal32_t non_finite_from_float {std::numeric_limits<double>::quiet_NaN()};
+    if (isnan(non_finite_from_float))
+    {
+        std::cout << "NaN constructs NaN" << std::endl;
+    }
+
     return 0;
 }