diff --git a/arithmetic.html b/arithmetic.html index be79f3c..848bf3c 100644 --- a/arithmetic.html +++ b/arithmetic.html @@ -1,4 +1,4 @@ - + @@ -17,7 +17,7 @@ -boost.png (6897 bytes) +Boost logo Endian Arithmetic Types diff --git a/bikeshed.txt b/bikeshed.txt index 67dbce1..da17001 100644 --- a/bikeshed.txt +++ b/bikeshed.txt @@ -70,6 +70,10 @@ flip (verb) : to move (something) with a quick light movement +-------------------------------------------------- +Copyright Beman Dawes, 2014 +Distributed under the Boost Software License, Version 1.0. +See www.boost.org/LICENSE_1_0.txt \ No newline at end of file diff --git a/buffers.html b/buffers.html index 6007965..e171fbb 100644 --- a/buffers.html +++ b/buffers.html @@ -17,7 +17,7 @@ -boost.png (6897 bytes) +Boost logo Endian Buffer Types diff --git a/conversion.html b/conversion.html index 9e9e92f..5ea86b5 100644 --- a/conversion.html +++ b/conversion.html @@ -1,4 +1,4 @@ - + @@ -15,7 +15,7 @@ -boost.png (6897 bytes) +Boost logo Endian Conversion Functions diff --git a/index.html b/index.html index 4a25bd1..0ccac4e 100644 --- a/index.html +++ b/index.html @@ -15,7 +15,7 @@ -boost.png (6897 bytes) +Boost logo Endian Library @@ -39,17 +39,31 @@ - Abstract
- Introduction to endianness
- Introduction to the Boost.Endian library
- Choosing approaches
- Built-in support for Intrinsics
- Performance
-    Timings
-    Conclusions
- FAQ
- Release history
- Acknowledgements +Abstract
+Introduction to endianness
+Introduction to the Boost.Endian library
+Choosing between conversion, buffer types,
+ and arithmetic types
+   Characteristics
+      Endianness invariants
+      Conversion explicitness
+      Arithmetic operations
+      Sizes
+      Alignments
+   Use cases
+      Porting endian unaware codebase
+      Porting endian aware codebase
+      Reliability and arithmetic-speed
+      Reliability and ease-of-use
+Built-in support for Intrinsics
+Performance
+   Timings for Example 2
+   Conclusions
+Overall FAQ
+Release history
+   Changes since formal review
+Acknowledgements
+ @@ -77,20 +91,23 @@ floating point numbers, and user-defined types.

  • Program portability. POSIX-based and Windows-based operating systems traditionally supply libraries with non-portable functions to perform endian conversion. There are at least four - non-compatible sets of functions in common use. The Endian library is + incompatible sets of functions in common use. The Endian library is portable across all C++ platforms.
     
    • -
  • Secondary use case: Minimizing storage size via sizes and/or alignments not supported by the +
  • Secondary use case: Minimizing data size via sizes and/or alignments not supported by the standard C++ arithmetic types.

    • -
  • Three approaches to dealing with endianness are provided. Each approach has a +
  • Three approaches to dealing with endianness are supported. Each has a long history of successful use, and each approach has use cases where it is preferred over the other approaches.
    • +

     

    +

     

    +

    Introduction to endianness

    Consider the following code:

    @@ -166,20 +183,25 @@ integers. The types may be aligned.

    Boost Endian is a header-only library.

    -

    Choosing between endian conversion functions, endian buffer types, -and endian arithmetic types

    +

    Choosing between conversion functions, buffer types, +and arithmetic types

    -

    The best approach to endianness depends on interaction between +

    The best approach to endianness for a particular use case depends on interactions between the approach characteristics and the application needs.

    -

    Approach characteristics

    +

    Recommendation: If you are uncertain, new to endianness, concerned +about security, concerned about reliability, or don't want to invest time making +engineering trade-offs, use the endian arithmetic types. They are safer, easier +to use, and your code will be easier to maintain.

    -

    The characteristics that differentiate the approaches are the endianness +

    Characteristics

    + +

    The characteristics that differentiate the three approaches to endianness are the endianness invariants, conversion explicitness, arithmetic operations, sizes available, and alignment requirements.

    -

    Endianness invariants

    +

    Endianness invariants

    @@ -193,11 +215,11 @@ find bugs.

    Endian buffer and arithmetic types hold values internally as arrays of characters with an invariant that the endianness of the array never changes. -That makes these types easy to use and programs easy to maintain.

    +That makes these types easier to use and programs easier to maintain.

    -

    Conversion explicitness

    +

    Conversion explicitness

    @@ -211,7 +233,7 @@ to hoist conversions out of inner loops can bring a performance penalty.

    -

    Arithmetic operations

    +

    Arithmetic operations

    @@ -228,7 +250,7 @@ are very easy to use if lots of arithmetic is involved.

    -

    Sizes available

    +

    Sizes

    @@ -241,7 +263,7 @@ factor, using sizes tailored to application needs can be useful.

    -

    Alignments available

    +

    Alignments

    @@ -272,9 +294,24 @@ needed they are often very useful and workarounds are painful. For example,

    Use cases

    -

    Program portability use case

    +

    Porting endian unaware codebase

    -

    An existing large codebase runs on little-endian Linux systems. It already +

    An existing codebase runs on big endian systems. It does not +currently deal with endianness. The codebase needs to be modified so it can run +on  little endian systems under various operating systems. To ease +transition and protect value of existing files, external data will continue to +be maintained as big endian.

    + +

    The endian +arithmetic approach is recommended to meet these needs. A relatively small +number of header files dealing with binary I/O layouts need to change types like +short or int16_t to big_int16_t, and +int or int32_t to bif_int32_t. No +changes are required for .cpp files.

    + +

    Porting endian aware codebase

    + +

    An existing codebase runs on little-endian Linux systems. It already deals with endianness via Linux provided functions. Because of a business merger, the codebase has to be quickly @@ -282,12 +319,12 @@ modified for Windows and possibly other operating systems, while still supporting Linux. The codebase is reliable and the programmers are all well-aware of endian issues.

    -

    These factors all argue for an endian conversion +

    These factors all argue for an endian conversion approach that just mechanically changes the calls to htobe32, etc. to boost::endian::native_to_big, etc. and replaces <endian.h> with <boost/endian/conversion.hpp>.

    -

    Reliability and arithmetic-speed use case

    +

    Reliability and arithmetic-speed

    A new, complex, multi-threaded application is to be developed that must run on little endian machines, but do big endian network I/O. The developers believe @@ -299,7 +336,7 @@ slow conversions if full-blown endian arithmetic types are used.

    The endian buffers approach is made-to-order for this use case.

    -

    Reliability and ease-of-use use case

    +

    Reliability and ease-of-use

    A new, complex, multi-threaded application is to be developed that must run on little endian machines, but do big endian network I/O. The developers believe @@ -640,7 +677,7 @@ determine if some coding technique has significant impact on performance.

    Unaligned types are much slower that aligned types, regardless of endianness considerations. Instead of single instruction register loads and -stores, multiple instructions are required.

    +stores, multiple instructions are required on common platforms.

    @@ -727,7 +764,7 @@ and 16, 32, and 64-bit aligned integers.

    Release history

    -

    Changes since formal review

    +

    Changes since formal review