From 3d814f4f527882e746fe27ea31ca641fb7e14a15 Mon Sep 17 00:00:00 2001 From: Beman Date: Mon, 19 Jan 2015 07:41:28 -0500 Subject: [PATCH] Add docs for BOOST_ENDIAN_DEPRECATED_NAMES compatibility. Fix inspect issues. --- doc/arithmetic.html | 75 ++++++++++++++++++++----------------- doc/buffers.html | 12 +++--- doc/choosing_approach.html | 4 +- doc/conversion.html | 6 +-- doc/index.html | 27 +++++++++++-- doc/mini_review_topics.html | 8 ++-- 6 files changed, 79 insertions(+), 53 deletions(-) diff --git a/doc/arithmetic.html b/doc/arithmetic.html index f9af025..2d72bd3 100644 --- a/doc/arithmetic.html +++ b/doc/arithmetic.html @@ -1,4 +1,4 @@ - + @@ -17,7 +17,7 @@ -Boost logo +Boost logo Endian Arithmetic Types @@ -109,10 +109,11 @@ using namespace boost::endian; namespace { - // This is an extract from a very widely used GIS file format. It seems odd - // to mix big and little endians in the same file - but this is a real-world - // format and users wishing to write low level code manipulating these files - // must deal with the mixed endianness. + // This is an extract from a very widely used GIS file format. + // Why the designer decided to mix big and little endians in + // the same file is not known. But this is a real-world format + // and users wishing to write low level code manipulating these + // files have to deal with the mixed endianness. struct header { @@ -136,11 +137,13 @@ int main(int, char* []) h.version = 1; h.shape_type = 0x01020304; - // Low-level I/O such as POSIX read/write or <cstdio> fread/fwrite is sometimes - // used for binary file operations when ultimate efficiency is important. Such - // I/O is often performed in some C++ wrapper class, but to drive home the - // point that endian integers are often used in fairly low-level code that does - // bulk I/O operations, <cstdio> fopen/fwrite is used for I/O in this example. + // Low-level I/O such as POSIX read/write or <cstdio> + // fread/fwrite is sometimes used for binary file operations + // when ultimate efficiency is important. Such I/O is often + // performed in some C++ wrapper class, but to drive home the + // point that endian integers are often used in fairly + // low-level code that does bulk I/O operations, <cstdio> + // fopen/fwrite is used for I/O in this example. std::FILE* fi = std::fopen(filename, "wb"); // MUST BE BINARY @@ -205,8 +208,9 @@ enum class align {no, yes};

One class template is provided:

- 
template <order Order, typename T, std::size_t n_bits, align A = align::no>
-  class endian_arithmetic;
+  
template <order Order, typename T, std::size_t n_bits,
+  align Align = align::no>
+class endian_arithmetic;

Typedefs, such as big_int32_t, provide convenient naming @@ -366,9 +370,10 @@ usual operations on integers are supplied.

enum class align {no, yes}; - template <order Order, class T, std::size_t n_bits, align A = align::no> + template <order Order, class T, std::size_t n_bits, + align Align = align::no> class endian_arithmetic - : public endian_buffer<Order, T, n_bits, A> + : public endian_buffer<Order, T, n_bits, Align> { public: typedef T value_type; @@ -380,8 +385,8 @@ usual operations on integers are supplied.

endian_arithmetic& operator=(T v) noexcept; operator value_type() const noexcept; - value_type value() const noexcept; // exposition only; see endian_buffer - const char* data() const noexcept; // exposition only; see endian_buffer + value_type value() const noexcept; // for exposition; see endian_buffer + const char* data() const noexcept; // for exposition; see endian_buffer // arithmetic operations // note that additional operations are provided by the value_type @@ -417,35 +422,35 @@ usual operations on integers are supplied.

// typedefs // aligned big endian floating point types - typedef endian<order::big, float, 32, align::yes> big_float32_t; - typedef endian<order::big, double, 64, align::yes> big_float64_t; + typedef endian<order::big, float, 32, align::yes> big_float32_t; + typedef endian<order::big, double, 64, align::yes> big_float64_t; // aligned little endian floating point types - typedef endian<order::little, float, 32, align::yes> little_float32_t; - typedef endian<order::little, double, 64, align::yes> little_float64_t; + typedef endian<order::little, float, 32, align::yes> little_float32_t; + typedef endian<order::little, double, 64, align::yes> little_float64_t; // unaligned big endian floating point types - typedef endian<order::big, float, 32, align::no> big_float32un_t; - typedef endian<order::big, double, 64, align::no> big_float64un_t; + typedef endian<order::big, float, 32, align::no> big_float32_ut; + typedef endian<order::big, double, 64, align::no> big_float64_ut; // unaligned little endian floating point types - typedef endian<order::little, float, 32, align::no> little_float32un_t; - typedef endian<order::little, double, 64, align::no> little_float64un_t; + typedef endian<order::little, float, 32, align::no> little_float32_ut; + typedef endian<order::little, double, 64, align::no> little_float64_ut; // aligned big endian signed integer types - typedef endian<order::big, int16_t, 16, align::yes> big_int16_t; - typedef endian<order::big, int32_t, 32, align::yes> big_int32_t; - typedef endian<order::big, int64_t, 64, align::yes> big_int64_t; + typedef endian<order::big, int16_t, 16, align::yes> big_int16_t; + typedef endian<order::big, int32_t, 32, align::yes> big_int32_t; + typedef endian<order::big, int64_t, 64, align::yes> big_int64_t; // aligned big endian unsigned integer types - typedef endian<order::big, uint16_t, 16, align::yes> big_uint16_t; - typedef endian<order::big, uint32_t, 32, align::yes> big_uint32_t; - typedef endian<order::big, uint64_t, 64, align::yes> big_uint64_t; + typedef endian<order::big, uint16_t, 16, align::yes> big_uint16_t; + typedef endian<order::big, uint32_t, 32, align::yes> big_uint32_t; + typedef endian<order::big, uint64_t, 64, align::yes> big_uint64_t; // aligned little endian signed integer types - typedef endian<order::little, int16_t, 16, align::yes> little_int16_t; - typedef endian<order::little, int32_t, 32, align::yes> little_int32_t; - typedef endian<order::little, int64_t, 64, align::yes> little_int64_t; + typedef endian<order::little, int16_t, 16, align::yes> little_int16_t; + typedef endian<order::little, int32_t, 32, align::yes> little_int32_t; + typedef endian<order::little, int64_t, 64, align::yes> little_int64_t; // aligned little endian unsigned integer types typedef endian<order::little, uint16_t, 16, align::yes> little_uint16_t; @@ -672,7 +677,7 @@ differs from endian representation size. Vicente Botet and other reviewers suggested supporting floating point types.

Last revised: -17 January, 2015

+19 January, 2015

© Copyright Beman Dawes, 2006-2009, 2013

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

diff --git a/doc/buffers.html b/doc/buffers.html index 26cd461..594b941 100644 --- a/doc/buffers.html +++ b/doc/buffers.html @@ -17,7 +17,7 @@ -Boost logo +Boost logo Endian Buffer Types @@ -195,8 +195,9 @@ enum class align {no, yes};

One class template is provided:

- 
template <order Order, typename T, std::size_t Nbits, align A = align::no>
-  class endian_buffer;
+  
template <order Order, typename T, std::size_t Nbits,
+  align Align = align::no>
+class endian_buffer;

Typedefs, such as big_int32_buf_t, provide convenient naming @@ -356,7 +357,8 @@ usual operations on integers are supplied.

enum class align {no, yes}; - template <order Order, class T, std::size_t Nbits, align Align = align::no> + template <order Order, class T, std::size_t Nbits, + align Align = align::no> class endian_buffer { public: @@ -648,7 +650,7 @@ any Boost object libraries.

Last revised: -17 January, 2015

+19 January, 2015

© Copyright Beman Dawes, 2006-2009, 2013

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

diff --git a/doc/choosing_approach.html b/doc/choosing_approach.html index 119d302..effb79f 100644 --- a/doc/choosing_approach.html +++ b/doc/choosing_approach.html @@ -14,7 +14,7 @@ -Boost logo +Boost logo Choosing the Approach @@ -400,7 +400,7 @@ arithmetic approach.

Last revised: -17 January, 2015

+19 January, 2015

© Copyright Beman Dawes, 2011, 2013, 2014

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

diff --git a/doc/conversion.html b/doc/conversion.html index 53d33d6..c23617b 100644 --- a/doc/conversion.html +++ b/doc/conversion.html @@ -1,4 +1,4 @@ - + @@ -15,7 +15,7 @@ -Boost logo +Boost logo Endian Conversion Functions @@ -367,7 +367,7 @@ Pierre Talbot provided the int8_t endian_reverse() and templated endian_reverse_inplace() implementations.

Last revised: -17 January, 2015

+19 January, 2015

© Copyright Beman Dawes, 2011, 2013

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

diff --git a/doc/index.html b/doc/index.html index 6836b0d..27e0b10 100644 --- a/doc/index.html +++ b/doc/index.html @@ -15,7 +15,7 @@ -Boost logo +Boost logo Endian Library @@ -56,6 +56,7 @@ requested by formal review
   Other changes since formal review
+Compatibility with interim releases
Acknowledgements
@@ -445,8 +446,9 @@ page for details.

Other changes since formal review

+

Compatibility with interim releases

+ +

Prior to the official Boost release, class template +endian_arithmetic has been used for a decade or more with the same +functionality but under the name endian. Other names also changed +in the official release. If the macro BOOST_ENDIAN_DEPRECATED_NAMES +is defined, those old now deprecated names are still supported. However, the +class template endian name is only provided for compilers +supporting C++11 template aliases. For C++03 compilers, the name will have to be +changed to endian_arithmetic.

+ +

To support backward header compatibility, deprecated header boost/endian/endian.hpp +forwards to boost/endian/arithmetic.hpp. It requires +BOOST_ENDIAN_DEPRECATED_NAMES be defined. It should only be used while +transitioning to the official Boost release of the library as it will be removed +in some future release.

+

Acknowledgements

Comments and suggestions were received from Adder, Benaka Moorthi, Christopher Kohlhoff, Cliff Green, Daniel James, Gennaro Proto, Giovanni Piero @@ -484,7 +503,7 @@ Blechmann, Tim Moore, tymofey, Tomas Puverle, Vincente Botet, Yuval Ronen and Vitaly Budovsk. Apologies if anyone has been missed.

Last revised: -15 January, 2015

+19 January, 2015

© Copyright Beman Dawes, 2011, 2013

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

diff --git a/doc/mini_review_topics.html b/doc/mini_review_topics.html index 11c455f..d7a7f3c 100644 --- a/doc/mini_review_topics.html +++ b/doc/mini_review_topics.html @@ -13,7 +13,7 @@ -Boost logo +Boost logo Endian Mini-Review @@ -113,8 +113,8 @@ might used inadvertently or inappropriately. The impact of adding an endian_buff

11. Stream insertion and extraction of the endian integer/float types should be documented and included in the test coverage.

-

Done. See Stream inserter and - Stream extractor.

+

Done. See Stream inserter and + Stream extractor.

12. Binary I/O support that was investigated during development of the Endian library should be put up for mini-review for inclusion in the Boost I/O @@ -140,7 +140,7 @@ might used inadvertently or inappropriately. The impact of adding an endian_buff

Last revised: -04 January, 2015

+19 January, 2015

© Copyright Beman Dawes, 2014

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