Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r74216 - sandbox/endian/libs/endian/doc
From: bdawes_at_[hidden]
Date: 2011-09-03 17:33:35

Author: bemandawes
Date: 2011-09-03 17:33:34 EDT (Sat, 03 Sep 2011)
New Revision: 74216
URL: http://svn.boost.org/trac/boost/changeset/74216

Log:
Continue to refine the docs
Text files modified:
   sandbox/endian/libs/endian/doc/index.html | 203 ++++++++++-----------------------------
   sandbox/endian/libs/endian/doc/types.html | 21 ---
   2 files changed, 54 insertions(+), 170 deletions(-)

Modified: sandbox/endian/libs/endian/doc/index.html
==============================================================================
--- sandbox/endian/libs/endian/doc/index.html (original)
+++ sandbox/endian/libs/endian/doc/index.html 2011-09-03 17:33:34 EDT (Sat, 03 Sep 2011)
@@ -30,170 +30,71 @@
</tr>
</table>

-<h2><a name="Introduction">Introduction</a></h2>
+<h2><a name="Introduction-to-endianness">Introduction to endianness</a></h2>
+
+Consider the following code:
+
+<blockquote>
+ <pre>int16_t i = 0x0102;
+FILE * file = fopen("test", "wb"); // MUST BE BINARY
+fwrite(&i, sizeof(int16_t), 1, file);
+fclose(file);</pre>
+</blockquote>
+On a modern Apple, Linux, or Windows computer with an Intel CPU, a hex dump
+of the "test" output file produces:
+<blockquote>
+ <code>0201</code>
+</blockquote>
+On a Oracle/Sun Solaris computer with a SPARC CPU, a hex dump of the "test"
+output file produces:
+<blockquote>
+ <code>0102</code>
+</blockquote>
+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. The names are derived from
+<a href="http://en.wikipedia.org/wiki/Jonathan_Swift" title="Jonathan Swift">
+Jonathan Swift</a>'s satirical novel 
+<a href="http://en.wikipedia.org/wiki/Gulliver's_Travels" title="Gulliver's Travels">
+Gulliver’s Travels</a>, 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.
+<h2><a name="Introduction">Introduction</a> to the Boost Endian Library</h2>

-The Boost Endian Library provides facilities to deal with integer endianness. See
-Introduction to endianness below for
-the basics of endianness.
+The Boost Endian Library provides facilities to deal with integer endianness.

The library provides two approaches to dealing with integer endianness:

<blockquote>

-Endian conversions for native integers - With this approach, the application uses the
+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 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, <code>big32_t</code> or <code>little64_t</code>. 
+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, <code>big32_t</code> or <code>little64_t</code>.
+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.

</blockquote>

-Boost Endian is header-only library.
-
-<h2><a name="Introduction-to-endianness">Introduction to endianness</a></h2>
-
-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:
-
-<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
- <tr>
- <td colspan="6" align="center">int16_t x = 0x0A0B;</td>
- </tr>
- <tr>
- <td colspan="3" align="center">Big Endian</td>
- <td colspan="3" align="center">Little Endian</td>
- </tr>
- <tr>
- <td>Value</td>
- <td align="center">0A</td>
- <td align="center">0B</td>
- <td>Value</td>
- <td align="center">0B</td>
- <td align="center">0A</td>
- </tr>
- <tr>
- <td>Address</td>
- <td align="center">...0</td>
- <td align="center">...1</td>
- <td>Address</td>
- <td align="center">...0</td>
- <td align="center">...1</td>
- </tr>
-</table>
-
- 
-
-<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
- <tr>
- <td colspan="10" align="center">int32_t y = 0x0A0B0C0D;</td>
- </tr>
- <tr>
- <td colspan="5" align="center">Big Endian</td>
- <td colspan="5" align="center">Little Endian</td>
- </tr>
- <tr>
- <td>Value</td>
- <td align="center">0A</td>
- <td align="center">0B</td>
- <td align="center">0C</td>
- <td align="center">0D</td>
- <td>Value</td>
- <td align="center">0D</td>
- <td align="center">0C</td>
- <td align="center">0B</td>
- <td align="center">0A</td>
- </tr>
- <tr>
- <td>Address</td>
- <td align="center">...0</td>
- <td align="center">...1</td>
- <td align="center">...2</td>
- <td align="center">...3</td>
- <td>Address</td>
- <td align="center">...0</td>
- <td align="center">...1</td>
- <td align="center">...2</td>
- <td align="center">...3</td>
- </tr>
-</table>
-
- 
-
-<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
- <tr>
- <td colspan="18" align="center">int64_t z = 0x0A0B0C0D0E0F0102;</td>
- </tr>
- <tr>
- <td colspan="9" align="center">Big Endian</td>
- <td colspan="9" align="center">Little Endian</td>
- </tr>
- <tr>
- <td>Value</td>
- <td align="center">0A</td>
- <td align="center">0B</td>
- <td align="center">0C</td>
- <td align="center">0D</td>
- <td align="center">0E</td>
- <td align="center">0F</td>
- <td align="center">01</td>
- <td align="center">02</td>
- <td>Value</td>
- <td align="center">02</td>
- <td align="center">01</td>
- <td align="center">0F</td>
- <td align="center">0E</td>
- <td align="center">0D</td>
- <td align="center">0C</td>
- <td align="center">0B</td>
- <td align="center">0A</td>
- </tr>
- <tr>
- <td>Address</td>
- <td align="center">...0</td>
- <td align="center">...1</td>
- <td align="center">...2</td>
- <td align="center">...3</td>
- <td align="center">...4</td>
- <td align="center">...5</td>
- <td align="center">...6</td>
- <td align="center">...7</td>
- <td>Address</td>
- <td align="center">...0</td>
- <td align="center">...1</td>
- <td align="center">...2</td>
- <td align="center">...3</td>
- <td align="center">...4</td>
- <td align="center">...5</td>
- <td align="center">...6</td>
- <td align="center">...7</td>
- </tr>
-</table>
-
-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
-<a href="http://en.wikipedia.org/wiki/Jonathan_Swift" title="Jonathan Swift">
-Jonathan Swift</a>'s satirical novel 
-<a href="http://en.wikipedia.org/wiki/Gulliver's_Travels" title="Gulliver's Travels">
-Gulliver’s Travels</a>, where rival kingdom's opened their soft-boiled eggs
-at different ends.
+Boost Endian is a header-only 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.
-
-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.
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
Comments and suggestions were
received from

Modified: sandbox/endian/libs/endian/doc/types.html
==============================================================================
--- sandbox/endian/libs/endian/doc/types.html (original)
+++ sandbox/endian/libs/endian/doc/types.html 2011-09-03 17:33:34 EDT (Sat, 03 Sep 2011)
@@ -634,29 +634,12 @@
Original design developed by Darin Adler based on classes developed by Mark
Borgerding. Four original class templates combined into a single <code>endian</code>
class template by Beman Dawes, who put the library together, provided
-documentation, and added the typedefs. He also added the <code>unrolled_byte_loops</code>
+documentation, added the typedefs, and also added the <code>unrolled_byte_loops</code>
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.
<hr>
Last revised:
-27 May, 2011
+03 September, 2011
© Copyright Beman Dawes, 2006-2009
Distributed under the Boost Software License, Version 1.0. See
<a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/ LICENSE_1_0.txt</a>

Date view	Thread view	Subject view	Author view

Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk