mirror of
https://github.com/boostorg/endian.git
synced 2026-07-10 10:30:51 +02:00
Beman
238 lines
9.8 KiB
HTML
238 lines
9.8 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="types.html">Endian 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/types.hpp"><boost/endian/types.hpp></a></td>
|
||
</tr>
|
||
</table>
|
||
<h2><a name="Abstract">Abstract</a></h2>
|
||
|
||
<p>Boost.Endian provides two 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.</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.bin", "wb"); // MUST BE BINARY
|
||
fwrite(&i, sizeof(int16_t), 1, file);
|
||
fclose(file);</pre>
|
||
</blockquote>
|
||
<p>On OS X, Linux, or Windows systems with an Intel CPU, a hex dump
|
||
of the "test.bin" output file produces:</p>
|
||
<blockquote>
|
||
<p><code>0201</code></p>
|
||
</blockquote>
|
||
<p>On OS X systems with a PowerPC CPU, or Solaris systems with a SPARC CPU, a hex dump of the "test.bin"
|
||
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 a core dump on little-endian systems, most programmers can
|
||
ignore endianness. But when exchanging binary integers and binary floating point
|
||
values between computer systems with differing endianness, whether by physical file transfer or over a network, programmers have to deal with endianness
|
||
in their code. </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="types.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 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="types.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>
|
||
</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>
|
||
</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>
|
||
</li>
|
||
<li>Uses less CPU time, particularly if each variable is used many times
|
||
relative to I/O of the variable.<br>
|
||
</li>
|
||
<li>Easier to pass structures to third-party libraries expecting a
|
||
specific structure format.<br>
|
||
</li>
|
||
<li>Supports <code>float</code> and <code>double</code>.</li>
|
||
</ul>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<h2>Overall <a name="FAQ">FAQ</a></h2>
|
||
<p><b>Why bother with endianness?</b></p>
|
||
<blockquote>
|
||
<p>Binary data portability is the primary use case.</p>
|
||
</blockquote>
|
||
<p><b>Does endianness have any uses outside of portable binary file or network
|
||
I/O formats?</b> </p>
|
||
<blockquote>
|
||
<p>Using the unaligned integer types to save internal or external
|
||
memory space is a minor secondary use case.</p>
|
||
</blockquote>
|
||
<p><b>Why bother with binary I/O? Why not just use C++ Standard Library stream
|
||
inserters and extractors?</b></p>
|
||
<blockquote>
|
||
<p>Binary arithmetic data is smaller and therefore I/O is faster and file sizes
|
||
are smaller. Transfer between systems is less expensive. Standard interchange
|
||
formats often specify binary arithmetic data.</p>
|
||
<p>Furthermore, binary arithmetic data is of fixed size, and so fixed-size disk
|
||
records are possible without padding, easing sorting and allowing direct access.
|
||
Disadvantages, such as the inability to use text utilities on the resulting
|
||
files, limit usefulness to applications where the binary I/O advantages are
|
||
paramount.</p>
|
||
</blockquote>
|
||
|
||
<p><b>Why is only big, little, and native endianness supported?</b></p>
|
||
<blockquote>
|
||
<p>These are the only endian schemes that have any practical value today. PDP-11
|
||
and the other middle endian approaches are interesting historical curiosities
|
||
but have no relevance to C++ developers.</p>
|
||
</blockquote>
|
||
|
||
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
|
||
<p>Comments and suggestions were
|
||
received from
|
||
Adder, Benaka Moorthi,
|
||
Christopher Kohlhoff,
|
||
Cliff Green,Daniel James, Gennaro Proto,
|
||
Giovanni Piero Deretta, Gordon Woodhull, dizzy, Hartmut Kaiser, Jeff Flinn,
|
||
John Filo, John Maddock,
|
||
Kim Barrett,
|
||
Marsh Ray,
|
||
Martin Bonner, Mathias Gaunard, Matias Capeletto,
|
||
Neil Mayhew, Paul Bristow, Phil Endecott, Pyry Jahkola, Rene Rivera,
|
||
Robert Stewart, Roland Schwarz, Scott McMurray,
|
||
Sebastian Redl,
|
||
Tim Blechmann, Tim Moore, tymofey, Tomas Puverle, Vincente Botet, Yuval Ronen
|
||
and Vitaly Budovski,.</p>
|
||
<hr>
|
||
<p>Last revised:
|
||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->22 May, 2013<!--webbot bot="Timestamp" endspan i-checksum="13980" --></p>
|
||
<p>© Copyright Beman Dawes, 2011, 2013</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> |