Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r83955 - in sandbox/precision/libs/precision/doc: . html html/precision
From: pbristow_at_[hidden]
Date: 2013-04-18 09:33:33

Next message: john_at_[hidden]: "[Boost-commit] svn:boost r83956 - in branches/release/tools/auto_index: . src"
Previous message: john_at_[hidden]: "[Boost-commit] svn:boost r83954 - in branches/release/tools/bcp: . doc doc/html"

Author: pbristow
Date: 2013-04-18 09:33:32 EDT (Thu, 18 Apr 2013)
New Revision: 83955
URL: http://svn.boost.org/trac/boost/changeset/83955

Log:
Update after ISO WG21/SG6 meeting discussions
Binary files modified:
   sandbox/precision/libs/precision/doc/precision.pdf
Text files modified:
   sandbox/precision/libs/precision/doc/html/index.html | 12 ++
   sandbox/precision/libs/precision/doc/html/precision/cmathinterop.html | 2
   sandbox/precision/libs/precision/doc/html/precision/literals.html | 2
   sandbox/precision/libs/precision/doc/html/precision/thestandard.html | 166 +++++++++++++++++++++++++++++++++------
   sandbox/precision/libs/precision/doc/html/precision/version_id.html | 2
   sandbox/precision/libs/precision/doc/precision.qbk | 123 +++++++++++++++++++++++------
   6 files changed, 250 insertions(+), 57 deletions(-)

Modified: sandbox/precision/libs/precision/doc/html/index.html
==============================================================================
--- sandbox/precision/libs/precision/doc/html/index.html (original)
+++ sandbox/precision/libs/precision/doc/html/index.html 2013-04-18 09:33:32 EDT (Thu, 18 Apr 2013)
@@ -52,7 +52,7 @@
<dt><a href="precision/thetypedefs.html">The proposed typedefs and potential
 extensions</a></dt>
<dt>Handling floating-point literals</dt>
-<dt>Place in the standard</dt>
+<dt>Changes to the C and C++ standard</dt>
<dt><a href="precision/cmathinterop.html">Interoperation with <cmath>
 and special functions</a></dt>
<dt>Interoperation with <limits></dt>
@@ -65,14 +65,20 @@
</dl>
</div>

- ISO/IEC JTC1 SC22 WG21/SG6 Numerics N3626 - 2013-04-05
+ ISO/IEC JTC1 SC22 WG21/SG6 Numerics N3626 - 2013-04-18
+ 
+
+ ISO/IEC JTC1 SC22 WG14/ Numerics N1703 - 2013-04-18
+ 
+
+ Revised after WG21/SG6 meeting 18 Apr 2013.
 

 Comments and suggestions to Paul.A.Bristow pbristow_at_hetp.u-net.com.
 
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left">Last revised: April 09, 2013 at 08:52:41 GMT</td>
+<td align="left">Last revised: April 18, 2013 at 13:32:31 GMT</td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>

Modified: sandbox/precision/libs/precision/doc/html/precision/cmathinterop.html
==============================================================================
--- sandbox/precision/libs/precision/doc/html/precision/cmathinterop.html (original)
+++ sandbox/precision/libs/precision/doc/html/precision/cmathinterop.html 2013-04-18 09:33:32 EDT (Thu, 18 Apr 2013)
@@ -6,7 +6,7 @@
<meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
<link rel="home" href="../index.html" title="Floating-Point Typedefs Having Specified Widths - N3626">
<link rel="up" href="../index.html" title="Floating-Point Typedefs Having Specified Widths - N3626">
-<link rel="prev" href="thestandard.html" title="Place in the standard">
+<link rel="prev" href="thestandard.html" title="Changes to the C and C++ standard">
<link rel="next" href="limitsinterop.html" title="Interoperation with <limits>">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">

Modified: sandbox/precision/libs/precision/doc/html/precision/literals.html
==============================================================================
--- sandbox/precision/libs/precision/doc/html/precision/literals.html (original)
+++ sandbox/precision/libs/precision/doc/html/precision/literals.html 2013-04-18 09:33:32 EDT (Thu, 18 Apr 2013)
@@ -7,7 +7,7 @@
<link rel="home" href="../index.html" title="Floating-Point Typedefs Having Specified Widths - N3626">
<link rel="up" href="../index.html" title="Floating-Point Typedefs Having Specified Widths - N3626">
<link rel="prev" href="thetypedefs.html" title="The proposed typedefs and potential extensions">
-<link rel="next" href="thestandard.html" title="Place in the standard">
+<link rel="next" href="thestandard.html" title="Changes to the C and C++ standard">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>

Modified: sandbox/precision/libs/precision/doc/html/precision/thestandard.html
==============================================================================
--- sandbox/precision/libs/precision/doc/html/precision/thestandard.html (original)
+++ sandbox/precision/libs/precision/doc/html/precision/thestandard.html 2013-04-18 09:33:32 EDT (Thu, 18 Apr 2013)
@@ -1,7 +1,7 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
-<title>Place in the standard</title>
+<title>Changes to the C and C++ standard</title>
<link rel="stylesheet" href=".././boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
<link rel="home" href="../index.html" title="Floating-Point Typedefs Having Specified Widths - N3626">
@@ -24,11 +24,12 @@
</div>
<div class="section precision_thestandard">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="precision.thestandard"></a><a class="link" href="thestandard.html" title="Place in the standard">Place in the standard</a>
+<a name="precision.thestandard"></a><a class="link" href="thestandard.html" title="Changes to the C and C++ standard">Changes to the C and C++ standard</a>
</h2></div></div></div>

 The proper place for defining the optional floating-point <code class="computeroutput">typedef</code>s
- having specified widths should be oriented along the lines of the current standard.
+ having specified widths should be oriented along the lines of the current standard
+ <code class="computeroutput">stdint.h</code> and <code class="computeroutput"><cstdint></code>.
 Consider the existing specification of integer <code class="computeroutput">typedef</code>s
 having specified widths in C++11. A partial synopsis is shown below.
 
@@ -51,55 +52,170 @@

 It is not immediately obvious where the optional floating-point <code class="computeroutput">typedef</code>s having specified widths should reside.
 One potential place is <code class="computeroutput"><cstdint></code>. The <code class="computeroutput">int</code>,
- however, implies integer types. Here, we prefer the proposed new header <code class="computeroutput"><cstdfloat></code>.
+ however, implies integer types. Here, we prefer the proposed new headers <code class="computeroutput">stdfloat.h</code> and <code class="computeroutput"><cstdfloat></code>
+ calling <code class="computeroutput">stdfloat.h</code>.
 

- We propose to add a new header <code class="computeroutput"><cstdfloat></code>
- to the standard library. The header <code class="computeroutput"><cstdfloat></code>
- should contain all optional floating-point <code class="computeroutput">typedef</code>s
+ We propose the following changes to the C standard (and incorporated into the
+ C++ by reference).
+ 
+
+ We propose to add a new header <code class="computeroutput">stdfloat.h</code> and <code class="computeroutput"><cstdfloat></code> to the standard library. The header <code class="computeroutput"><cstdfloat></code> should call <code class="computeroutput">stdfloat.h</code> which
+ may contain optional floating-point <code class="computeroutput">typedef</code>s
 having specified widths included in the implementation and the corresponding
- C-style macros shown above.
+ C macros shown above.
 

- Section 18.4 could be extended as shown below.
+ Section 18.4 could be extended (with a new title) but for clarity a new section
+ 18.11 is proposed.
 

- 18.4? Integer and Floating-Point Types Having Specified Widths
+ 18.11 Floating-Point Types having Specified Widths
 

- 18.4.1 Header <cstdint> synopsis [cstdint.syn]
+ 18.11.1 Header <cstdfloat> synopsis [cstdfloat.syn]
+ 
+
+ Header <code class="computeroutput">cstdfloat.h</code>
+ 
+
+ All implementations should define this header, even if none of the <code class="computeroutput">typedef</code>s are available, when it will be an empty
+ file.
 

- 18.4.2? Header <cstdfloat> synopsis [cstdfloat.syn]
+ Only those <code class="computeroutput">typedef</code>s that are appropriate
+ should be defined. For example, if a <code class="computeroutput">double</code>
+ type is not in IEEE754 format, then <code class="computeroutput">typedef
+ floating-point-type
+ float64_t</code> should not
+ be defined. This will ensure that programs that try to use a <code class="computeroutput">typedef</code> that is not defined on that platform
+ will simply fail to compile.
+ 
+
+ <code class="computeroutput">typedef</code>s of the format <code class="computeroutput">floatN_t</code> are for IEE754 types (were available)
+ providing exactly N bits. For these types that are defined, <code class="computeroutput">std::numeric_limits<T>::is_iec559 == true</code>.
+ 
+
+ <code class="computeroutput">typedef</code>s of the format <code class="computeroutput">float_leastN_t</code> provide types with at least
+ the precision N, but do not specify the layout.
+ 
+
+ <code class="computeroutput">typedef</code>s of the format <code class="computeroutput">float_fastN_t</code> provide types with at least
+ the precision N, and provide the fastest execution, and do not
+ specify the layout.
+ 
+
+ The use of denormals is implementation dependent, but can be determined for
+ any type T from <code class="computeroutput">std::numeric_limits<T>::has_denorm, denorm_min</code>
+ and <code class="computeroutput">float_denorm_style</code>.
+ 
+
+ The endianness of the layout of the floating-point types is not specified here
+ (though it may be possible to determine this - see note 9).
 
<pre class="programlisting">namespace std
{
- typedef floating-point type float16_t; // optional.
- typedef floating-point type float32_t; // optional.
- typedef floating-point type float64_t; // optional.
- typedef floating-point type float80_t; // optional.
- typedef floating-point type float128_t; // optional.
- typedef floating-point type float256_t; // optional.
- typedef floating-point type float512_t; // optional.
- typedef floating-point type floatmax_t; // optional.
+ typedef floating-point type float8_t; // optional (See note 1).
+ typedef floating-point type float16_t; // optional (See note 2).
+ typedef floating-point type float24_t; // optional (See note 3.
+ typedef floating-point type float32_t; // optional (See note 4).
+ typedef floating-point type float64_t; // optional (See note 5).
+ typedef floating-point type float80_t; // optional (See note 6).
+ typedef floating-point type float128_t; // optional (See note 7).
+ typedef floating-point type floatmax_t; // optional (largest floating-point type available).

 typedef floating-point type float_least16_t; // optional.
 typedef floating-point type float_least32_t; // optional.
 typedef floating-point type float_least64_t; // optional.
- typedef floating-point type float_least80_t; // optional.
 typedef floating-point type float_least128_t; // optional.
- typedef floating-point type float_least256_t; // optional.
- typedef floating-point type float_least512_t; // optional.

 typedef floating-point type float_fast16_t; // optional.
 typedef floating-point type float_fast32_t; // optional.
 typedef floating-point type float_fast64_t; // optional.
 typedef floating-point type float_fast80_t; // optional.
 typedef floating-point type float_fast128_t; // optional.
- typedef floating-point type float_fast256_t; // optional.
- typedef floating-point type float_fast512_t; // optional.
}
</pre>
+
+ Notes
+ 
+
+ 1 There is no IEEE754/IEC559 specification for a 8-bit floating-point type,
+ so the layout is implementation dependent. The type should occupy exactly 8
+ bits to allow optimisation.
+ 
+
+ 2 There is no IEEE754/IEC559 specification for a 24-bit floating-point type,
+ so the layout is implementation dependent.
+ 
+
+ 3 IEEE754 Half precision.
+ 
+
+ 4 IEEE754 Single precision.
+ 
+
+ 5 IEEE754 Double precision.
+ 
+
+ 6 IEEE754 Extended precision. This type may be implemented using 128 bits,
+ with padding. The size and location of any padding is implementation dependent,
+ so this type is unlikely to be suitable for binary interchange.
+ 
+
+ 7 IEEE754 Quadruple precision.
+ 
+
+ 8 The use of denormals is implementation dependent, but can be determined for
+ any type T from <code class="computeroutput">std::numeric_limits<T>::has_denorm, denorm_min</code>
+ and <code class="computeroutput">float_denorm_style</code>.
+ 
+
+ 9 If cooperating programs wish to try to use binary interchange for IEEE754/IEC559
+ types of <code class="computeroutput">float_N_t</code>, for example
+ for serialization, because the endianness of the layout of the floating-point
+ types is not specified (but may be determined) therefore programs must ensure
+ that they all use the same endianness and the same use of denormals.
+ 
+
+ The header <code class="computeroutput">stdfloat.h</code> should also contain all necessary C function
+ macros in the form shown below.
+ 
+<pre class="programlisting">FLOAT{16 32 64 80 128 MAX}_C
+</pre>
+
+ The code below, for example, initializes a constant <code class="computeroutput">float128_t</code>
+ value using one of these macros.
+ 
+<pre class="programlisting">`#include cstdfloat.h` or `#include <cstdfloat>`
+
+constexpr std::float128_t euler = FLOAT128_C(0.57721566490153286060651209008240243104216);
+</pre>
+
+ The following code initializes a constant <code class="computeroutput">float16_t</code>
+ value using another one of these macros.
+ 
+<pre class="programlisting">const std::float16_t euler = FLOAT16_C(0.577216);
+</pre>
+
+ In addition, the header <code class="computeroutput"><cstdfloat></code> should contain all necessary macros of
+ the form:
+ 
+<pre class="programlisting">FLOAT_[FAST LEAST]{16 32 64 80 128}_MIN
+FLOAT_[FAST LEAST]{16 32 64 80 128}_MAX
+FLOATMAX_MIN
+FLOATMAX_MAX
+</pre>
+
+ These macros can be used to query the ranges of the optional floating-point
+ typedefs having specified widths at compile-time. For example,
+ 
+<pre class="programlisting">#include <limits>
+#include <cstdfloat>
+
+static_assert(FLOATMAX_MAX > (std::numeric_limits<float>::max)(),
+ "The iec559 floating-point range is too small.");
+</pre>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>

Modified: sandbox/precision/libs/precision/doc/html/precision/version_id.html
==============================================================================
--- sandbox/precision/libs/precision/doc/html/precision/version_id.html (original)
+++ sandbox/precision/libs/precision/doc/html/precision/version_id.html 2013-04-18 09:33:32 EDT (Thu, 18 Apr 2013)
@@ -26,7 +26,7 @@
<a name="precision.version_id"></a><a class="link" href="version_id.html" title="Version Info">Version Info</a>
</h2></div></div></div>

- Last edit to Quickbook file precision.qbk was at 09:52:41 AM on 2013-Apr-09.
+ Last edit to Quickbook file precision.qbk was at 02:32:31 PM on 2013-Apr-18.

<div class="tip"><table border="0" summary="Tip">
<tr>

Modified: sandbox/precision/libs/precision/doc/precision.pdf
==============================================================================
Binary files. No diff available.

Modified: sandbox/precision/libs/precision/doc/precision.qbk
==============================================================================
--- sandbox/precision/libs/precision/doc/precision.qbk (original)
+++ sandbox/precision/libs/precision/doc/precision.qbk 2013-04-18 09:33:32 EDT (Thu, 18 Apr 2013)
@@ -13,7 +13,11 @@

[/purpose paper for C++ ISO standards group WG21/SG6 numerics.]

-ISO/IEC JTC1 SC22 WG21/SG6 Numerics N3626 - 2013-04-05
+ISO/IEC JTC1 SC22 WG21/SG6 Numerics N3626 - 2013-04-18
+
+ISO/IEC JTC1 SC22 WG14/ Numerics N1703 - 2013-04-18
+
+Revised after WG21/SG6 meeting 18 Apr 2013.

Comments and suggestions to Paul.A.Bristow pbristow_at_hetp.u-net.com.

@@ -351,11 +355,11 @@

[endsect] [/section:literals Handling floating-point literals]

-[section:thestandard Place in the standard]
+[section:thestandard Changes to the C and C++ standard]

The proper place for defining the optional
floating-point `typedef`s having specified widths
-should be oriented along the lines of the current standard.
+should be oriented along the lines of the current standard `stdint.h` and `<cstdint>`.
Consider the existing specification of integer `typedef`s having
specified widths in C++11. A partial synopsis is shown below.

@@ -377,50 +381,117 @@
optional floating-point `typedef`s having specified widths
should reside. One potential place is `<cstdint>`.
The `int`, however, implies integer types. Here, we prefer the
-proposed new header `<cstdfloat>`.
+proposed new headers `stdfloat.h` and `<cstdfloat>` calling `stdfloat.h`.

-We propose to add a new header `<cstdfloat>` to the standard library.
-The header `<cstdfloat>` should contain all
-optional floating-point `typedef`s having specified widths
-included in the implementation and the corresponding C-style
-macros shown above.
+We propose the following changes to the C standard (and incorporated into the C++ by reference).

-Section 18.4 could be extended as shown below.
+We propose to add a new header `stdfloat.h` and
+`<cstdfloat>` to the standard library.
+The header `<cstdfloat>` should call `stdfloat.h`
+which may contain optional floating-point `typedef`s having specified widths
+included in the implementation and the corresponding C macros shown above.

-18.4? Integer and Floating-Point Types Having Specified Widths
+Section 18.4 could be extended (with a new title) but for clarity a new section 18.11 is proposed.

-18.4.1 Header <cstdint> synopsis [cstdint.syn]
+18.11 Floating-Point Types having Specified Widths
+
+18.11.1 Header <cstdfloat> synopsis [cstdfloat.syn]
+
+Header `cstdfloat.h`
+
+All implementations should define this header, even if none of the `typedef`s are available, when it will be an empty file.
+
+Only those `typedef`s that are appropriate should be defined. For example, if a `double` type is not in IEEE754 format,
+then `typedef floating-point-type float64_t` should *not* be defined.
+This will ensure that programs that try to use a `typedef` that is not defined on that platform will simply fail to compile.
+
+`typedef`s of the format `floatN_t` are for IEE754 types (were available) providing exactly N bits.
+For these types that are defined, `std::numeric_limits<T>::is_iec559 == true`.
+
+`typedef`s of the format `float_leastN_t` provide types with at least the precision N, but do *not* specify the layout.
+
+`typedef`s of the format `float_fastN_t` provide types with at least the precision N, and provide the fastest execution, and do *not* specify the layout.

-18.4.2? Header <cstdfloat> synopsis [cstdfloat.syn]
+The use of denormals is implementation dependent, but can be determined for any type T from `std::numeric_limits<T>::has_denorm, denorm_min` and `float_denorm_style`.
+
+The endianness of the layout of the floating-point types is not specified here (though it may be possible to determine this - see note 9).

 namespace std
 {
- typedef floating-point type float16_t; // optional.
- typedef floating-point type float32_t; // optional.
- typedef floating-point type float64_t; // optional.
- typedef floating-point type float80_t; // optional.
- typedef floating-point type float128_t; // optional.
- typedef floating-point type float256_t; // optional.
- typedef floating-point type float512_t; // optional.
- typedef floating-point type floatmax_t; // optional.
+ typedef floating-point type float8_t; // optional (See note 1).
+ typedef floating-point type float16_t; // optional (See note 2).
+ typedef floating-point type float24_t; // optional (See note 3.
+ typedef floating-point type float32_t; // optional (See note 4).
+ typedef floating-point type float64_t; // optional (See note 5).
+ typedef floating-point type float80_t; // optional (See note 6).
+ typedef floating-point type float128_t; // optional (See note 7).
+ typedef floating-point type floatmax_t; // optional (largest floating-point type available).

 typedef floating-point type float_least16_t; // optional.
 typedef floating-point type float_least32_t; // optional.
 typedef floating-point type float_least64_t; // optional.
- typedef floating-point type float_least80_t; // optional.
 typedef floating-point type float_least128_t; // optional.
- typedef floating-point type float_least256_t; // optional.
- typedef floating-point type float_least512_t; // optional.

 typedef floating-point type float_fast16_t; // optional.
 typedef floating-point type float_fast32_t; // optional.
 typedef floating-point type float_fast64_t; // optional.
 typedef floating-point type float_fast80_t; // optional.
 typedef floating-point type float_fast128_t; // optional.
- typedef floating-point type float_fast256_t; // optional.
- typedef floating-point type float_fast512_t; // optional.
 }

+Notes
+
+1 There is no IEEE754/IEC559 specification for a 8-bit floating-point type, so the layout is implementation dependent. The type should occupy exactly 8 bits to allow optimisation.
+
+2 There is no IEEE754/IEC559 specification for a 24-bit floating-point type, so the layout is implementation dependent.
+
+3 IEEE754 Half precision.
+
+4 IEEE754 Single precision.
+
+5 IEEE754 Double precision.
+
+6 IEEE754 Extended precision. This type may be implemented using 128 bits, with padding.
+The size and location of any padding is implementation dependent, so this type is unlikely to be suitable for binary interchange.
+
+7 IEEE754 Quadruple precision.
+
+8 The use of denormals is implementation dependent, but can be determined for any type T from `std::numeric_limits<T>::has_denorm, denorm_min` and `float_denorm_style`.
+
+9 If cooperating programs wish to try to use binary interchange for IEEE754/IEC559 types of `float_N_t`,
+for example for serialization,
+because the endianness of the layout of the floating-point types is not specified (but may be determined)
+therefore programs must ensure that they all use the same endianness and the same use of denormals.
+
+The header `stdfloat.h` should also contain all necessary C function macros in the form shown below.
+
+ FLOAT{16 32 64 80 128 MAX}_C
+
+The code below, for example, initializes a constant `float128_t` value using one of these macros.
+
+ `#include cstdfloat.h` or `#include <cstdfloat>`
+
+ constexpr std::float128_t euler = FLOAT128_C(0.57721566490153286060651209008240243104216);
+
+The following code initializes a constant `float16_t` value using another one of these macros.
+
+ const std::float16_t euler = FLOAT16_C(0.577216);
+
+In addition, the header `<cstdfloat>` should contain all necessary macros of the form:
+
+ FLOAT_[FAST LEAST]{16 32 64 80 128}_MIN
+ FLOAT_[FAST LEAST]{16 32 64 80 128}_MAX
+ FLOATMAX_MIN
+ FLOATMAX_MAX
+
+These macros can be used to query the ranges of the optional floating-point typedefs having specified widths at compile-time. For example,
+
+ #include <limits>
+ #include <cstdfloat>
+
+ static_assert(FLOATMAX_MAX > (std::numeric_limits<float>::max)(),
+ "The iec559 floating-point range is too small.");
+
[endsect] [/section:thestandard Place in the standard]

[section:cmathinterop Interoperation with <cmath> and special functions]

Next message: john_at_[hidden]: "[Boost-commit] svn:boost r83956 - in branches/release/tools/auto_index: . src"
Previous message: john_at_[hidden]: "[Boost-commit] svn:boost r83954 - in branches/release/tools/bcp: . doc doc/html"

Date view	Thread view	Subject view	Author view

Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk