boost_endian/libs/endian/doc/index.html

<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns="http://www.w3.org/TR/REC-html40">

<head>
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">

<title>Boost Endian Library</title>
<link rel="stylesheet" type="text/css" href="../../../doc/src/minimal.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="710">
  <tr>
    <td width="277">
<a href="../../../index.html">
<img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" border="0" width="277" height="86"></a></td>
    <td width="413" align="middle">
    <font size="7">Endian Library</font></td>
  </tr>
</table>

<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="100%">
  <tr>
    <td><a href="../../../index.htm">Boost Home</a>&nbsp;&nbsp;&nbsp;&nbsp;
    <a href="index.html">Endian Home</a>&nbsp;&nbsp;&nbsp;&nbsp;
    <a href="conversion.html">Conversion Reference</a>&nbsp;&nbsp;&nbsp;&nbsp;
    <a href="types.html">Types Reference</a>&nbsp;&nbsp;&nbsp;&nbsp; Tutorial</td>
  </tr>
</table>

<h2><a name="Introduction-to-endianness">Introduction to endianness</a></h2>

<p>Consider the following code:</p>

<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; 
ordering and the least-significant byte first is traditionally called 
&quot;little-endian&quot; ordering. The names are derived from
<a href="http://en.wikipedia.org/wiki/Jonathan_Swift" title="Jonathan Swift">
Jonathan Swift</a>'s satirical novel <i>
<a href="http://en.wikipedia.org/wiki/Gulliver's_Travels" title="Gulliver's Travels">
Gulliver’s Travels</a></i>, where rival kingdom's opened their soft-boiled eggs 
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>The Boost Endian Library provides facilities to deal with integer endianness.</p>

<p>The library provides two approaches to dealing with integer endianness:</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>

<h2><a name="Acknowledgements">Acknowledgements</a></h2>
<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>
<p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->03 September, 2011<!--webbot bot="Timestamp" endspan i-checksum="39334" --></p>
<p>© Copyright Beman Dawes, 2011</p>
<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>

<p>&nbsp;</p>

</body>

</html>