The Boost Endian Library provides facilities to deal with integer endianness. See -Introduction to endianness below for -the basics of endianness.
- -The library provides two approaches to dealing with integer endianness:
- -- -- -Endian conversions for native integers - With this approach, the application uses the -built-in integer types, and calls the provided conversion functions to convert -byte ordering as needed. Both mutating and non-mutating conversions are supplied, and -each comes in unconditional and conditional variants. This approach is simple -and efficient, but is less flexible in terms of size and alignment, and can be -hard-to-manage and error-prone in code with many logical paths involving endianness transitions.
- -Endian integer types - With this approach, the application uses the -provided endian classes which mimic the -built-in integer types. For example,
- -big32_torlittle64_t.
Boost Endian is header-only library.
-Consider a C++ program that defines variables x, y, and z as 16, 32, and -64-bit integers, respectively. There are several ways a processor might layout -the individual bytes for these variables in memory:
- -| int16_t x = 0x0A0B; | -|||||
| Big Endian | -Little Endian | -||||
| Value | -0A | -0B | -Value | -0B | -0A | -
| Address | -...0 | -...1 | -Address | -...0 | -...1 | -
| int32_t y = 0x0A0B0C0D; | -|||||||||
| Big Endian | -Little Endian | -||||||||
| Value | -0A | -0B | -0C | -0D | -Value | -0D | -0C | -0B | -0A | -
| Address | -...0 | -...1 | -...2 | -...3 | -Address | -...0 | -...1 | -...2 | -...3 | -
| int64_t z = 0x0A0B0C0D0E0F0102; | -|||||||||||||||||
| Big Endian | -Little Endian | -||||||||||||||||
| Value | -0A | -0B | -0C | -0D | -0E | -0F | -01 | -02 | -Value | -02 | -01 | -0F | -0E | -0D | -0C | -0B | -0A | -
| Address | -...0 | -...1 | -...2 | -...3 | -...4 | -...5 | -...6 | -...7 | -Address | -...0 | -...1 | -...2 | -...3 | -...4 | -...5 | -...6 | -...7 | -
Consider the following code:
+
+ int16_t i = 0x0102;
+FILE * file = fopen("test", "wb"); // MUST BE BINARY
+fwrite(&i, sizeof(int16_t), 1, file);
+fclose(file);
+
+On a modern Apple, Linux, or Windows computer with an Intel CPU, a hex dump +of the "test" output file produces:
++++
0201
On a Oracle/Sun Solaris computer with a SPARC CPU, a hex dump of the "test" +output file produces:
++++
0102
What's happening here is that Intel CPU's order the bytes of an integer with +the least-significant byte first, while SPARC CPU's place the most-significant +byte first. Some CPU's, such as the PowerPC, allow the operating system to +choose which ordering applies.
The most-significant byte first ordering is traditionally called "big endian" ordering and the least-significant byte first is traditionally called -"little-endian" ordering. Although some other orderings are possible, most -modern uses are as shown above. The names are derived from +"little-endian" ordering. The names are derived from Jonathan Swift's satirical novel Gulliver’s Travels, where rival kingdom's opened their soft-boiled eggs at different ends.
+For a more complete introduction to endianness, see the Wikipedia's +Endianness article.
+Except for reading an occasional core dump, most programmers can ignore +endianness. But when exchanging data with other computer systems, whether by +file transfers or over a network, programmers have to deal with endianness when +binary data is involved.
+Intel processors are traditionally little endian while many others are big -endian. Some processors can switch endianness, so which is in use depends on the -operating system. The Wikipedia's -Endianness entry lists -details for many processors and operating systems.
+The Boost Endian Library provides facilities to deal with integer endianness.
+ +The library provides two approaches to dealing with integer endianness:
+ ++ ++ +Endian conversions for native integers - The application uses the +built-in integer types, and calls the provided conversion functions to convert +byte ordering as needed. Both mutating and non-mutating conversions are supplied, and +each comes in unconditional and conditional variants. This approach is simple +and usually more efficient, but is less flexible in terms of size and alignment, can be +hard-to-manage and error-prone in code with many logical paths involving endianness transitions, +and can foster very hard to debug logic errors.
+ +Endian integer types - The application uses the provided endian types +which mimic the +built-in integer types. For example,
+ +big32_torlittle64_t. +This approach is also simple, but can be less efficient. Types with lengths of +1-8 bytes are supported, rather than just 1, 2, 4, and 8 bytes. Strict alignment +requirements are avoided, and this may allow data to be packed more tightly.
Boost Endian is a header-only library.
-External memory, such as disks, generally uses the same endianness as the -operating system. Networks traditionally use big endian ordering, so this is -sometimes referred as network endianness.
Comments and suggestions were received from diff --git a/libs/endian/doc/types.html b/libs/endian/doc/types.html index bcb9ef9..444e68a 100644 --- a/libs/endian/doc/types.html +++ b/libs/endian/doc/types.html @@ -634,29 +634,12 @@ any Boost object libraries.
Original design developed by Darin Adler based on classes developed by Mark
Borgerding. Four original class templates combined into a single endian
class template by Beman Dawes, who put the library together, provided
-documentation, and added the typedefs. He also added the unrolled_byte_loops
+documentation, added the typedefs, and also added the unrolled_byte_loops
sign partial specialization to correctly extend the sign when cover integer size
differs from endian representation size.
Comments and suggestions were -received from -Benaka Moorthi, -Christopher Kohlhoff, -Cliff Green, -Gennaro Proto, -Giovanni Piero Deretta, dizzy, Jeff Flinn, -John Maddock, -Kim Barrett, -Marsh Ray, -Martin Bonner, -Matias Capeletto, -Neil Mayhew, Phil Endecott, Rene Rivera, -Roland Schwarz, Scott McMurray, -Sebastian Redl, -Tomas Puverle, Vincente Botet, and -Yuval Ronen.
Last revised: -27 May, 2011
+03 September, 2011© Copyright Beman Dawes, 2006-2009
Distributed under the Boost Software License, Version 1.0. See www.boost.org/ LICENSE_1_0.txt