From 2db73ab893a61b74e73c0c644c2819241beef95a Mon Sep 17 00:00:00 2001 From: Beman Date: Tue, 5 Apr 2016 13:57:27 -0400 Subject: [PATCH] Document permanent removal of floating point types. --- doc/index.html | 68 ++++++++++++++++++++------------------------------ 1 file changed, 27 insertions(+), 41 deletions(-) diff --git a/doc/index.html b/doc/index.html index 05594ab..0338f70 100644 --- a/doc/index.html +++ b/doc/index.html @@ -88,27 +88,9 @@ formal review
  • Secondary use: Minimizing data size via sizes and/or alignments not supported by the - standard C++ arithmetic types.
    -
    • + standard C++ integer types. -
    -
    - - - - -
    -

    Notice

    -

    This first release (1.58.0) of the Endian library as an - official Boost library removes for floating point type support that was - present in the mini-review pre-release. Floating point types will be - supported in the Boost 1.59.0 release with a slightly modified floating - point conversion interface and implementation that addresses reliability - concerns.

    -
    -
    -

    Introduction to endianness

    Consider the following code:

    @@ -414,12 +396,12 @@ large array saves a lot of space compared to one of the 64-bit types.

    Why bother with binary I/O? Why not just use C++ Standard Library stream inserters and extractors?

    -

    Data interchange formats often specify binary arithmetic data.

    -

    Binary arithmetic data is smaller and therefore I/O is faster and file sizes +

    Data interchange formats often specify binary integer data.

    +

    Binary integer data is smaller and therefore I/O is faster and file sizes are smaller. Transfer between systems is less expensive.

    -

    Furthermore, binary arithmetic data is of fixed size, and so fixed-size disk +

    Furthermore, binary integer data is of fixed size, and so fixed-size disk records are possible without padding, easing sorting and allowing random access.

    -

    Disadvantages, such as the inability to use text utilities on the +

    Disadvantages, such as the inability to use text utilities on the resulting files, limit usefulness to applications where the binary I/O advantages are paramount.

    @@ -453,7 +435,7 @@ that would be lost if the inheritance hierarchy were collapsed.

    requested during formal review by those wishing total control over when conversion occurs. They also felt that buffer types would be less likely to be misused by maintenance programmers not familiar with the implications of -performing a lot of arithmetic operations on the endian arithmetic types.

    +performing a lot of integer operations on the endian arithmetic integer types.

    What is gained by using the buffer types rather than always just using the arithmetic types?

    @@ -466,22 +448,6 @@ same design patterns or idioms that would be used for buffer types, resulting in the same code being generated for either types.

    -

    What are the limitations of floating point support?

    - -
    - -

    The only supported types are four-byte float and eight-byte -double. The only supported format is -IEEE 754 (also -know as ISO/IEC/IEEE 60559). Systems on which integer endianness differs from floating point -endianness are not supported.

    - -

    Support for floating point types was removed from Boost 1.58.0 because there -was not enough time to resolve reliability concerns. It is expected that -floating point support will be available in Boost 1.59.0.

    - -
    -

    What are the limitations of integer support?

    @@ -494,6 +460,26 @@ and 8, 16, 32, and 64-bit aligned integers.

    +

    Why is there no floating point support?

    + +
    + +

    An attempt was made to support four-byte floats and eight-byte +doubles, limited to +IEEE 754 (also +know as ISO/IEC/IEEE 60559) floating point and further limited to systems where +floating point endianness does not differ from integer +endianness.

    + +

    Even with those limitations, support for floating point types was not +reliable and was removed. For example, simply reversing the endianness of a +floating point number can result in a signaling-NAN. For all practical purposes, +binary serialization and endianness for integers are one and the same problem. +That is not true for floating point numbers, so binary serialization interfaces +and formats for floating point does not fit well in an endian-based library.

    + +
    +

    Release history

    Changes requested by formal review

    The library was reworked from top to bottom to accommodate changes requested @@ -610,7 +596,7 @@ Blechmann, Tim Moore, tymofey, Tomas Puverle, Vincente Botet, Yuval Ronen and Vitaly Budovsk. Apologies if anyone has been missed.

    Last revised: -16 October, 2015

    +05 April, 2016

    © Copyright Beman Dawes, 2011, 2013

    Distributed under the Boost Software License, Version 1.0. See www.boost.org/ LICENSE_1_0.txt