From c62aa232e132241b5f7da812057cf1b4d6856af6 Mon Sep 17 00:00:00 2001 From: Beman Date: Tue, 17 Feb 2015 11:21:21 -0500 Subject: [PATCH] Apply mini-review editorial fixes from Rob Stewart, mostly just accepting his suggested wording. --- doc/arithmetic.html | 23 ++++++++++---------- doc/buffers.html | 51 ++++++++++++++++++++++++--------------------- doc/index.html | 26 +++++++++++------------ 3 files changed, 52 insertions(+), 48 deletions(-) diff --git a/doc/arithmetic.html b/doc/arithmetic.html index fac718c..ea4f5ee 100644 --- a/doc/arithmetic.html +++ b/doc/arithmetic.html @@ -384,7 +384,7 @@ usual operations on integers are supplied.

public: typedef T value_type; - // if BOOST_ENDIAN_FORCE_PODNESS is defined && C++11 POD's are not + // if BOOST_ENDIAN_FORCE_PODNESS is defined && C++11 PODs are not // available then these two constructors will not be present endian_arithmetic() noexcept = default; endian_arithmetic(T v) noexcept; @@ -599,9 +599,9 @@ FAQ.

conversion for every object involved in I/O. Endian integers require no conversion or copying. They are already in the desired format for binary I/O. Thus they can be read or written in bulk.

-

Are endian types POD's? Yes for C++11. No for C++03, although several +

Are endian types PODs? Yes for C++11. No for C++03, although several macros are available to force PODness in all cases.

-

What are the implications of endian integer types not being POD's with C++03 +

What are the implications of endian integer types not being PODs with C++03 compilers? They can't be used in unions. Also, compilers aren't required to align or lay out storage in portable ways, although this potential problem hasn't prevented @@ -657,14 +657,14 @@ places. Using Boost.Endian simplifies and cleans the code wonderfully."

The availability of the C++11 Defaulted Functions feature is detected automatically, and will be used if -present to ensure that objects of class endian are trivial, and -thus POD's.

+present to ensure that objects of class endian_arithmetic are trivial, and +thus PODs.

Compilation

Boost.Endian is implemented entirely within headers, with no need to link to any Boost object libraries.

Several macros allow user control over features:

Acknowledgements

Original design developed by Darin Adler based on classes developed by Mark -Borgerding. Four original class templates combined into a single endian +Borgerding. Four original class templates combined into a single endian_arithmetic class template by Beman Dawes, who put the library together, provided documentation, added the typedefs, and also added the unrolled_byte_loops sign partial specialization to correctly extend the sign when cover integer size @@ -687,7 +688,7 @@ differs from endian representation size. Vicente Botet and other reviewers suggested supporting floating point types.

Last revised: -12 February, 2015

+17 February, 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 3481035..a1f98f9 100644 --- a/doc/buffers.html +++ b/doc/buffers.html @@ -62,7 +62,8 @@

Introduction

-

The internal byte order of arithmetic types is traditionally called endianness. See the +

The internal byte order of arithmetic types is traditionally called endianness. See +the Wikipedia for a full exploration of endianness, including definitions of big @@ -85,7 +86,7 @@ class template, which is aimed at users who wish fully automatic endianness conversion and direct support for all normal arithmetic operations.

Example

The example/endian_example.cpp program writes a -binary file containing four byte big-endian and little-endian integers:

+binary file containing four-byte, big-endian and little-endian integers:

#include <iostream>
 #include <cstdio>
@@ -115,10 +116,10 @@ namespace
 
 int main(int, char* [])
 {
-  BOOST_STATIC_ASSERT(sizeof(header) == 16U);  // reality check
-  
   header h;
 
+  BOOST_STATIC_ASSERT(sizeof(h) == 16U);  // reality check
+  
   h.file_code   = 0x01020304;
   h.file_length = sizeof(header);
   h.version     = 1;
@@ -172,10 +173,10 @@ been no real-world use cases presented for other sizes.

 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 
+problem in practice since all known C++ compilers  lay out memory as if 
 endian were a POD type. In C++11, it is 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++11, endian_buffer 
+default constructor as trivial, and private data members and base classes  no longer disqualify a type from being a POD 
+type. Thus under C++11, endian_buffer 
 will no longer be relying on unspecified behavior.

 
Feature set

 
    
@@ -332,7 +333,8 @@ memory, files, and network transmissions. 
    
 Code that uses aligned types is possibly non-portable because alignment 
 requirements vary between hardware architectures and because alignment may be 
 affected by compiler switches or pragmas. For example, alignment of an 64-bit 
-integer may be to a 32-bit boundary on a 32-bit machine. Furthermore, aligned types 
+integer may be to a 32-bit boundary on a 32-bit machine and to a 64-bit boundary 
+on a 64-bit machine. Furthermore, aligned types 
 are only available on architectures with 8, 16, 32, and 64-bit integer types. 
    
 
    Recommendation: Prefer unaligned endian types.
    
 
    Recommendation: Protect yourself against alignment ills. For 
@@ -341,7 +343,7 @@ example:
    
   
    static_assert(sizeof(containing_struct) == 12, "sizeof(containing_struct) is wrong");

Note: One-byte big and little buffer types -never actually reverse endianness. They are provided to enable generic code, and +have identical layout on all platforms, so they never actually reverse endianness. They are provided to enable generic code, and to improve code readability and searchability.

Class template endian_buffer

An endian_buffer is an integer byte-holder with user-specified @@ -518,7 +520,7 @@ greater or equal to Nbits.

Members

endian_buffer() noexcept = default;
-

Effects: Constructs an object of type endian_buffer<Order, T, +

Effects: Constructs an uninitialized object of type endian_buffer<Order, T, Nbits, Align>.

explicit endian_buffer(T v) noexcept;
@@ -529,25 +531,25 @@ Nbits, Align>.

is a constant of type value_type with Nbits low-order bits set to one.

Remarks: If Align is align::yes then -endianness conversion if required is performed by +endianness conversion, if required, is performed by boost::endian::endian_reverse.

endian_buffer& operator=(T v) noexcept;

Postcondition: value() == v & mask, where mask is a constant of type value_type with Nbits - low-order bits set to one..

+ low-order bits set to one.

Returns: *this.

Remarks: If Align is align::yes then -endianness conversion if required is performed by +endianness conversion, if required, is performed by boost::endian::endian_reverse.

value_type value() const noexcept;

Returns: endian_value, converted to value_type -if necessary and having the endianness of the native platform.

+if required, and having the endianness of the native platform.

Remarks: If Align is align::yes then -endianness conversion if required is performed by +endianness conversion, if required, is performed by boost::endian::endian_reverse.

const char* data() const noexcept;
@@ -587,9 +589,9 @@ FAQ.

conversion for every object involved in I/O. Endian integers require no conversion or copying. They are already in the desired format for binary I/O. Thus they can be read or written in bulk.

-

Are endian types POD's? Yes for C++11. No for C++03, although several +

Are endian types PODs? Yes for C++11. No for C++03, although several macros are available to force PODness in all cases.

-

What are the implications of endian integer types not being POD's with C++03 +

What are the implications of endian integer types not being PODs with C++03 compilers? They can't be used in unions. Also, compilers aren't required to align or lay out storage in portable ways, although this potential problem hasn't prevented @@ -634,14 +636,14 @@ incrementing a variable in a record. It is very convenient to write:

The availability of the C++11 Defaulted Functions feature is detected automatically, and will be used if -present to ensure that objects of class endian are trivial, and -thus POD's.

+present to ensure that objects of class endian_buffer are trivial, and +thus PODs.

Compilation

Boost.Endian is implemented entirely within headers, with no need to link to any Boost object libraries.

Several macros allow user control over features:

Last revised: -12 February, 2015

+17 February, 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/index.html b/doc/index.html index 9f92ac5..b651d6c 100644 --- a/doc/index.html +++ b/doc/index.html @@ -125,7 +125,7 @@ Jonathan Swift's satirical novel Gulliver’s Travels, where rival kingdoms opened their soft-boiled eggs at different ends.

-

See the Wikipedia's +

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

Programmers can usually ignore endianness, except when reading a core @@ -248,7 +248,7 @@ native_to_big_inplace(x);

There will be no performance difference between the two approaches in -release builds, +optimized builds, regardless of the native endianness of the machine. That's because optimizing compilers will generate exactly the same code for each. That conclusion was confirmed by studying the generated assembly code for GCC and Visual C++. Furthermore, time spent doing I/O will determine the speed of this application.

@@ -404,18 +404,18 @@ 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 are smaller. Transfer between systems is less expensive.

-

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.

+

Furthermore, binary arithmetic 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 +resulting files, limit usefulness to applications where the binary I/O +advantages are paramount.

Which is better, big-endian or little-endian?

Big-endian tends to be preferred in a networking environment and is a bit more of an industry standard, but little-endian may be preferred for -applications that run primarily on x86, x64, and other little-endian +applications that run primarily on x86, x86-64, and other little-endian CPU's. The Wikipedia article gives more pros and cons.

@@ -456,7 +456,7 @@ the same code being generated for either types.

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. Systems where integer endianness differs from floating point +point formats. Systems on which integer endianness differs from floating point endianness are not supported.

@@ -467,9 +467,9 @@ endianness are not supported.

Tests have only been performed on machines that use two's complement arithmetic. The Endian -conversion functions support 16, 32, and 64-bit aligned integers only. The -Endian types support 8, 16, 24, 32, 40, 48, 56, and 64-bit unaligned integers -and 16, 32, and 64-bit aligned integers.

+conversion functions only support 16, 32, and 64-bit aligned integers. The +endian types only support 8, 16, 24, 32, 40, 48, 56, and 64-bit unaligned integers, +and 8, 16, 32, and 64-bit aligned integers.

@@ -593,7 +593,7 @@ Blechmann, Tim Moore, tymofey, Tomas Puverle, Vincente Botet, Yuval Ronen and Vitaly Budovsk. Apologies if anyone has been missed.

Last revised: -12 February, 2015

+17 February, 2015

© Copyright Beman Dawes, 2011, 2013

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