diff --git a/doc/index.html b/doc/index.html index c48679f..6cde0db 100644 --- a/doc/index.html +++ b/doc/index.html @@ -83,7 +83,7 @@ floating point numbers, and user-defined types.

-
  • 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 @@ -169,13 +169,18 @@ integers. The types may be aligned.

    Choosing between endian conversion functions, endian buffer types, and endian 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.

    +

    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.

    +

    Approach characteristics

    -

    The characteristics that differentiate the approaches are the endianness +

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

    @@ -193,7 +198,7 @@ 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.

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

    Use cases

    -

    Program portability use case

    +

    Porting endian aware codebase

    -

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

    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,11 +287,26 @@ 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>.

    +

    Porting endian unaware codebase

    + +

    An existing codebase runs on expensive big endian systems. It does not +currently deal with endianness. The codebase needs to be modified so it can run +on lower-cost 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 little_int16_t, and +int or int32_t to little_int32_t. No +changes are required for .cpp files.

    +

    Reliability and arithmetic-speed use case

    A new, complex, multi-threaded application is to be developed that must run