Merge pull request #1245 from cppalliance/docsdocs

More doc and example fixes

Author: mborland

doc/modules/ROOT/pages/cmath.adoc

@@ -543,6 +543,7 @@ constexpr bool issignaling(Decimal x) noexcept;
 ----
 
 Effects: If x is an sNaN returns true, otherwise returns false.
+This function does not signal even if x is an sNaN per IEEE 754 section 5.7.2.
 
 === `read_payload`
 
@@ -661,6 +662,7 @@ constexpr auto frexp10(Decimal num, int* expptr) noexcept;
 
 This function is very similar to https://en.cppreference.com/w/cpp/numeric/math/frexp[frexp], but returns the significand and an integral power of 10 since the `FLT_RADIX` of this type is 10.
 The significand is normalized to the number of digits of precision the type has (e.g. for decimal32_t it is [1'000'000, 9'999'999]).
+For further discussion on normalized form see the page on xref:cohorts.adoc[cohorts].
 
 === `normalize`
 

doc/modules/ROOT/pages/cohorts.adoc

@@ -24,6 +24,9 @@ That means all the following are valid ways to represent the number 300 using th
 . 3000000e-4
 
 These values can be useful in certain applications, like preserving the precision of results.
+A value is said to be *normalized* when the effects of these cohorts is removed.
+This is done by appending zeros to the significand and reducing the exponent until the significand has the same number of significant digits as the type can represent.
+For example 1 - 6 above would all be represented the same as value 7.
 By default, most methods *DO NOT* observe cohorts.
 Below is an example of how cohorts can be preserved if one so wishes.
 

doc/modules/ROOT/pages/examples.adoc

@@ -49,8 +49,10 @@ decimal32_t value (a): 5.2
 decimal64_t value (b): 3.9
 a is greater than b
 5.2 is less than 1e+385
-1e+385 is now less than inf
+1e+385 is less than inf
 The result of a + b is a decimal64_t: 9.1
+The result of 2*c is a decimal64_t: 18.2
+18.2 is greater than 5
 ....
 ====
 

examples/promotion.cpp

@@ -57,5 +57,20 @@ int main()
     static_assert(std::is_same<c_type, decimal64_t>::value, "decimal32_t + decimal64_t is supposed to yield decimal64_t");
     std::cout << "The result of a + b is a decimal64_t: " << c << '\n';
 
-    return 0;
+    // Now we can look at similar promotion that occurs when an operation is performed between
+    // a decimal type and an integer
+    //
+    // Similar to the above when we have mixed operations like +, -, *, / we always promote to the decimal type
+    // Example: decimal64_t * int -> decimal64_t
+
+    const auto d {2 * c};
+    using d_type = std::remove_cv_t<decltype(d)>;
+    static_assert(std::is_same<d_type, decimal64_t>::value, "decimal64_t * integer is supposed to yield decimal64_t");
+    std::cout << "The result of 2 * c is a decimal64_t: " << d << '\n';
+
+    // The full suite of comparison operators between decimal types and integers
+    if (d > 5)
+    {
+        std::cout << d << " is greater than 5" << '\n';
+    }
 }