From c1dff8958c50a3ae2248bdd51301b4ca66e455f3 Mon Sep 17 00:00:00 2001 From: Beman Date: Mon, 20 May 2013 15:04:33 -0400 Subject: [PATCH] Continue doc refinement. --- doc/conversion.html | 9 +++--- doc/index.html | 71 ++++++++++++++++++++++++++------------------- doc/types.html | 22 +++++++------- 3 files changed, 57 insertions(+), 45 deletions(-) diff --git a/doc/conversion.html b/doc/conversion.html index 2864883..1dda49e 100644 --- a/doc/conversion.html +++ b/doc/conversion.html @@ -129,7 +129,8 @@ provided.

The only supported types are four byte float and eight byte double. Even after endianness has been accounted for, floating point values will not be portable between systems that use different floating -point formats.

+point formats. Systems where the integer endianness and floating point +endianness are not supported.

@@ -137,8 +138,8 @@ point formats.

-

Only 16-bit, 32-bit, and 64-bit integers are supported. No tests have been -performed on machines that do not use two's complement arithmetic.

+

Only 16-bit, 32-bit, and 64-bit integers are supported. Tests have been +performed on machines that use two's complement arithmetic.

@@ -367,7 +368,7 @@ convert(x, some_order, order::native); // convert to native byte order if neede

Recent compilers, including GCC, Clang, and Microsoft, supply intrinsic built-in support for byte swapping. Such support is automatically detected and used since it results in smaller and much faster generated code for release builds.

Defining BOOST_ENDIAN_NO_INTRINSICS will suppress use of the intrinsics. Please try defining it if you get compiler errors, such as header byteswap.h not being found.

The macro BOOST_ENDIAN_INTRINSIC_MSG is defined as either "no byte swap intrinsics" or a string describing the particular set of intrinsics being used.

Acknowledgements

Tomas Puverle was instrumental in identifying and articulating the need to support endian conversion as separate from endian integer types. Phil Endecott suggested the form of the value returning signatures. Vicente Botet and other reviewers suggested supporting floating point types and user defined types. General reverse template implementation approach using std::reverse suggested by Mathias Gaunard. Portable implementation approach for 16, 32, and 64-bit integers suggested by tymofey, with avoidance of undefined behavior as suggested by Giovanni Piero Deretta, and a further refinement suggested by Pyry Jahkola. Intrinsic builtins implementation approach for 16, 32, and 64-bit integers suggested by several reviewers, and by David Stone, who provided his Boost licensed macro implementation that became the starting point for boost/endian/detail/intrinsic.hpp.

-

Last revised: 19 May, 2013

+

Last revised: 20 May, 2013

© Copyright Beman Dawes, 2011

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 f2ffe06..4172d1b 100644 --- a/doc/index.html +++ b/doc/index.html @@ -26,7 +26,7 @@ Boost Home     Endian Home     Conversion Functions     - Integer Types     Tutorial + Endian Types     Tutorial @@ -53,7 +53,7 @@

Abstract

-

Boost.Endian provides facilities to manipulate the byte ordering of integers.

+

Boost.Endian provides two facilities to manipulate the byte ordering of integers.

Introduction to endianness

@@ -82,16 +73,16 @@ 
int16_t i = 0x0102;
-FILE * file = fopen("test", "wb");   // MUST BE BINARY
+FILE * file = fopen("test.bin", "wb");   // MUST BE BINARY
 fwrite(&i, sizeof(int16_t), 1, file);
 fclose(file);
-

On an Apple, Linux, or Windows computer with an Intel CPU, a hex dump -of the "test" output file produces:

+

On OS X, Linux, or Windows systems with an Intel CPU, a hex dump +of the "test.bin" output file produces:

0201

-

On an Apple or other computer with a PowerPC CPU, or an Oracle/Sun Solaris computer with a SPARC CPU, a hex dump of the "test" +

On OS X systems with a PowerPC CPU, or Solaris systems with a SPARC CPU, a hex dump of the "test.bin" output file produces:

0102

@@ -111,9 +102,10 @@ at different ends.

See the Wikipedia's Endianness article for an extensive discussion of endianness.

-

Except for reading an occasional core dump, most programmers can ignore -endianness. But when exchanging binary integers with other computer systems, whether by -file transfers or over a network, programmers have to deal with endianness.

+

Except for reading a core dump on little-endian systems, most programmers can +ignore endianness. But when exchanging binary integers and binary floating point +values between computer systems with differing endianness, whether by physical file transfer or over a network, programmers have to deal with endianness +in their code.

Introduction to the Boost.Endian library

The Boost.Endian library provides two facilities for dealing with endianness.

@@ -185,28 +177,47 @@ application.

+

Overall FAQ

+

Why bother with endianness? Does endianness have any uses outside of +portable binary file or network I/O formats?

+
+

Binary data portability is the primary use case, and that implies I/O.

+

Using the 3, 5, 6, and 7 byte integer types to save internal or external +memory space is a minor secondary use case.

+
+

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

+
+

Binary arithmetic data is smaller and therefore I/O is faster and file sizes +are smaller. Transfer between systems is less expensive. Standard interchange +formats often specify binary arithmetic data.

+

Furthermore, binary arithmetic data is of fixed size, and so fixed-size disk +records are possible without padding, easing sorting and allowing direct access. +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.

+
+

Acknowledgements

Comments and suggestions were received from -Benaka Moorthi, +Adder, Benaka Moorthi, Christopher Kohlhoff, -Cliff Green, -Gennaro Proto, -Giovanni Piero Deretta, dizzy, Jeff Flinn, -John Maddock, +Cliff Green,Daniel James, Gennaro Proto, +Giovanni Piero Deretta, Gordon Woodhull, dizzy, Hartmut Kaiser, Jeff Flinn, +John Filo, John Maddock, Kim Barrett, Marsh Ray, -Martin Bonner, -Matias Capeletto, -Neil Mayhew, Phil Endecott, Rene Rivera, +Martin Bonner, Mathias Gaunard, Matias Capeletto, +Neil Mayhew, Paul Bristow, Phil Endecott, Pyry Jahkola, Rene Rivera, Robert Stewart, Roland Schwarz, Scott McMurray, Sebastian Redl, -Tomas Puverle, Vincente Botet, and -Yuval Ronen.

+Tim Blechmann, Tim Moore, tymofey, Tomas Puverle, Vincente Botet, Yuval Ronen +and Vitaly Budovski,.

Last revised: 20 May, 2013

-

© Copyright Beman Dawes, 2011

+

© 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/types.html b/doc/types.html index 3ea0f74..893d5e9 100644 --- a/doc/types.html +++ b/doc/types.html @@ -53,7 +53,7 @@ Design
Experience
Motivating use cases
- C++0x
+ C++11
Compilation
Acknowledgements @@ -178,9 +178,9 @@ because it has constructors, private data members, and a base class. This means that common use cases are relying on unspecified behavior in that the C++ Standard does not guarantee memory layout for non-POD types. This has not been a problem in practice since all known C++ compilers do layout memory as if -endian were a POD type. In C++0x, it will be possible to specify the +endian were a POD type. In C++11, it will be possible to specify the default constructor as trivial, and private data members and base classes will -no longer disqualify a type from being a POD. Thus under C++0x, endian +no longer disqualify a type from being a POD. Thus under C++11, endian will no longer be relying on unspecified behavior.

Feature set