Merge pull request #1160 from cppalliance/1153

Add cohort preserving `from_chars`

Author: mborland

doc/modules/ROOT/pages/charconv.adoc

@@ -1,5 +1,5 @@
 ////
-Copyright 2024 Matt Borland
+Copyright 2024 - 2025 Matt Borland
 Distributed under the Boost Software License, Version 1.0.
 https://www.boost.org/LICENSE_1_0.txt
 ////
@@ -21,16 +21,22 @@ namespace decimal {
 
 enum class chars_format : unsigned
 {
-    scientific = 1 << 0,
-    fixed = 1 << 1,
-    hex = 1 << 2,
+    scientific,
+    fixed,
+    hex,
+    cohort_preserving_scientific,
     general = fixed | scientific
 };
 
 } //namespace decimal
 } //namespace boost
 ----
 
+The one difference here between `<charconv>` and what we provide is the option `cohort_preserving_scientific`.
+This format is allowed in both `from_chars` and `to_chars` in specially defined ways to allow for cohorts to be preserved during the conversion process.
+
+IMPORTANT: When using `from_chars` or `to_chars` with fast types it is invalid to specify the format `cohort_preserving_scientific` as these types have no support for cohorts.
+
 [#from_chars_result]
 == from_chars_result
 [source, c++]
@@ -106,6 +112,9 @@ constexpr std::from_chars_result from_chars(const char* first, const char* last,
 } //namespace boost
 ----
 
+When using the format `cohort_preserving_scientific` the number of digits in the string to be converted must not exceed the precision of the type that it is being converted to.
+For example: `4.99999999999e+03` is invalid if being converted to `decimal32_t` because it is not exactly representable in the type.
+
 IMPORTANT: If `std::chars_format` is used the function will return a `std::from_chars_result` and if `boost::decimal::chars_format` is used *OR* no format is specified then a `boost::decimal::from_chars_result` will be returned.
 
 [#to_chars]
@@ -140,7 +149,10 @@ constexpr std::to_chars_result to_chars(char* first, char* last, DecimalType val
 } //namespace boost
 ----
 
-All `to_chars` functions ignore the effects of cohorts, and instead output normalized values.
+All `to_chars` functions, except for when using the format `cohort_preserving_scientific`, ignore the effects of cohorts, and instead output normalized values.
+Additionally, when using the format `cohort_preserving_scientific` if a precision is specified the function will return `{first, std::errc::invalid_argument}`.
+Per IEEE 754 specifying both a precision and cohort preservation is an invalid operation.
+This follows because you are potentially rounding the number, or adding trailing zeros to the fraction which both destroy the cohort information.
 
 IMPORTANT: Same as `from_chars`, `boost::decimal::to_chars` will return a `std::to_chars_result` if `std::chars_format` is used to specify the format; otherwise it returns a `boost::decimal::to_chars_result`.
 

doc/modules/ROOT/pages/design.adoc

@@ -66,6 +66,11 @@ This behavior is the same as that of https://www.boost.org/doc/libs/master/libs/
 The pass:[C++] specification states that `from_chars` resulting value is to be rounded to nearest.
 Since the types in this library are more sensitive to rounding mode differences, `from_chars` rounds using the current global rounding mode as reported by `fegetround()`.
 
+=== `from_chars` and `to_chars` both have an additional `chars_format` option
+
+In order to support an IEEE 754 requirement to print a value to include its cohort information we introduced an additional `chars_format` option, `cohort_preserving_scientific`.
+Cohort preservation only makes sense in scientific format because it is the actual representation of the layout of the type, and thus no other cohort preserving formats are supported.
+
 [#non-finite-deviation]
 === `istream` of Non-finite Values is Allowed
 

examples/charconv_cohort_preservation.cpp

@@ -0,0 +1,107 @@
+// Copyright 2025 Matt Borland
+// Distributed under the Boost Software License, Version 1.0.
+// https://www.boost.org/LICENSE_1_0.txt
+
+#include <boost/decimal.hpp>
+#include <iostream>
+#include <array>
+#include <cstring>
+#include <string>
+
+static constexpr std::size_t N {7};
+
+// All the following decimal values will compare equal,
+// but since they have different numbers of 0s in the significand they will not be bitwise equal
+constexpr std::array<boost::decimal::decimal32_t, N> decimals = {
+    boost::decimal::decimal32_t{3, 2},
+    boost::decimal::decimal32_t{30, 1},
+    boost::decimal::decimal32_t{300, 0},
+    boost::decimal::decimal32_t{3000, -1},
+    boost::decimal::decimal32_t{30000, -2},
+    boost::decimal::decimal32_t{300000, -3},
+    boost::decimal::decimal32_t{3000000, -4},
+};
+
+// These strings represent the same values as the constructed ones shown above
+constexpr std::array<const char*, N> strings = {
+    "3e+02",
+    "3.0e+02",
+    "3.00e+02",
+    "3.000e+02",
+    "3.0000e+02",
+    "3.00000e+02",
+    "3.000000e+02",
+};
+
+int main()
+{
+    using namespace boost::decimal;
+
+    // In some instances we want to preserve the cohort of our values
+    // In the above strings array all of these values compare equal,
+    // but will NOT be bitwise equal once constructed.
+
+    for (std::size_t i = 0; i < N; ++i)
+    {
+        decimal32_t string_val;
+        const auto r_from = from_chars(strings[i], string_val, chars_format::cohort_preserving_scientific);
+
+        if (!r_from)
+        {
+            // Unexpected failure
+            return 1;
+        }
+
+        for (std::size_t j = 0; j < N; ++j)
+        {
+            // Now that we have constructed a value from string
+            // we can compare it bitwise to all the members of the decimal array
+            // to show the difference between operator== and bitwise equality
+            //
+            // All members of a cohort are supposed to compare equal with operator==,
+            // and likewise will hash equal to
+            std::uint32_t string_val_bits;
+            std::uint32_t constructed_val_bits;
+
+            std::memcpy(&string_val_bits, &string_val, sizeof(string_val_bits));
+            std::memcpy(&constructed_val_bits, &decimals[j], sizeof(constructed_val_bits));
+
+            if (string_val == decimals[j])
+            {
+                std::cout << "Values are equal and ";
+                if (string_val_bits == constructed_val_bits)
+                {
+                    std::cout << "bitwise equal.\n";
+                }
+                else
+                {
+                    std::cout << "NOT bitwise equal.\n";
+                }
+            }
+        }
+
+        // The same chars_format option applies to to_chars which allows us to roundtrip the values
+        char buffer[64] {};
+        const auto r_to = to_chars(buffer, buffer + sizeof(buffer), string_val, chars_format::cohort_preserving_scientific);
+
+        if (!r_to)
+        {
+            // Unexpected failure
+            return 1;
+        }
+
+        *r_to.ptr = '\0'; // charconv does not null terminate per the C++ specification
+
+        if (std::strcmp(strings[i], buffer) == 0)
+        {
+            std::cout << "Successful Roundtrip\n\n";
+        }
+        else
+        {
+            std::cout << "Failed\n\n";
+            return 1;
+        }
+    }
+
+    return 0;
+}

include/boost/decimal/charconv.hpp

@@ -46,13 +46,26 @@ namespace decimal {
 
 namespace detail {
 
+#ifdef _MSC_VER
+#  pragma warning(push)
+#  pragma warning(disable:4127)
+#endif
+
 template <BOOST_DECIMAL_DECIMAL_FLOATING_TYPE TargetDecimalType>
 constexpr auto from_chars_general_impl(const char* first, const char* last, TargetDecimalType& value, const chars_format fmt) noexcept -> from_chars_result
 {
     using significand_type = std::conditional_t<(std::numeric_limits<typename TargetDecimalType::significand_type>::digits >
                                                  std::numeric_limits<std::uint64_t>::digits),
                                                  int128::uint128_t, std::uint64_t>;
 
+    BOOST_DECIMAL_IF_CONSTEXPR (is_fast_type_v<TargetDecimalType>)
+    {
+        if (fmt == chars_format::cohort_preserving_scientific)
+        {
+            return {first, std::errc::invalid_argument};
+        }
+    }
+
     if (BOOST_DECIMAL_UNLIKELY(first >= last))
     {
         return {first, std::errc::invalid_argument};
@@ -93,12 +106,29 @@ constexpr auto from_chars_general_impl(const char* first, const char* last, Targ
     }
     else
     {
+        BOOST_DECIMAL_IF_CONSTEXPR (!is_fast_type_v<TargetDecimalType>)
+        {
+            if (fmt == chars_format::cohort_preserving_scientific)
+            {
+                const auto sig_digs {detail::num_digits(significand)};
+                if (sig_digs > precision_v<TargetDecimalType>)
+                {
+                    // If we are parsing more digits than are representable there's no concept of cohorts
+                    return {last, std::errc::value_too_large};
+                }
+            }
+        }
+
         value = TargetDecimalType(significand, expval, sign);
     }
 
     return r;
 }
 
+#ifdef _MSC_VER
+#  pragma warning(pop)
+#endif
+
 } //namespace detail
 
 template <BOOST_DECIMAL_DECIMAL_FLOATING_TYPE TargetDecimalType>
@@ -1217,11 +1247,6 @@ constexpr auto to_chars_impl(char* first, char* last, const TargetDecimalType& v
             case chars_format::hex:
                 return to_chars_hex_impl(first, last, value);
             case chars_format::cohort_preserving_scientific:
-                BOOST_DECIMAL_IF_CONSTEXPR (detail::is_fast_type_v<TargetDecimalType>)
-                {
-                    // Fast types have no concept of cohorts
-                    return {last, std::errc::invalid_argument};
-                }
 
                 if (local_precision != -1)
                 {
@@ -1244,17 +1269,16 @@ constexpr auto to_chars_impl(char* first, char* last, const TargetDecimalType& v
             return to_chars_fixed_impl(first, last, value, fmt, local_precision);
         }
 
-        if (fmt == chars_format::fixed)
-        {
-            return to_chars_fixed_impl(first, last, value, fmt, local_precision);
-        }
-        else if (fmt == chars_format::hex)
-        {
-            return to_chars_hex_impl(first, last, value, local_precision);
-        }
-        else
+        switch (fmt)
         {
-            return to_chars_scientific_impl(first, last, value, fmt, local_precision);
+            case chars_format::fixed:
+                return to_chars_fixed_impl(first, last, value, fmt, local_precision);
+            case chars_format::hex:
+                return to_chars_hex_impl(first, last, value, local_precision);
+            case chars_format::cohort_preserving_scientific:
+                return {last, std::errc::invalid_argument};
+            default:
+                return to_chars_scientific_impl(first, last, value, fmt, local_precision);
         }
     }
 

include/boost/decimal/detail/parser.hpp

@@ -73,7 +73,7 @@ constexpr auto from_chars_dispatch(const char* first, const char* last, builtin_
 
 #if !defined(BOOST_DECIMAL_DISABLE_CLIB)
 template <typename Unsigned_Integer, typename Integer>
-constexpr auto parser(const char* first, const char* last, bool& sign, Unsigned_Integer& significand, Integer& exponent, chars_format fmt = chars_format::general) noexcept -> from_chars_result
+constexpr auto parser(const char* first, const char* last, bool& sign, Unsigned_Integer& significand, Integer& exponent, const chars_format fmt = chars_format::general) noexcept -> from_chars_result
 {
     if (first >= last)
     {
@@ -225,15 +225,15 @@ constexpr auto parser(const char* first, const char* last, bool& sign, Unsigned_
     if (next == last)
     {
         // if fmt is chars_format::scientific the e is required
-        if (fmt == chars_format::scientific)
+        if (fmt == chars_format::scientific || fmt == chars_format::cohort_preserving_scientific)
         {
             return {first, std::errc::invalid_argument};
         }
 
         exponent = 0;
         std::size_t offset = i;
 
-        from_chars_result r = from_chars_dispatch(significand_buffer, significand_buffer + offset, significand, base);
+        const from_chars_result r {from_chars_dispatch(significand_buffer, significand_buffer + offset, significand, base)};
         switch (r.ec)
         {
             // The two invalid cases are here for completeness, but I don't think we can actually hit them
@@ -304,7 +304,7 @@ constexpr auto parser(const char* first, const char* last, bool& sign, Unsigned_
 
     if (next == last || is_delimiter(*next, fmt))
     {
-        if (fmt == chars_format::scientific)
+        if (fmt == chars_format::scientific || fmt == chars_format::cohort_preserving_scientific)
         {
             return {first, std::errc::invalid_argument};
         }
@@ -319,7 +319,7 @@ constexpr auto parser(const char* first, const char* last, bool& sign, Unsigned_
         }
         std::size_t offset = i;
 
-        from_chars_result r = from_chars_dispatch(significand_buffer, significand_buffer + offset, significand, base);
+        const from_chars_result r {from_chars_dispatch(significand_buffer, significand_buffer + offset, significand, base)};
         switch (r.ec)
         {
             // Out of range included for completeness, but I don't think we can actually reach it

test/Jamfile

@@ -112,6 +112,7 @@ run test_bid_conversions.cpp ;
 run test_big_uints.cpp ;
 run test_boost_math_univariate_stats.cpp ;
 run test_cbrt.cpp ;
+run test_charconv_preservation.cpp ;
 run test_cmath.cpp ;
 run test_constants.cpp ;
 run test_constexpr_rounding_mode.cpp ;
@@ -181,7 +182,6 @@ run test_tan.cpp ;
 run test_tanh.cpp ;
 run test_tgamma.cpp ;
 run test_to_chars.cpp ;
-run test_to_chars_quantum.cpp ;
 run test_to_string.cpp ;
 run test_zeta.cpp ;
 
@@ -190,6 +190,7 @@ run ../examples/adl.cpp ;
 run ../examples/basic_construction.cpp ;
 run ../examples/bit_conversions.cpp ;
 run ../examples/charconv.cpp ;
+run ../examples/charconv_cohort_preservation.cpp ;
 run ../examples/literals.cpp ;
 run ../examples/rounding_mode.cpp ;
 run ../examples/rounding_mode_compile_time.cpp ;