From 62943e150e97790e6cceb6da11748f8f8b83275c Mon Sep 17 00:00:00 2001 From: Beman Date: Tue, 12 Aug 2014 10:34:37 -0400 Subject: [PATCH] Do a pass through docs, bringing up to date where needed. --- doc/conversion.html | 12 +- doc/do_list.html | 54 +------- doc/done_list.html | 53 ------- doc/index.html | 327 ++++++++++++++++++++++++++++---------------- doc/types.html | 57 ++++---- doc/vc++readme.txt | 28 ++-- 6 files changed, 271 insertions(+), 260 deletions(-) delete mode 100644 doc/done_list.html diff --git a/doc/conversion.html b/doc/conversion.html index 3e47f40..bd5bfc4 100644 --- a/doc/conversion.html +++ b/doc/conversion.html @@ -88,7 +88,12 @@ namespace boost { namespace endian { - enum class order {big, little, native}; + enum class order + { + big, // big-endian + little, // little-endian + native = implementation-defined // same as order::big or order::little + }; // reverse byte order (i.e. endianness) int8_t reverse_value(int8_t x) noexcept; @@ -151,6 +156,9 @@ namespace endian } // namespace endian } // namespace boost +

The implementation-defined text above is either +big or little according to the endianness of the +platform.

Requirements

The template definitions in this header refer to named requirements whose details are set out in this section. User defined types may @@ -330,7 +338,7 @@ Pierre Talbot provided the int8_t reverse_value() and templated reverse() implementations.

Last revised: -16 April, 2014

+12 August, 2014

© 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/do_list.html b/doc/do_list.html index 5e676b7..e0358c5 100644 --- a/doc/do_list.html +++ b/doc/do_list.html @@ -11,6 +11,9 @@

Endian Library Do List

+ +

August 12, 2014: The many items that have been completed should be +removed, after verifying that they are in fact taken care of.

To Do

Format Review Comments

Votes

@@ -115,7 +111,6 @@

Docs

Infrastructure

-

Performance

-

 

-

Acknowledge

-

Gordon Woodhull, Hartmut Kaiser, Phil Endecott, tymofey, Giovanni Piero Deretta, Pyry Jahkola, -John Filo, Vitaly Budovski, Tomas Puverle, Vicente J. Botet Escriba, Tim -Blechmann, Daniel James, Mathias Gaunard, Adder, Tim Moore

-

Paul Bristow docs help

- -

Floating Point Support

- -

* Because FP formats vary, just dealing with endianness doesn't ensure
-portability.
-* The endianness of FP and integer values differs on some platforms,
-so we will have to build up a config file with separate entries for
-each platform, and that will take time to mature.
-* Ditto FP sizes.
-* I'm only willing to provide conversion.hpp FP support. Providing
+

* I'm only willing to provide conversion.hpp FP support. Providing
types that mimic FP types is far beyond my knowledge of how to deal
with floating point's notorious arithmetic issues.

Support IEEE754 format (32 bit, 64 bit) only.

diff --git a/doc/done_list.html b/doc/done_list.html deleted file mode 100644 index 30e43d0..0000000 --- a/doc/done_list.html +++ /dev/null @@ -1,53 +0,0 @@ - - - - - - - -Endian since formal review - - - - -

Endian changes since formal review

- - -

 

- - - - \ No newline at end of file diff --git a/doc/index.html b/doc/index.html index 265e839..6c6f3c4 100644 --- a/doc/index.html +++ b/doc/index.html @@ -46,7 +46,7 @@ Introduction to endianness
Introduction to the Boost.Endian library
Choosing approaches
- Intrinsic built-in support
+ Built-in support for Intrinsics
Performance
    Timings
    Conclusions
@@ -65,23 +65,15 @@ - - - - -
Heads up: As development has continues, there have been breaking - changes. Most recently, the endian types were - renamed.
-

Abstract

Boost.Endian provides facilities to manipulate the endianness of integers, floating point, and user defined data.

-

Intrinsic built-in support

-

Recent compilers, including GCC, Clang, and Microsoft, supply intrinsic -built-in support for byte swapping. Such support is automatically detected and +

Built-in support for Intrinsics

+

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

-

Defining BOOST_ENDIAN_NO_INTRINSICS will suppress use +

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 +

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.

@@ -267,9 +260,10 @@ big_endian(x); -

There will be no performance difference between the two approaches, -regardless of the native endianness of the machine. Optimizing compilers will likely -generate exactly the same code for both. That conclusion was confirmed by +

There will be no performance difference between the two approaches in +release builds, +regardless of the native endianness of the machine. That's because optimizing compilers will likely +generate exactly the same code for each. That conclusion was confirmed by studying the generated assembly code for GCC and Visual C++.

Now consider a slightly different problem: 

@@ -337,84 +331,180 @@ setup. 32-bit intrinsics.)

- - - - - + + + + + - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - - + + + + - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
GNU C++ version 4.7.0
Iterations: 1000000000, Intrinsics: __builtin_bswap16, etc.
Test CaseEndian
type		Endian
conversion
function
GNU C++ version 4.7.0
Iterations: 1000000000, Intrinsics: __builtin_bswap16, etc.
Test CaseEndian
type		Endian
conversion
function
16-bit aligned big endian1.37 s0.81 s
16-bit aligned little endian0.83 s0.81 s
16-bit unaligned big endian1.09 s0.83 s
16-bit unaligned little endian1.09 s0.81 s
32-bit aligned big endian0.98 s0.27 s
32-bit aligned little endian0.28 s0.27 s
32-bit unaligned big endian3.82 s0.27 s
32-bit unaligned little endian3.82 s0.27 s
64-bit aligned big endian1.65 s0.41 s
64-bit aligned little endian0.41 s0.41 s
64-bit unaligned big endian17.53 s0.41 s
64-bit unaligned little endian17.52 s0.41 s
16-bit aligned big endian1.37 s0.81 s
16-bit aligned little endian0.83 s0.81 s
16-bit unaligned big endian1.09 s0.83 s
16-bit unaligned little endian1.09 s0.81 s
32-bit aligned big endian0.98 s0.27 s
32-bit aligned little endian0.28 s0.27 s
32-bit unaligned big endian3.82 s0.27 s
32-bit unaligned little endian3.82 s0.27 s
64-bit aligned big endian1.65 s0.41 s
64-bit aligned little endian0.41 s0.41 s
64-bit unaligned big endian17.53 s0.41 s
64-bit unaligned little endian17.52 s0.41 s
Iterations: 1000000000, Intrinsics: no byte swap intrinsics
Test CaseEndian
type		Endian
conversion
function
Iterations: 1000000000, Intrinsics: no byte swap intrinsics
Test CaseEndian
type		Endian
conversion
function
16-bit aligned big endian1.95 s0.81 s
16-bit aligned little endian0.83 s0.81 s
16-bit unaligned big endian1.19 s0.81 s
16-bit unaligned little endian1.20 s0.81 s
32-bit aligned big endian0.97 s0.28 s
32-bit aligned little endian0.27 s0.28 s
32-bit unaligned big endian4.10 s0.27 s
32-bit unaligned little endian4.10 s0.27 s
64-bit aligned big endian1.64 s0.42 s
64-bit aligned little endian0.41 s0.41 s
64-bit unaligned big endian17.52 s0.42 s
64-bit unaligned little endian17.52 s0.41 s
16-bit aligned big endian1.95 s0.81 s
16-bit aligned little endian0.83 s0.81 s
16-bit unaligned big endian1.19 s0.81 s
16-bit unaligned little endian1.20 s0.81 s
32-bit aligned big endian0.97 s0.28 s
32-bit aligned little endian0.27 s0.28 s
32-bit unaligned big endian4.10 s0.27 s
32-bit unaligned little endian4.10 s0.27 s
64-bit aligned big endian1.64 s0.42 s
64-bit aligned little endian0.41 s0.41 s
64-bit unaligned big endian17.52 s0.42 s
64-bit unaligned little endian17.52 s0.41 s

- - - - - - +
Microsoft Visual C++ version 11.0
Iterations: 1000000000, Intrinsics: cstdlib _byteswap_ushort, etc.
Test CaseEndian
type		Endian
conversion
function
+ + + + + - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - - + + + + - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Microsoft Visual C++ version 11.0
Iterations: 1000000000, Intrinsics: cstdlib _byteswap_ushort, etc.
Test CaseEndian
type		Endian
conversion
function
16-bit aligned big endian0.83 s0.51 s
16-bit aligned little endian0.51 s0.50 s
16-bit unaligned big endian1.37 s0.51 s
16-bit unaligned little endian1.37 s0.50 s
32-bit aligned big endian0.81 s0.50 s
32-bit aligned little endian0.51 s0.51 s
32-bit unaligned big endian2.98 s0.53 s
32-bit unaligned little endian3.00 s0.51 s
64-bit aligned big endian1.33 s0.33 s
64-bit aligned little endian0.34 s0.27 s
64-bit unaligned big endian7.05 s0.33 s
64-bit unaligned little endian7.11 s0.31 s
16-bit aligned big endian0.83 s0.51 s
16-bit aligned little endian0.51 s0.50 s
16-bit unaligned big endian1.37 s0.51 s
16-bit unaligned little endian1.37 s0.50 s
32-bit aligned big endian0.81 s0.50 s
32-bit aligned little endian0.51 s0.51 s
32-bit unaligned big endian2.98 s0.53 s
32-bit unaligned little endian3.00 s0.51 s
64-bit aligned big endian1.33 s0.33 s
64-bit aligned little endian0.34 s0.27 s
64-bit unaligned big endian7.05 s0.33 s
64-bit unaligned little endian7.11 s0.31 s
Iterations: 1000000000, Intrinsics: no byte swap intrinsics
Test CaseEndian
type		Endian
conversion
function
Iterations: 1000000000, Intrinsics: no byte swap intrinsics
Test CaseEndian
type		Endian
conversion
function
16-bit aligned big endian0.83 s0.51 s
16-bit aligned little endian0.51 s0.51 s
16-bit unaligned big endian1.36 s0.51 s
16-bit unaligned little endian1.37 s0.51 s
32-bit aligned big endian3.42 s0.50 s
32-bit aligned little endian0.51 s0.51 s
32-bit unaligned big endian2.93 s0.50 s
32-bit unaligned little endian2.95 s0.50 s
64-bit aligned big endian5.99 s0.33 s
64-bit aligned little endian0.33 s0.33 s
64-bit unaligned big endian7.02 s0.27 s
64-bit unaligned little endian7.02 s0.27 s
16-bit aligned big endian0.83 s0.51 s
16-bit aligned little endian0.51 s0.51 s
16-bit unaligned big endian1.36 s0.51 s
16-bit unaligned little endian1.37 s0.51 s
32-bit aligned big endian3.42 s0.50 s
32-bit aligned little endian0.51 s0.51 s
32-bit unaligned big endian2.93 s0.50 s
32-bit unaligned little endian2.95 s0.50 s
64-bit aligned big endian5.99 s0.33 s
64-bit aligned little endian0.33 s0.33 s
64-bit unaligned big endian7.02 s0.27 s
64-bit unaligned little endian7.02 s0.27 s
@@ -487,9 +577,9 @@ paramount.

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

-

Big-endian tends to be a -bit more of an industry standard, but little-endian may be preferred for -applications that run primarily Intel/AMD on x86, x64, and other 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 CPU's. The Wikipedia article gives more pros and cons.

@@ -498,7 +588,7 @@ gives more pros and cons.

These are the only endian schemes that have any practical value today. PDP-11 and the other middle endian approaches are interesting historical curiosities -but have no relevance to C++ developers.

+but have no relevance to today's C++ developers.

What are the limitations of floating point support?

@@ -541,7 +631,7 @@ and 16, 32, and 64-bit aligned integers.

  • Both return-by-value and modify-in-place interfaces are provided, as requested.
  • Synonyms for the BSD byte swapping function names popularized by OS X - and Linux are provided, so that that developers already used to these name + and Linux are provided, so that that developers already used to these names can continue to use them if they wish.
  • In addition to the named-endianness functions, functions that perform compile-time (via template) and run-time (via function argument) dispatch @@ -553,13 +643,20 @@ and 16, 32, and 64-bit aligned integers.

  • For the endian types, the implementation uses the endian conversion functions, and thus the intrinsics, as requested.
    • +
  • order::native is now a synonym for order::big + or order::little according to the endianness of the platform, as + requested. This reduces the number of template specializations required.
    • +
  • reverse_value() overloads for int8_t and + uint8_t have been added for improved generality. (Pierre Talbot)
    • +
  • Overloads of reverse() have been replaced with a single + reverse() template. (Pierre Talbot)
  • C++11 features such as noexcept are now used, while still supporting C++03 compilers.
    • -
  • Acknowledgements have been updated.
  • Headers have been reorganized to make them easier to read, with a synopsis at the front and implementation following, as requested.
  • Documentation has been revised to address most, but not all, concerns raised during formal review.
    • +
  • Acknowledgements have been updated.

    • Acknowledgements

    @@ -573,7 +670,7 @@ Blechmann, Tim Moore, tymofey, Tomas Puverle, Vincente Botet, Yuval Ronen and Vitaly Budovski,.

    Last revised: -16 April, 2014

    +12 August, 2014

    © 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 c982ef0..3fb31ef 100644 --- a/doc/types.html +++ b/doc/types.html @@ -207,6 +207,7 @@ will no longer be relying on unspecified behavior.

    Two scoped enums are provided:

    enum class order {big, little, native};
+
 enum class align {no, yes};

    One class template is provided:

    @@ -349,7 +350,13 @@ usual operations on integers are supplied.

    { // C++11 features emulated if not available - enum class order {big, little, native}; + enum class order + { + big, // big-endian + little, // little-endian + native = implementation-defined // same as order::big or order::little + }; + enum class align {no, yes}; template <order Order, typename T, std::size_t n_bits, align A = align::no> @@ -467,28 +474,31 @@ usual operations on integers are supplied.

    typedef endian<order::little, uint_least64_t, 56> little_uint56_t; typedef endian<order::little, uint_least64_t, 64> little_uint64_t; - // unaligned native endian signed integer types - typedef endian<order::native, int_least8_t, 8> native_int8_t; - typedef endian<order::native, int_least16_t, 16> native_int16_t; - typedef endian<order::native, int_least32_t, 24> native_int24_t; - typedef endian<order::native, int_least32_t, 32> native_int32_t; - typedef endian<order::native, int_least64_t, 40> native_int40_t; - typedef endian<order::native, int_least64_t, 48> native_int48_t; - typedef endian<order::native, int_least64_t, 56> native_int56_t; - typedef endian<order::native, int_least64_t, 64> native_int64_t; - - // unaligned native endian unsigned integer types - typedef endian<order::native, uint_least8_t, 8> native_uint8_t; - typedef endian<order::native, uint_least16_t, 16> native_uint16_t; - typedef endian<order::native, uint_least32_t, 24> native_uint24_t; - typedef endian<order::native, uint_least32_t, 32> native_uint32_t; - typedef endian<order::native, uint_least64_t, 40> native_uint40_t; - typedef endian<order::native, uint_least64_t, 48> native_uint48_t; - typedef endian<order::native, uint_least64_t, 56> native_uint56_t; - typedef endian<order::native, uint_least64_t, 64> native_uint64_t; + // unaligned native endian signed integer types + typedef implementation-defined_int8_t native_int8_t; + typedef implementation-defined_int16_t native_int16_t; + typedef implementation-defined_int24_t native_int24_t; + typedef implementation-defined_int32_t native_int32_t; + typedef implementation-defined_int40_t native_int40_t; + typedef implementation-defined_int48_t native_int48_t; + typedef implementation-defined_int56_t native_int56_t; + typedef implementation-defined_int64_t native_int64_t; + + // unaligned native endian unsigned integer types + typedef implementation-defined_uint8_t native_uint8_t; + typedef implementation-defined_uint16_t native_uint16_t; + typedef implementation-defined_uint24_t native_uint24_t; + typedef implementation-defined_uint32_t native_uint32_t; + typedef implementation-defined_uint40_t native_uint40_t; + typedef implementation-defined_uint48_t native_uint48_t; + typedef implementation-defined_uint56_t native_uint56_t; + typedef implementation-defined_uint64_t native_uint64_t; } // namespace endian } // namespace boost +

    The implementation-defined text above is either +big or little according to the endianness of the +platform.

    Members

    endian() = default;  // C++03: endian(){}
    @@ -568,13 +578,10 @@ incrementing a variable in a record. It is very convenient to write:

    representation) regardless of whether a compiler treats char as signed or unsigned.
  • Unaligned types must not cause compilers to insert padding bytes.
    • -
  • The implementation should supply optimizations only in very limited - circumstances. Experience has shown that optimizations of endian +
  • The implementation should supply optimizations with great care. Experience has shown that optimizations of endian integers often become pessimizations when changing machines or compilers. Pessimizations can also happen when changing compiler switches, compiler versions, or CPU models of the same architecture.
    • -
  • It is better software engineering if the same implementation works regardless - of the CPU endianness. In other words, #ifdefs should be avoided in user code.

    • Experience

    Classes with similar functionality have been independently developed by @@ -621,7 +628,7 @@ differs from endian representation size. Vicente Botet and other reviewers suggested supporting floating point types.

    Last revised: -06 September, 2013

    +12 August, 2014

    © 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/vc++readme.txt b/doc/vc++readme.txt index fdd44e5..88ea31c 100644 --- a/doc/vc++readme.txt +++ b/doc/vc++readme.txt @@ -3,30 +3,28 @@ Windows Prerequisites -BOOST_TRUNK environmental variable set to the path to a current Boost trunk checkout. -Example: - - setx BOOST_TRUNK=c:\boost\trunk - -Boost libraries available in %BOOST_TRUNK%\stage\lib. Example: +Boost libraries available in boost-root\stage\lib. Example: - cd %BOOST_TRUNK% + cd boost-root .\bootstrap .\b2 --with-system --with-chrono --with-timer link=shared stage -path environmental variable set to include %BOOST_TRUNK%\stage\lib. Example: +The provided Visual Studio solution (endian/test/msvc/endian.sln) has a property page +(endian/test/msvc/common.prop) with these Common Properties set (do not include the +double quotes): + + VC++ Directores|Executable Directories: prefix default value with "..\..\..\..\..\stage\lib;" + (Click "Inherit from parent or project defaults" if not checked) + + C/C++|General|Additional Include Directories: prefix default value with "..\..\..\..\..\stage\lib;" - path %path%;%BOOST_TRUNK%\stage\lib + Linker|General|Additional Library Directories: prefix default value with "..\..\..\..\..\stage\lib;" -The provided Visual Studio solution (endian/test/msvc2012/endian.sln) has these Property -setups: - -C/C++|General|Additional Include Directories: prefix ..\..\..\..\endian\include;$(BOOST_TRUNK); -C/C++|Preprocessor: prefix BOOST_ALL_DYN_LINK; -Linker|General|Additional Library Directories: $(BOOST_TRUNK)\stage\lib + C/C++|Preprocessor: prefix default value with "BOOST_ALL_DYN_LINK;" IMPORTANT: If Preprocessor macros are supplied via a common property page, must be set for each project! + ------------------------------------------------------------------------------------------ Copyright Beman Dawes, 2013 Distributed under the Boost Software License, Version 1.0.