From 0b4566731af148805078d513cc17c7df3ad4a7ad Mon Sep 17 00:00:00 2001 From: bemandawes Date: Sat, 3 Sep 2011 21:33:34 +0000 Subject: [PATCH] Continue to refine the docs git-svn-id: http://svn.boost.org/svn/boost/sandbox/endian@74216 b8fc166d-592f-0410-95f2-cb63ce0dd405 --- libs/endian/doc/index.html | 205 ++++++++++--------------------------- libs/endian/doc/types.html | 21 +--- 2 files changed, 55 insertions(+), 171 deletions(-) diff --git a/libs/endian/doc/index.html b/libs/endian/doc/index.html index 34ff36c..c69f26e 100644 --- a/libs/endian/doc/index.html +++ b/libs/endian/doc/index.html @@ -30,170 +30,71 @@ -

Introduction

- -

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_t or little64_t.

- -
- -

Boost Endian is header-only library.

-

Introduction to endianness

-

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 EndianLittle Endian
Value0A0BValue0B0A
Address...0...1Address...0...1
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int32_t y = 0x0A0B0C0D;
Big EndianLittle Endian
Value0A0B0C0DValue0D0C0B0A
Address...0...1...2...3Address...0...1...2...3
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int64_t z = 0x0A0B0C0D0E0F0102;
Big EndianLittle Endian
Value0A0B0C0D0E0F0102Value02010F0E0D0C0B0A
Address...0...1...2...3...4...5...6...7Address...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.

+

Introduction to the Boost Endian Library

-

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_t or little64_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.

Acknowledgements

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