Merge pull request #177 from BoostGSoC21/qbook_docs

Fix #165 via add quickbook docs

doc/multiprecision.qbk

@@ -1,7 +1,8 @@
 [/
-  Copyright 2011 - 2020 John Maddock.
+  Copyright 2011 - 2024 John Maddock.
   Copyright 2013 - 2019 Paul A. Bristow.
-  Copyright 2013 Christopher Kormanyos.
+  Copyright 2013 - 2024 Christopher Kormanyos.
+  Copyright 2021 - 2024 Fahad Syed.
 
   Distributed under the Boost Software License, Version 1.0.
   (See accompanying file LICENSE_1_0.txt or copy at

doc/reference.qbk

@@ -1,7 +1,7 @@
 [/
-  Copyright 2011 - 2020 John Maddock.
+  Copyright 2011 - 2024 John Maddock.
   Copyright 2013 - 2019 Paul A. Bristow.
-  Copyright 2013 Christopher Kormanyos.
+  Copyright 2013 - 2024 Christopher Kormanyos.
 
   Distributed under the Boost Software License, Version 1.0.
   (See accompanying file LICENSE_1_0.txt or copy at
@@ -18,6 +18,7 @@
 [include reference_mpfr_float.qbk]
 [include reference_cpp_bin_float.qbk]
 [include reference_cpp_dec_float.qbk]
+[include reference_cpp_double_fp_backend.qbk]
 [include reference_internal_support.qbk]
 [include reference_backend_requirements.qbk]
 [include reference_header_structure.qbk]

doc/reference_cpp_double_fp_backend.qbk

@@ -0,0 +1,44 @@
+[/
+  Copyright 2021 - 2024 Fahad Syed.
+  Copyright 2024 Christopher Kormanyos.
+
+  Distributed under the Boost Software License, Version 1.0.
+  (See accompanying file LICENSE_1_0.txt or copy at
+  http://www.boost.org/LICENSE_1_0.txt).
+]
+
+[section:cpp_double_fp_ref cpp_double_fp_backend]
+
+   namespace boost{ namespace multiprecision {
+
+   template <class FloatingPointType>
+   class cpp_double_fp_backend;
+
+   typedef number<cpp_double_fp_backend<float>, et_off> cpp_double_float;
+   typedef number<cpp_double_fp_backend<double>, et_off> cpp_double_double;
+   typedef number<cpp_double_fp_backend<long double>, et_off> cpp_double_long_double;
+   typedef number<cpp_double_fp_backend<boost::float128_type>, et_off> cpp_double_float128; // Only when boost::float128_type is available
+
+   }} // namespaces
+
+The `cpp_double_fp_backend` back-end is the sum of two IEEE floating-point numbers
+combined to create a type having rougly twice the composite width of one of its parts.
+The `cpp_double_fp_backend` back-end is used in conjunction with `number`
+and acts as an entirely C++ header only floating-point number type.
+
+Class template `cpp_double_fp_backend` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type.
+Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject
+to change.
+
+The class takes one template parameter:
+
+[variablelist
+[[FloatingPointType][The consituent IEEE floating-point value of the two limbs of the composite type.
+This can be `float`, `double`, `long double` or when available `boost::float128_type`.]]
+]
+
+The type of `number_category<cpp_dec_float<Args...> >::type` is `std::integral_constant<int, number_kind_floating_point>`.
+
+More information on this type can be found in the [link boost_multiprecision.tut.floats.cpp_double_fp_backend tutorial].
+
+[endsect]

doc/tutorial.qbk

@@ -1,7 +1,7 @@
 [/
-  Copyright 2011 - 2020 John Maddock.
+  Copyright 2011 - 2024 John Maddock.
   Copyright 2013 - 2019 Paul A. Bristow.
-  Copyright 2013 Christopher Kormanyos.
+  Copyright 2013 - 2024 Christopher Kormanyos.
 
   Distributed under the Boost Software License, Version 1.0.
   (See accompanying file LICENSE_1_0.txt or copy at

doc/tutorial_cpp_double_fp_backend.qbk

@@ -0,0 +1,76 @@
+[/
+  Copyright 2021 - 2024 Fahad Syed.
+  Copyright 2024 Christopher Kormanyos.
+
+  Distributed under the Boost Software License, Version 1.0.
+  (See accompanying file LICENSE_1_0.txt or copy at
+  http://www.boost.org/LICENSE_1_0.txt).
+]
+
+[section:cpp_double_fp_backend cpp_double_fp_backend]
+
+`#include <boost/multiprecision/cpp_double_fp_backend.hpp>`
+
+   namespace boost{ namespace multiprecision {
+
+   template <class FloatingPointType>
+   class cpp_double_fp_backend;
+
+   typedef number<cpp_double_fp_backend<float>, et_off> cpp_double_float;
+   typedef number<cpp_double_fp_backend<double>, et_off> cpp_double_double;
+   typedef number<cpp_double_fp_backend<long double>, et_off> cpp_double_long_double;
+   typedef number<cpp_double_fp_backend<boost::float128_type>, et_off> cpp_double_float128; // Only when boost::float128_type is available
+
+   }} // namespaces
+
+The `cpp_double_fp_backend` back-end is the sum of two IEEE floating-point numbers
+combined to create a type having rougly twice the composite width of one of its parts.
+The `cpp_double_fp_backend` back-end is used in conjunction with `number`
+and acts as an entirely C++ header only floating-point number type.
+
+The `cpp_double_fp_backend` types have fixed width and do not allocate.
+The type `cpp_double_double`, for instance, (composed of two double-precision IEEE floating-point numebers)
+has (on most common systems) 106 binary digits of precision and approximately
+32 decimal digits of precision.
+
+The exponent ranges of the types are slightly limited (on the negative side) compared to those of the composite type.
+Consider again the type `cpp_double_double`, composed of two double-precision IEEE double-precision
+floating-point numebers. On common systems, this type has a maximum decimal exponent of 308
+(as does a single double-precision floating point number). The negative minimum exponent, however,
+is about -291, which is less range than the -3�7 from standalone double. The reason for
+the limitation is because the composite lower-limb has lower value than its upper limb and would
+underflow or become subnormal if the upper limb had its usual minimum value.
+
+There is full standard library and `std::numeric_limits` support available for this type.
+
+Note that the availability of `cpp_double_float128` depends on the availability
+of `boost::float128_type`, which can be queried at compile-time via the
+configuration macro `BOOST_HAS_FLOAT128`. This is available at the moment
+predominantly with GCC compilers in GNU-standard mode and (with GCC 14 and later)
+also in strict ANSI mode.
+
+Run-time performance is a top-level requirement for the `cpp_double_fp_backend` types.
+The types still do, however, support infinities, NaNs and (of course) zeros.
+Signed negative zero, however, is not supported (in favor of efficiency)
+and all zeros are treated as positive.
+
+The `cpp_double_fp_backend` types inoteroperate with Boost.Math and Boost.Math.Constants.
+This offers the wealth of Boost-related mathematical tools instantiated with
+the `cpp_double_fp_backend` types.
+
+Things you should know when using the `cpp_double_fp_backend` types:
+
+* Although the types are created from two individual IEEE floating-point components, they specifically and clearly not in their composite forms also IEEE types.
+* As a result these types can behave subtly differently from IEEE floating-point types.
+* There is a `std::numeric_limits` specialization for this type.
+* Conversion to and from string internally uses an  intermediate `cpp_dec_float` value.
+
+The `cpp_double_fp_backend` back-end has been inspired by original works and types such as the historical `doubledouble`
+and more. These include the following:
+
+* K. Briggs, the doubledouble library, 1998.
+* Yozo Hida, X. Li, and D. H. Bailey, Quad-Double Arithmetic: Algorithms, Implementation, and Application, Lawrence Berkeley National Laboratory Technical Report LBNL-46996 (2000). Also Y. Hida et al., Library for double-double and quad-double arithmetic [@https://web.mit.edu/tabbott/Public/quaddouble-debian/qd-2.3.4-old/docs/qd.pdf].
+* Mioara Maria Joldes, Jean-Michel Muller, Valentina Popescu. Tight and rigorous error bounds for basic building blocks of double-word arithmetic. ACM Transactions on Mathematical Software, 2017, 44 (2), pp. 1 - 27. ff10.1145/3121432ff. ffhal-01351529v3f.
+* The `cpp_double_fp_backend` draft was originally created by Fahad Syed in BoostGSoC2021 _multiprecision_ [@https://github.com/BoostGSoC21/multiprecision].
+
+[endsect]

doc/tutorial_floats.qbk

@@ -1,7 +1,7 @@
 [/
-  Copyright 2011 - 2020 John Maddock.
+  Copyright 2011 - 2024 John Maddock.
   Copyright 2013 - 2019 Paul A. Bristow.
-  Copyright 2013 Christopher Kormanyos.
+  Copyright 2013 - 2024 Christopher Kormanyos.
 
   Distributed under the Boost Software License, Version 1.0.
   (See accompanying file LICENSE_1_0.txt or copy at
@@ -19,13 +19,15 @@ The following back-ends provide floating-point arithmetic:
 [[`mpf_float<N>`][boost/multiprecision/gmp.hpp][2][[gmp]][Very fast and efficient back-end.][Dependency on GNU licensed [gmp] library.]]
 [[`mpfr_float<N>`][boost/multiprecision/mpfr.hpp][2][[gmp] and [mpfr]][Very fast and efficient back-end, with its own standard library implementation.][Dependency on GNU licensed [gmp] and [mpfr] libraries.]]
 [[`float128`][boost/multiprecision/float128.hpp][2][Either [quadmath] or the Intel C++ Math library.][Very fast and efficient back-end for 128-bit floating-point values (113-bit mantissa, equivalent to FORTRAN's QUAD real)][Depends on the compiler being either recent GCC or Intel C++ versions.]]
+[[`cpp_double_fp_backend<T>`][boost/multiprecision/cpp_double_fp_backend.hpp][2][None][Header only, all C++ implementation. Boost licence.][Approximately 2x double-`float`, `double`, `long double` or `boost::float128_type` designed for lower-precision, higher run-time performance.]]
 ]
 
 [include tutorial_cpp_bin_float.qbk]
 [include tutorial_cpp_dec_float.qbk]
 [include tutorial_gmp_float.qbk]
 [include tutorial_mpfr_float.qbk]
 [include tutorial_float128.qbk]
+[include tutorial_cpp_double_fp_backend.qbk]
 [include tutorial_float_eg.qbk]
 
 [endsect] [/section:floats floating-point Numbers]