boostorg/endian
1
0
Fork 1
mirror of https://github.com/boostorg/endian.git synced 2025-08-01 21:44:31 +02:00
Code Issues Packages Projects Releases Wiki Activity

Continue to refine the docs

Browse Source 
git-svn-id: http://svn.boost.org/svn/boost/sandbox/endian@74216 b8fc166d-592f-0410-95f2-cb63ce0dd405
This commit is contained in:
bemandawes
2011-09-03 21:33:34 +00:00
parent f243089ef4
commit 0b4566731a
2 changed files with 55 additions and 171 deletions
Download Patch File Download Diff File Expand all files Collapse all files

205
libs/endian/doc/index.html
View File

@@ -30,170 +30,71 @@
</tr> </tr>
</table> </table>
<h2><a name="Introduction">Introduction</a></h2>
<p>The Boost Endian Library provides facilities to deal with integer endianness. See
<a href="#Introduction-to-endianness">Introduction to endianness</a> below for
the basics of endianness.</p>
<p>The library provides two approaches to dealing with integer endianness:</p>
<blockquote>
<p><b>Endian conversions for native integers -</b> 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.</p>
<p><b>Endian integer types -</b> 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>. </p>
</blockquote>
<p>Boost Endian is header-only library.</p>
<h2><a name="Introduction-to-endianness">Introduction to endianness</a></h2> <h2><a name="Introduction-to-endianness">Introduction to endianness</a></h2>
<p>Consider a C++ program that defines variables x, y, and z as 16, 32, and <p>Consider the following code:</p>
64-bit integers, respectively. There are several ways a processor might layout
the individual bytes for these variables in memory:</p>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
<tr>
<td colspan="6" align="center"><b>int16_t x = 0x0A0B;</b></td>
</tr>
<tr>
<td colspan="3" align="center"><b>Big Endian</b></td>
<td colspan="3" align="center"><b>Little Endian</b></td>
</tr>
<tr>
<td><b>Value</b></td>
<td align="center"><b>0A</b></td>
<td align="center"><b>0B</b></td>
<td><b>Value</b></td>
<td align="center"><b>0B</b></td>
<td align="center"><b>0A</b></td>
</tr>
<tr>
<td><b>Address</b></td>
<td align="center"><b>...0</b></td>
<td align="center"><b>...1</b></td>
<td><b>Address</b></td>
<td align="center"><b>...0</b></td>
<td align="center"><b>...1</b></td>
</tr>
</table>
<br>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
<tr>
<td colspan="10" align="center"><b>int32_t y = 0x0A0B0C0D;</b></td>
</tr>
<tr>
<td colspan="5" align="center"><b>Big Endian</b></td>
<td colspan="5" align="center"><b>Little Endian</b></td>
</tr>
<tr>
<td><b>Value</b></td>
<td align="center"><b>0A</b></td>
<td align="center"><b>0B</b></td>
<td align="center"><b>0C</b></td>
<td align="center"><b>0D</b></td>
<td><b>Value</b></td>
<td align="center"><b>0D</b></td>
<td align="center"><b>0C</b></td>
<td align="center"><b>0B</b></td>
<td align="center"><b>0A</b></td>
</tr>
<tr>
<td><b>Address</b></td>
<td align="center"><b>...0</b></td>
<td align="center"><b>...1</b></td>
<td align="center"><b>...2</b></td>
<td align="center"><b>...3</b></td>
<td><b>Address</b></td>
<td align="center"><b>...0</b></td>
<td align="center"><b>...1</b></td>
<td align="center"><b>...2</b></td>
<td align="center"><b>...3</b></td>
</tr>
</table>
<br>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
<tr>
<td colspan="18" align="center"><b>int64_t z = 0x0A0B0C0D0E0F0102;</b></td>
</tr>
<tr>
<td colspan="9" align="center"><b>Big Endian</b></td>
<td colspan="9" align="center"><b>Little Endian</b></td>
</tr>
<tr>
<td><b>Value</b></td>
<td align="center"><b>0A</b></td>
<td align="center"><b>0B</b></td>
<td align="center"><b>0C</b></td>
<td align="center"><b>0D</b></td>
<td align="center"><b>0E</b></td>
<td align="center"><b>0F</b></td>
<td align="center"><b>01</b></td>
<td align="center"><b>02</b></td>
<td><b>Value</b></td>
<td align="center"><b>02</b></td>
<td align="center"><b>01</b></td>
<td align="center"><b>0F</b></td>
<td align="center"><b>0E</b></td>
<td align="center"><b>0D</b></td>
<td align="center"><b>0C</b></td>
<td align="center"><b>0B</b></td>
<td align="center"><b>0A</b></td>
</tr>
<tr>
<td><b>Address</b></td>
<td align="center"><b>...0</b></td>
<td align="center"><b>...1</b></td>
<td align="center"><b>...2</b></td>
<td align="center"><b>...3</b></td>
<td align="center"><b>...4</b></td>
<td align="center"><b>...5</b></td>
<td align="center"><b>...6</b></td>
<td align="center"><b>...7</b></td>
<td><b>Address</b></td>
<td align="center"><b>...0</b></td>
<td align="center"><b>...1</b></td>
<td align="center"><b>...2</b></td>
<td align="center"><b>...3</b></td>
<td align="center"><b>...4</b></td>
<td align="center"><b>...5</b></td>
<td align="center"><b>...6</b></td>
<td align="center"><b>...7</b></td>
</tr>
</table>
<blockquote>
<pre>int16_t i = 0x0102;
FILE * file = fopen(&quot;test&quot;, &quot;wb&quot;); // MUST BE BINARY
fwrite(&amp;i, sizeof(int16_t), 1, file);
fclose(file);</pre>
</blockquote>
<p>On a modern Apple, Linux, or Windows computer with an Intel CPU, a hex dump
of the &quot;test&quot; output file produces:</p>
<blockquote>
<p><code>0201</code></p>
</blockquote>
<p>On a Oracle/Sun Solaris computer with a SPARC CPU, a hex dump of the &quot;test&quot;
output file produces:</p>
<blockquote>
<p><code>0102</code></p>
</blockquote>
<p>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.</p>
<p>The most-significant byte first ordering is traditionally called &quot;big endian&quot; <p>The most-significant byte first ordering is traditionally called &quot;big endian&quot;
ordering and the least-significant byte first is traditionally called ordering and the least-significant byte first is traditionally called
&quot;little-endian&quot; ordering. Although some other orderings are possible, most &quot;little-endian&quot; ordering. The names are derived from
modern uses are as shown above. The names are derived from
<a href="http://en.wikipedia.org/wiki/Jonathan_Swift" title="Jonathan Swift"> <a href="http://en.wikipedia.org/wiki/Jonathan_Swift" title="Jonathan Swift">
Jonathan Swift</a>'s satirical novel <i> Jonathan Swift</a>'s satirical novel <i>
<a href="http://en.wikipedia.org/wiki/Gulliver's_Travels" title="Gulliver's Travels"> <a href="http://en.wikipedia.org/wiki/Gulliver's_Travels" title="Gulliver's Travels">
Gulliver<EFBFBD>s Travels</a></i>, where rival kingdom's opened their soft-boiled eggs Gulliver<EFBFBD>s Travels</a></i>, where rival kingdom's opened their soft-boiled eggs
at different ends.</p> at different ends.</p>
<p>For a more complete introduction to endianness, see the Wikipedia's
<a href="http://en.wikipedia.org/wiki/Endianness">Endianness</a> article.</p>
<p>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.</p>
<h2><a name="Introduction">Introduction</a> to the Boost Endian Library</h2>
<p>Intel processors are traditionally little endian while many others are big <p>The Boost Endian Library provides facilities to deal with integer endianness.</p>
endian. Some processors can switch endianness, so which is in use depends on the
operating system. The Wikipedia's <p>The library provides two approaches to dealing with integer endianness:</p>
<a href="http://en.wikipedia.org/wiki/Endianness">Endianness</a> entry lists
details for many processors and operating systems.</p> <blockquote>
<p><b>Endian conversions for native integers -</b> 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. </p>
<p><b>Endian integer types -</b> 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.</p>
</blockquote>
<p>Boost Endian is a header-only library.</p>
<p>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.</p>
<h2><a name="Acknowledgements">Acknowledgements</a></h2> <h2><a name="Acknowledgements">Acknowledgements</a></h2>
<p>Comments and suggestions were <p>Comments and suggestions were
received from received from

21
libs/endian/doc/types.html
View File

@@ -634,29 +634,12 @@ any Boost object libraries.</p>
<p>Original design developed by Darin Adler based on classes developed by Mark <p>Original design developed by Darin Adler based on classes developed by Mark
Borgerding. Four original class templates combined into a single <code>endian</code> Borgerding. Four original class templates combined into a single <code>endian</code>
class template by Beman Dawes, who put the library together, provided 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 sign partial specialization to correctly extend the sign when cover integer size
differs from endian representation size.</p> differs from endian representation size.</p>
<p>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.</p>
<hr> <hr>
<p>Last revised: <p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->27 May, 2011<!--webbot bot="Timestamp" endspan i-checksum="13974" --></p> <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->03 September, 2011<!--webbot bot="Timestamp" endspan i-checksum="39334" --></p>
<p><EFBFBD> Copyright Beman Dawes, 2006-2009</p> <p><EFBFBD> Copyright Beman Dawes, 2006-2009</p>
<p>Distributed under the Boost Software License, Version 1.0. See <p>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></p> <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/ LICENSE_1_0.txt</a></p>