Merge pull request #1249 from cppalliance/1188

Add new page on binary floating point conversions

Author: mborland

doc/modules/ROOT/nav.adoc

@@ -27,6 +27,7 @@
 ** xref:decimal_fast32_t.adoc[]
 ** xref:decimal_fast64_t.adoc[]
 ** xref:decimal_fast128_t.adoc[]
+* xref:binary_floating_conversions.adoc[]
 * xref:cohorts.adoc[]
 * xref:conversions.adoc[]
 * xref:literals.adoc[]

doc/modules/ROOT/pages/basics.adoc

@@ -119,6 +119,7 @@ For more information see: xref:cfenv.adoc[]
 The entire library can be accessed using the convenience header `<boost/decimal.hpp>`.
 A short example of the basic usage:
 
+[#first_example]
 .This https://github.com/cppalliance/decimal/blob/develop/examples/first_example.cpp[example] shows the very basics on how to make a complete and working program using the decimal library
 ====
 [source, c++]

doc/modules/ROOT/pages/binary_floating_conversions.adoc

@@ -0,0 +1,35 @@
+////
+Copyright 2025 Matt Borland
+Distributed under the Boost Software License, Version 1.0.
+https://www.boost.org/LICENSE_1_0.txt
+////
+
+[#bin_float]
+= Conversion from Binary Floating Point
+:idprefix: bin_float_
+
+The library deliberately does not contain any operations between a binary floating point type and the decimal floating point types.
+The rationale is similar to that of the library in the first place in that you may end up with surprising results.
+As shown in our xref:basics.adoc#first_example[first example] `0.1 + 0.2 != 0.3` when using `double`, so you could end up with a decimal value that does not represent exactly what you expect.
+To offer minimal and explicit interoperability with types `float`, `double`, and `long double` each decimal type has an explicit constructor and conversion operator as discussed on the type specific documentation pages like xref:decimal32_t.adoc[`decimal32_t`]:
+
+[source, c++]
+----
+namespace boost {
+namespace decimal {
+
+class decimal32_t
+{
+    template <typename Float>
+    explicit decimal32_t(Float x) noexcept;
+
+    template <typename Float>
+    explicit operator Float() const noexcept;
+};
+
+} // namespace decimal
+} // namespace boost
+----
+
+*No additional support is planned* to deter use of these conversions.
+If you have existing floating point values that need to be converted into decimals it is recommended to write them to string, validate the string, and then utilize the string constructors provided by this library.

doc/modules/ROOT/pages/design.adoc

@@ -20,11 +20,6 @@ This allows Boost.Decimal to better emulate the functionality a built-in type wo
 Boost.Math requires C++14 as the minimum language standard for the library.
 By meeting this requirement, and Boost.Math's conceptual requirements for a user-defined type we are able to provide the statistics, interpolation, quadrature, etc. out of the box.
 
-== No Binary Floating Point Operations
-The library deliberately does not contain any operations between a binary floating point type and the decimal floating point types.
-The rationale is similar to that of the library in the first place in that you may end up with surprising results.
-Conversion operators and constructors are available for all decimal types should the user want to explicit cast one side of the operation to conduct the operation.
-
 == IEEE Deviations
 
 === `<cmath>` Functions Do Not Meet the Definition of Correctly Rounded