From d0dc573ec168c1311a2ebce0bb6b8032ddc38f6f Mon Sep 17 00:00:00 2001 From: Beman Date: Mon, 16 Feb 2015 19:28:11 -0500 Subject: [PATCH] Refer to endian type size in terms of bits, for consistency with names (e.g. big_int40_ut is 40-bits, not 40-bytes). Add example to "Does endianness have any uses outside of ...". --- doc/index.html | 44 +++++++++++++++++++++++++++----------------- 1 file changed, 27 insertions(+), 17 deletions(-) diff --git a/doc/index.html b/doc/index.html index 9c99dc0..9f92ac5 100644 --- a/doc/index.html +++ b/doc/index.html @@ -118,7 +118,7 @@ the least-significant byte first, while SPARC CPUs place the most-significant byte first. Some CPUs, such as the PowerPC, allow the operating system to choose which ordering applies.

Most-significant-byte-first ordering is traditionally called "big endian" -ordering and the least-significant-byte-first is traditionally called +ordering and least-significant-byte-first is traditionally called "little-endian" ordering. The names are derived from Jonathan Swift's satirical novel @@ -135,7 +135,7 @@ And programmers may also want to use the library when minimizing either internal external data sizes is advantageous.

Introduction to the Boost.Endian library

-

The Boost.Endian library provides three different approaches to dealing with +

Boost.Endian provides three different approaches to dealing with endianness. All three approaches support integers, floating point types except  long double, and user-define types (UDTs).

@@ -154,15 +154,22 @@ conditional variants.

Endian buffer types - The application uses the provided endian buffer types to hold values, and explicitly converts to and from the built-in integer and -floating point types to perform arithmetic. Buffer lengths of 1 through 8 bytes -are supported, rather than just 2, 4, and 8 bytes. The types may be aligned or -unaligned.

+floating point types. Buffer sizes of 8, 16, 24, 32, 40, 48, 56, and 64 bits (i.e. +1, 2, 3, 4, 5, 6, 7, and 8 bytes) are provided. Unaligned integer buffer types +are provided for all sizes, unaligned floating point buffer types are provided +for 32 and 64 bit sizes, and aligned buffer types are provided for 16, 32, and +64-bit sizes. The provided specific types are typedefs for a generic class +template that may be used directly for less common use cases.

-

Endian arithmetic types - The application uses the provided endian -arithmetic types, which supply the same operations as the built-in C++ -arithmetic types. All conversions are implicit. Arithmetic integer types with -lengths of 1 through 8 bytes are supported, rather than just 2, 4, and 8 byte -integers. The types may be aligned.

+

Endian arithmetic types - The +application uses the provided endian arithmetic types, which supply the same +operations as the built-in C++ arithmetic types. All conversions are implicit. +Arithmetic sizes of 8, 16, 24, 32, 40, 48, 56, and 64 bits (i.e. 1, 2, 3, 4, 5, +6, 7, and 8 bytes) are provided. Unaligned integer types are provided for all +sizes, unaligned floating point types are provided for 32 and 64 bit sizes, and aligned +arithmetic types are provided for 16, 32, and 64-bit sizes. The provided +specific types are typedefs for a generic class template that may be used +directly for less common use cases.

@@ -178,15 +185,16 @@ Choosing the Approach page.

Built-in support for Intrinsics

Most compilers, including GCC, Clang, and Visual C++, supply built-in support for byte swapping intrinsics. -The Endian library uses these intrinsics when available since they may result in smaller and faster generated code, particularly for release +The Endian library uses these intrinsics when available since they may result in smaller and faster generated code, particularly for +optimized builds.

Defining the macro BOOST_ENDIAN_NO_INTRINSICS will suppress use -of the intrinsics. Useful when intrinsic headers such as -byteswap.h are not being found by your compiler, perhaps because it +of the intrinsics. This is useful when a compiler has no intrinsic support or +fails to locate the appropriate header, perhaps because it is an older release or has very limited supporting libraries.

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. Useful for eliminating missing +particular set of intrinsics being used. This is useful for eliminating missing intrinsics as a source of performance issues.

Performance

@@ -385,8 +393,10 @@ setup.

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

-

Using the unaligned integer types to save internal or external -memory space is a minor secondary use.

+

Using the unaligned integer types with a size tailored to the application's +needs is a minor secondary use that saves internal or external memory space. For +example, using big_int40_buf_ut or big_int40_ut in a +large array saves a lot of space compared to one of the 64-bit types.

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

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

Last revised: -09 February, 2015

+12 February, 2015

© Copyright Beman Dawes, 2011, 2013

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