boost_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><b><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 Functions</a>&nbsp;&nbsp;&nbsp;&nbsp;
    <a href="integers.html">Integer Types</a>&nbsp;&nbsp;&nbsp;&nbsp; Tutorial</b></td>
  </tr>
</table>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" align="right">
  <tr>
    <td width="100%" bgcolor="#D7EEFF" align="center">
      <i><b>Contents</b></i></td>
  </tr>
  <tr>
    <td width="100%" bgcolor="#E8F5FF">
      <a href="#Abstract">Abstract</a><br>
      <a href="#Introduction-to-endianness">Introduction to endianness</a><br>
      <a href="#Introduction">Introduction to the Boost.Endian library</a><br>
      <a href="#Acknowledgements">Acknowledgements</a></td>
  </tr>
  <tr>
    <td width="100%" bgcolor="#D7EEFF" align="center">
      <b><i>Headers</i></b></td>
  </tr>
  <tr>
    <td width="100%" bgcolor="#E8F5FF">
      <a href="../../../boost/endian/conversion.hpp">&lt;boost/endian/conversion.hpp&gt;</a><br>
      <a href="../../../boost/endian/integers.hpp">&lt;boost/endian/integers.hpp&gt;</a></td>
  </tr>
</table>
<h2><a name="Abstract">Abstract</a></h2>

<p>Boost.Endian provides facilities to manipulate the byte ordering of integers.</p>
<ul>
  <li>The primary use case is binary I/O of integers for portable exchange with 
  other systems, via either file or network transmission.<br>
&nbsp;</li>
  <li>A secondary use case is minimizing storage size via integers of sizes 
  and/or alignments not supported by the built-in types. Integers 1, 2, 3, 4, 5, 
  6, 7, and 8 bytes in length are supported.<br>
&nbsp;</li>
  <li>Two distinct approaches to byte ordering are provided. Each approach has a 
  long history of successful use, and each approach has use cases where it is 
  superior to the other approach.<br>
&nbsp;<ul>
    <li>The explicit approach provides <a href="conversion.html">conversion 
    functions</a> to reorder bytes. All four combinations of non-modifying or 
    modifying, and unconditional or conditional, functions are provided.<br>
&nbsp;</li>
    <li>The implicit approach provides <a href="integers.html">integer types</a> 
    that mimic the built-in integers, implicitly handling all byte reordering.</li>
  </ul>
  </li>
</ul>

<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 an 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 an Apple or other computer with a PowerPC CPU, or an 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><a name="definition"></a>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 kingdoms opened their soft-boiled eggs 
at different ends.</p>
<p>See the Wikipedia's
<a href="http://en.wikipedia.org/wiki/Endianness">Endianness</a> article for an 
extensive discussion of endianness.</p>
<p>Except for reading an occasional core dump, most programmers can ignore 
endianness. But when exchanging binary integers with other computer systems, whether by 
file transfers or over a network, programmers have to deal with endianness. </p>
<h2><a name="Introduction">Introduction</a> to the Boost.Endian library</h2>

<p>The Boost.Endian library provides two facilities for dealing with endianness.</p>

<p>The library provides two approaches to dealing with integer endianness:</p>

<blockquote>

<p><b><a href="conversion.html">Endian conversions</a> -</b> The application 
uses the built-in integer and floating point 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. Type <code>long double</code> is not currently supported.</p>

<p><b><a href="integers.html">Endian types</a> -</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>. Types with lengths of 
1-8 bytes are supported, rather than just&nbsp; 2, 4, and 8 bytes. There are no alignment 
requirements. Floating point types are not currently supported.</p>

</blockquote>

<p>Boost Endian is a header-only library.</p>

<h2><a name="Choosing">Choosing</a> between endian types and endian 
conversion functions</h2>

<p>Which approach is best for dealing with endianness depends on the 
application.</p>

<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
  <tr>
    <th colspan="2">Advantages</th>
  </tr>
  <tr>
    <th width="50%"><b><a href="integers.html">Endian types</a></b></th>
    <th><b><a href="conversion.html">Endian conversion functions</a></b></th>
  </tr>
  <tr>
    <td valign="top">
    <ul>
      <li>Mimic the built-in types. This can simplify use and eliminate logic 
      errors since there is no need to reason about the current endianness of 
      variables.<br>
&nbsp;</li>
      <li>1, 2, 3, 4, 5, 6, 7, and 8 byte integers are supported. Use of 3, 5, 
      6, or 7 byte integers can reduce internal and external space usage and 
      save I/O time.<br>
&nbsp;</li>
      <li>Alignment is not required. This can eliminate padding bytes in 
      structures, reducing internal and external space usage and saving I/O 
      time.</li>
    </ul>
    </td>
    <td valign="top">
    <ul>
      <li>Already familiar to developers who have been using C conversion 
      functions for years.<br>
&nbsp;</li>
      <li>Uses less CPU time, particularly if each variable is used many times 
      relative to I/O of the variable.<br>
&nbsp;</li>
      <li>Easier to pass structures to third-party libraries expecting a 
      specific structure format.<br>
&nbsp;</li>
      <li>Supports <code>float</code> and <code>double</code>.</li>
    </ul>
    </td>
  </tr>
</table>

<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,
Robert Stewart, 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 -->20 May, 2013<!--webbot bot="Timestamp" endspan i-checksum="13976" --></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>