forked from boostorg/endian
173 lines
7.3 KiB
HTML
173 lines
7.3 KiB
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>
|
||
<a href="index.html">Endian Home</a>
|
||
<a href="conversion.html">Conversion Functions</a>
|
||
<a href="integers.html">Integer Types</a> 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"><boost/endian/conversion.hpp></a><br>
|
||
<a href="../../../boost/endian/integers.hpp"><boost/endian/integers.hpp></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>
|
||
</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>
|
||
</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>
|
||
<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>
|
||
</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("test", "wb"); // MUST BE BINARY
|
||
fwrite(&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 "test" 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 "test"
|
||
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 "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 <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 facilities to deal with integer endianness.</p>
|
||
|
||
<p>The library provides two approaches to dealing with integer endianness:</p>
|
||
|
||
<blockquote>
|
||
|
||
<p><b><a href="conversion.html">Endian conversions</a> 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><a href="integers.html">Endian integer 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>.
|
||
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 -->04 September, 2011<!--webbot bot="Timestamp" endspan i-checksum="39336" --></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> </p>
|
||
|
||
</body>
|
||
|
||
</html> |