diff --git a/doc/modules/ROOT/nav.adoc b/doc/modules/ROOT/nav.adoc index c91dac97d..ebf2d17f9 100644 --- a/doc/modules/ROOT/nav.adoc +++ b/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[] diff --git a/doc/modules/ROOT/pages/basics.adoc b/doc/modules/ROOT/pages/basics.adoc index 188924cfe..77e1d23ab 100644 --- a/doc/modules/ROOT/pages/basics.adoc +++ b/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 ``. 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++] diff --git a/doc/modules/ROOT/pages/binary_floating_conversions.adoc b/doc/modules/ROOT/pages/binary_floating_conversions.adoc new file mode 100644 index 000000000..ca35d16bf --- /dev/null +++ b/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 + explicit decimal32_t(Float x) noexcept; + + template + 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. diff --git a/doc/modules/ROOT/pages/design.adoc b/doc/modules/ROOT/pages/design.adoc index 68c49640f..a7465dd75 100644 --- a/doc/modules/ROOT/pages/design.adoc +++ b/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 === `` Functions Do Not Meet the Definition of Correctly Rounded