[Boost-commit] svn:boost r83530 - sandbox/precision/libs/precision/doc

Subject: [Boost-commit] svn:boost r83530 - sandbox/precision/libs/precision/doc
From: e_float_at_[hidden]
Date: 2013-03-23 12:12:31

Author: christopher_kormanyos
Date: 2013-03-23 12:12:31 EDT (Sat, 23 Mar 2013)
New Revision: 83530
URL: http://svn.boost.org/trac/boost/changeset/83530

Log:
Significant rework of several sections in precision.qbk. Also check in the final "chris" version prior to its removal.
Text files modified: 
   sandbox/precision/libs/precision/doc/precision.qbk       |   171 +++++++++++++++++++++++++++------------ 
   sandbox/precision/libs/precision/doc/precision_chris.qbk |    10 +                                       
   2 files changed, 124 insertions(+), 57 deletions(-)

Modified: sandbox/precision/libs/precision/doc/precision.qbk
==============================================================================
--- sandbox/precision/libs/precision/doc/precision.qbk	(original)
+++ sandbox/precision/libs/precision/doc/precision.qbk	2013-03-23 12:12:31 EDT (Sat, 23 Mar 2013)
@@ -58,18 +58,32 @@
 
 [section:abstract  Abstract]
 
-It is proposed to add several optional typedefs with specified widths
-for floating-point types including `float32_t, float64_t _float128_t` (similar to `int64_t` for integer types).
+It is proposed to add several optional typedefs for floating-point types
+with specified widths. In particular, there are
+`float16_t`, `float32_t`, `float64_t`, `float128_t`, and their
+corresponding fast and least types. These floating-point types
+must conform with the corresponding types
+`binary16`, `binary32`, `binary64`, and `binary128`
+specified in __IEEE_floating_point.
+
+The new floating-point types with specified widths should improve
+clarity of code and portability of floating-point calculations.
+Analogous improvements for integer calculations were recently
+standardized with integer types having specified width
+such as `int8_t`, `int16_t`, `int32_t`, and `int64_t`.
+
+The proposed new floating-point with specified widths
+will be defined in the global and `std` namespaces.
+
+It is also proposed to provide additional suffix(es) to specify
+constants to suit precision lower than that of `float` and
+precision higher than that of `long double`.
 
-These will be defined in the global and `std` namespaces.
+The main objectives of this proposal are to:
 
-And also to provide additional suffix(es) to specify extended precision constants to suit precisions
-lower than that of `float` higher than that of `long double`.
-
-The objectives are to:
-
-* Make it easier to use higher-precision.
+* Extend the range of floating-point precision.
 * Reduce errors in precision.
+* Improve clarity of coding.
 * Improve portability, reliability and safety.
 
 [endsect] [/section:abstract  Abstract]
@@ -77,8 +91,10 @@
 [section:background Background]
 
 C++11 supports floating-point calculations with its built-in types
-`float`, `double`, and `long double` as well as implementations of
+`float`, `double`, and `long double` as well as imlementations of
 numerous elementary and transcendental functions.
+Support for mathematical facilities and specialized number types
+in C++ is progressing rapidly.
 
 A variety of higher transcendental functions of pure and applied mathematics
 were added to the C++11 libraries via technical report TR1.
@@ -94,10 +110,13 @@
 
 The __Boost_Math library was accepted into __Boost several years ago.  It implements many of the functions in both documents mentioned above and has become quite widely used.
 
-With the acceptance and release of __Boost_Multiprecision
-that provides much higher precision than built-in `long double` with
-__cpp_dec_float employing a variety of backends including the well-established __GMP and __MPFR libraries
-as well as a full open-license backend developed
+There is also progress in C++ in the area of multiprecision floating-point.
+In particular, the acceptance and release of __Boost_Multiprecision
+provides much higher precision than built-in `long double` with
+__cpp_dec_float. __Boost_Multiprecision employs a variety of backends
+to implement multiprecision floating-point types
+including the well-established __GMP and __MPFR libraries
+as well as a full open-license backend that originates
 from the __e_float library by Christopher Kormanyos and John Maddock.
 
 Since __Boost_Multiprecision and __Boost_Math work seamlessly, allowing a `float_type typedef` to be switched from a built-in type to hundreds of decimal digits; then all the special functions and distributions can be used at any chosen precision.
@@ -106,7 +125,10 @@
 [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3407.html decimal] and
 [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3352.html binary fixed-point].
 
-Of course, moving away from hardware supported types to software using C++ templates carries a small price at compile-time, and a much bigger price at runtime.
+Of course, moving away from hardware supported types to software using C++ templates
+carries a small price at compile-time, and potentially a much bigger price at runtime.
+Nonetheless, the new numerical types have large ranges of application and
+are required in numerous programming domains.
 
 All these development have made C++ much more attractive to the scientific and engeering community,
 especially those needing higher (or lower) precision for some (if not all) of the calculations,
@@ -133,8 +155,8 @@
 to simplify and improve efficiency of floating-point implementations
 on cost-sensitive architectures such as small microcontrollers.
 The extension to higher precision is useful for large-scale high-performance
-numerical calculations and should ease the progression to extended precision
-by providing precision-steps with finer granularity.
+numerical calculations and should ease the progression to multiprecision
+by providing built-in types with progressing precision of finer granularity.
 
 All of these improvements should improve portability, reliability, and safety
 of floating-point calculations in C++ by ensuring that the actual precision
@@ -187,34 +209,68 @@
 
 [endsect] [/section:introduction Introduction]
 
-[section:suffixes  How to specify constants with quad and half precision?]
+[section:thetypes  The proposed types and potential extensions]
 
-Recent discussion on extended precision floating-point types in C++ has also
-raised the issue of how to specify constant values with a precision greater than `long double`,
-now signified by the suffix `L`.
-
-One obvious way is to add `Q` or `q` suffixes to signify that a constant has at least 128-bits (about 40 decimal digits) of precision.
+The core of this proposal is based on the types `float16_t`, `float32_t`,
+`float64_t`, and `float128_t`. These are floating-point types with
+specified widths. These floating-point types are to conform with the
+corresponding types `binary16`, `binary32`, `binary64`, and `binary128`
+specified in __IEEE_floating_point.
+
+In particular, `float16_t`, `float32_t`, `float64_t`, and `float128_t`
+correspond to floating-point types with 11, 24, 53, and 113 binary significand digits,
+respectively. These are defined in __IEEE_floating_point, and there are more detailed descrptions
+of each type at __IEEE_Half, __IEEE_Single, __IEEE_Double, __IEEE_Quad, and __IEEE_Extended.
+
+There may be a need for octuple-precision float, in other words
+`float256_t` with about 240 binary significand digits of precision.
+In addition, a `float512_t` type with even more precision
+may be considered as a option. Beyond these, there may be
+potential extension to multiprecision types in the future.
+
+The popular [@http://gcc.gnu.org/wiki/x87note Intel X8087 chipset]
+architecture supports a 10-byte floating-point format.
+So it may be useful to provide optional support for `float80_t`.
+There is no analogous type in __IEEE_floating_point.
+
+At present, the only way to provide a literal constant value with precision exceeding
+the precision of `long double` is to use a string in association with
+extended-precision type conversion.
+For example, the `from_string` method is used for this purpose in
+__Boost_Math, __Boost_Multiprecision and __libquadmath.
+
+Along these lines, the herein proposed floating-point types with specified widths
+should be copy assignable and copy constructable from string literal constants.
+This may require slight changes to the core language such as inclusion
+of new suffixes, as described below.
+
+It would also be useful to have a method of querying the size of types,
+similar to that provided by
+[@http://gcc.gnu.org/onlinedocs/cpp/Common-Predefined-Macros.html GCC 3.7.2 Common Predefined Macros],
+for example, `__SIZEOF_LONG_DOUBLE__`.
+But similar macros are not defined for `__float128` nor for `__float80`.
 
-There may also be a need for 256-bit (about 80 decimal digits) precision, and perhaps 512-bits (about 155 decimal digits) precision.
+[endsect] [/section:thetypes The proposed types and potential extensions]
 
-At present, the only way to provide constant values is to use a string to extended-precision type conversion.
+[section:suffixes  How to specify constants with quad and half precision?]
 
-This `from_string` method is used for __Boost_Math, __Boost_Multiprecision and __libquadmath, for example.
+The standard specifies that the type of a floating literal is double unless
+explicitly specified by a suffix. The standard continues by specifying that
+the suffixes `f` and `F` specify `float`, the suffixes `l` and `L` specify `long double`.
 
-It would also be useful to have a method of interrogating the size of types, similar to that provided by
-[@http://gcc.gnu.org/onlinedocs/cpp/Common-Predefined-Macros.html GCC 3.7.2 Common Predefined Macros], for example,
-`__SIZEOF_LONG_DOUBLE__`
-(but is not defined for `__float128` nor `__float80`)
+Recent discussion on extended precision floating-point types in C++ has also
+raised the issue of how to specify constant values with a precision greater than `long double`,
+now signified by the suffix `L` or `l`.
 
-We refer to floating-point types with fixed
-precision such as 24, 53, 113 or more binary significand digits,
-(and possibly even extending beyond these to potential multiprecision types).
+One possible way is to add `Q` or `q` suffixes to signify that a constant
+This specifies quadruple precision.
 
-These are defined in __IEEE754.
+The half-precision suffix could be `H` or `h`.
 
-There are detailed descriptions at __IEEE_floating_point, with more detailed descrptions of each type at __IEEE_Half, __IEEE_Single, __IEEE_Double, __IEEE_Quad, and __IEEE_Extended and these correspond to the proposed types below `float16_t` ....
+The octuple-precision suffix could be `O` or `o`.
 
-TBD by Chris: Suffix for half-precision.
+Higher precisions may require construction from string literals, as the list of
+available suffixes dwindles and the myriad of suffixes may become confusing.
 
 [endsect] [/section:suffixes  How to specify constants with quad and half precision?]
 
@@ -226,11 +282,12 @@
 * `float32_t, float64_t, float128_t, ...`
 
 The first set above is intuitively coined from [@http://dx.doi.org/10.1109/IEEESTD.2008.4610935 IEE754:2008].
-It is also consistent with the gist of `std::uint32_t`, et al
-in so far as the number of binary digits of ['significand] precision
+It is also consistent with the gist of integer types with specified precision
+such as `uint32_t`, in so far as the number of binary digits of ['significand] precision
 is contained within the name of the data type.
 
-On the other hand, the second set using the size of the ['whole type] may probably seem more intuitive to users.
+On the other hand, the second set with the size of the ['whole type] contained within
+the name may be more intuitive to users.
 The exact layout and number of significand and exponent bits can be confirmed as IEEE754 by checking
 `std::numeric_limits<type>::is_iec559 == true`.
 
@@ -284,7 +341,7 @@
 
   namespace std
   {
-    typedef signed integer type int8_t; // optional
+    typedef signed integer type int8_t;  // optional
     typedef signed integer type int16_t; // optional
     typedef signed integer type int32_t; // optional
     typedef signed integer type int64_t; // optional
@@ -303,12 +360,12 @@
 18.4.2? Header <cstdfloat> synopsis [cstdfloat.syn]
 
   namespace std {
-    typedef signed floating-point type float_16_t;  // optional.
-    typedef signed floating-point type float_32_t;  // optional.
-    typedef signed floating-point type float_64_t;  // optional.
-    typedef signed floating-point type float_80_t;  // optional.
-    typedef signed floating-point type float_128_t; // optional.
-    typedef signed floating-point type float_256_t; // optional.
+    typedef signed floating-point type float16_t;   // optional.
+    typedef signed floating-point type float32_t;   // optional.
+    typedef signed floating-point type float64_t;   // optional.
+    typedef signed floating-point type float80_t;   // optional.
+    typedef signed floating-point type float128_t;  // optional.
+    typedef signed floating-point type float256_t;  // optional.
     typedef signed floating-point type floatmax_t;  // optional.
 
     typedef signed floating-point type float_least16_t;  // optional.
@@ -328,13 +385,21 @@
 
 It is not proposed to make any change to `std::numeric_limits`.
 
-It is obviously highly desirable that `std::numeric_limits` is specialized for all floating-point types.
-And experience with __Boost_Math and __Boost_Multiprecision is that the normal set of trig and others useful functions is also essential to make the type useful in real-life.
-
-
-
-
-Programs can then use this to determine if a floating-point type is IEEE 754 using `std::numeric_limits<>::is_iec559`.
+It is, nonethelsee, mandatory that `std::numeric_limits` is specialized
+for all floating-point types. Thus their must be explicit template
+specializations for all of the optional floating-point types with
+specified precision that are included in the implementation.
+This will ensure that programs can use the established
+`std::numeric_limits<>::is_iec559` member to determine
+if a floating-point type conforms with __IEEE_floating_point.
+
+Experience with __Boost_Math and __Boost_Multiprecision has shown that the normal set
+of elementary and transcendental functions (and possibly additional higher transcendental functions)
+is also essential to make the type useful in real-life computational regimes.
+Therefore, the implementation must provide support for the mathematical
+functions in the `std` namespace (TBD: Chris list functions)
+for each of the floating-point types with specified precision
+included in the implementation.
 
 [endsect] [/section:new Proposed new section]
 [endsect] [/section:precision Specifying Precision]

Modified: sandbox/precision/libs/precision/doc/precision_chris.qbk
==============================================================================
--- sandbox/precision/libs/precision/doc/precision_chris.qbk	(original)
+++ sandbox/precision/libs/precision/doc/precision_chris.qbk	2013-03-23 12:12:31 EDT (Sat, 23 Mar 2013)
@@ -90,7 +90,7 @@
 `float`, `double`, and `long double` as well as imlementations of
 numerous elementary and transcendental functions.
 Support for mathematical facilities and specialized number types
-in C++ is rapidly developing.
+in C++ is progressing rapidly.
 
 A variety of higher transcendental functions of pure and applied mathematics
 were added to the C++11 libraries via technical report TR1.
@@ -112,7 +112,7 @@
 __cpp_dec_float. __Boost_Multiprecision employs a variety of backends
 to implement multiprecision floating-point types
 including the well-established __GMP and __MPFR libraries
-as well as a full open-license backend originating
+as well as a full open-license backend that originates
 from the __e_float library by Christopher Kormanyos and John Maddock.
 
 Since __Boost_Multiprecision and __Boost_Math work seamlessly, allowing a `float_type typedef` to be switched from a built-in type to hundreds of decimal digits; then all the special functions and distributions can be used at any chosen precision.
@@ -374,7 +374,7 @@
 
 It is not proposed to make any change to `std::numeric_limits`.
 
-It is mandatorye that `std::numeric_limits` is specialized for all floating-point types.
+It is mandatory that `std::numeric_limits` is specialized for all floating-point types.
 This will ensure that programs can use the established `std::numeric_limits<>::is_iec559`
 to determine if a floating-point type conforms with __IEEE_floating_point.
 
@@ -391,7 +391,7 @@
 
 [endsect] [/section:complexinteract Interaction with complex]
 
-[section:microfpu Improvemed safety for microcontrollers with an FPU]
+[section:microfpu Improved safety for microcontrollers with an FPU]
 
 TBD by Chris: Describe recent confidential meetings with tier-one silicon suppliers and the relevant problems discussed therein.
 
@@ -401,6 +401,8 @@
 
 TBD ba Chris: Add an example and remarks on functional safety and any relevant citations from to ISO/IEC 26262.
 
+TBD by Chris - add reference to your book!
+
 [endsect] [/section:microfpu Improvemed safety for microcontrollers with an FPU]