Directory reorg to follow Boost Git practice.

This commit is contained in:
Beman committed 2013-03-18 14:57:23 -04:00
1 parent d549e3bdd3
commit d131123327
27 files changed

No files matched your search

+169
View File
@@ -0,0 +1,169 @@
<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 Conversion Functions</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="933">
<tr>
<td width="277">
<a href="../../../index.html">
<img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86" border="0"></a></td>
<td width="636" align="middle">
<font size="7">Endian Conversion Functions</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="#Introduction">Introduction</a><br>
<a href="#Reference">Reference</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Synopsis">Synopsis</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Members">Members</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="Introduction">Introduction</a></h2>
<p>Header <a href="../../../boost/endian/conversion.hpp">boost/endian/conversion.hpp</a>
provides functions that convert built-in
integers between native byte ordering and <a href="index.html#definition">big or little endian</a> byte
ordering.</p>
<h2><a name="Reference">Reference</a></h2>
<h3>
<a name="Synopsis">Synopsis</a></h3>
<pre>namespace boost
{
namespace endian
{
// unconditional modifying (i.e. in-place) reverse byte order
inline void reorder(int16_t&amp; x);
inline void reorder(int32_t&amp; x);
inline void reorder(int64_t&amp; x);
inline void reorder(uint16_t&amp; x);
inline void reorder(uint32_t&amp; x);
inline void reorder(uint64_t&amp; x);
// unconditional non-modifying reverse byte order copy
inline void reorder(int16_t source, int16_t&amp; target);
inline void reorder(int32_t source, int32_t&amp; target);
inline void reorder(int64_t source, int64_t&amp; target);
inline void reorder(uint16_t source, uint16_t&amp; target);
inline void reorder(uint32_t source, uint32_t&amp; target);
inline void reorder(uint64_t source, uint64_t&amp; target);
// conditional modifying (i.e. in-place) reverse byte order
template &lt;class T&gt; void native_to_big(T&amp; x);
template &lt;class T&gt; void native_to_little(T&amp; x);
template &lt;class T&gt; void big_to_native(T&amp; x);
template &lt;class T&gt; void little_to_native(T&amp; x);
// non-modifying conditional reverse byte order copy
template &lt;class T&gt; void native_to_big(T source, T&amp; target);
template &lt;class T&gt; void native_to_little(T source, T&amp; target);
template &lt;class T&gt; void big_to_native(T source, T&amp; target);
template &lt;class T&gt; void little_to_native(T source, T&amp; target);
} // namespace endian
} // namespace boost</pre>
<h3 dir="ltr"><a name="Members">Members</a></h3>
<pre dir="ltr">inline void reorder(int16_t&amp; x);
inline void reorder(int32_t&amp; x);
inline void reorder(int64_t&amp; x);
inline void reorder(uint16_t&amp; x);
inline void reorder(uint32_t&amp; x);
inline void reorder(uint64_t&amp; x);</pre>
<blockquote>
<p dir="ltr"><i>Effects:</i> Reverses the byte order of <i><code>x</code></i>.</p>
</blockquote>
<pre dir="ltr">inline void reorder(int16_t source, int16_t&amp; target);
inline void reorder(int32_t source, int32_t&amp; target);
inline void reorder(int64_t source, int64_t&amp; target);
inline void reorder(uint16_t source, uint16_t&amp; target);
inline void reorder(uint32_t source, uint32_t&amp; target);
inline void reorder(uint64_t source, uint64_t&amp; target);</pre>
<blockquote>
<p dir="ltr"><i>Effects:</i> Copies <code>source</code> to <code>target</code>,
reversing the byte order.</p>
</blockquote>
<pre dir="ltr">template &lt;class T&gt; void native_to_big(T&amp; x);
template &lt;class T&gt; void native_to_little(T&amp; x);
template &lt;class T&gt; void big_to_native(T&amp; x);
template &lt;class T&gt; void little_to_native(T&amp; x);</pre>
<blockquote>
<p dir="ltr"><i>Effects:</i> If the native byte ordering and byte
ordering indicated by the function name are different, <code>reorder(x)</code>, otherwise no effect.</p>
<p dir="ltr"><i>Example:</i></p>
<blockquote>
<pre>int32_t x = <b><i>some-value</i></b>;
native_to_big(x); // converts x to big-endian unless
// the native representation is already big-endian</pre>
</blockquote>
</blockquote>
<pre dir="ltr">template &lt;class T&gt; void native_to_big(T source, T&amp; target);
template &lt;class T&gt; void native_to_little(T source, T&amp; target);
template &lt;class T&gt; void big_to_native(T source, T&amp; target);
template &lt;class T&gt; void little_to_native(T source, T&amp; target);</pre>
<blockquote>
<p dir="ltr"><i>Effects:</i> If the native byte ordering and byte
ordering indicated by the function name are different, <code>reorder(source, target)</code>, otherwise <code>
target = source</code>.</p>
<p dir="ltr"><i>Example:</i></p>
<blockquote>
<pre>int32_t x;
<i>... read an external little-endian value into x ...</i>
int32_t y;
little_to_native(x, y); // if native ordering is big-endian, reorder(x, y),
// otherwise y = x</pre>
</blockquote>
</blockquote>
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
<p>Tomas Puverle was instrumental in identifying and articulating the need to
support endian conversion as separate from endian types.</p>
<hr>
<p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05 September, 2011<!--webbot bot="Timestamp" endspan i-checksum="39338" --></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>
</body>
</html>
+275
View File
@@ -0,0 +1,275 @@
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<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>Endian Library Do List</title>
</head>
<body>
<h1>Endian Library Do List</h1>
<h2>To Do</h2>
<ul>
<li>Re-read all messages, and extract Acknowledgements and revise TODO list.</li>
<li>Develop the use-cases example programs, using plain integers and UDT's.
</li>
<li>Apply revised conversion functions to the example programs. Iterate until
happy.</li>
<li>Apply the integers to the example programs, and also see if using<br>
the revised conversion functions to implement some or all of the<br>
integers.</li>
<li>Apply mockups of the buffers to the example programs, to get a<br>
firmer idea if the buffer idea actually seems to do be worthwhile in<br>
practice.</li>
<li>Post work-in-progress for feedback.</li>
<li>Finalize and hold mini-review.</li>
</ul>
<h2>Format Review Comments</h2>
<h3 dir="ltr">Votes</h3>
<ul>
<li dir="ltr">
<p dir="ltr">John Filo - &quot;Absolutely. I'd like to see support for float and
double, but<br>
even without those additions, I still vote yes.&quot; &quot;For those who deal with
non-native endian data, this library is<br>
extremely useful. It automatically eliminates a whole class of common<br>
programming errors when dealing with such data.&quot;<br>
&nbsp;</li>
<li dir="ltr">
<p dir="ltr">Hartmut Kaiser - &quot;Even if this is not a full review, I would like
to vote YES to include this <br>
library into Boost.
<p>Boost.Spirit is using (and shipping) with an older version of this library
<br>
for several years now and we never had any problems with its usage in <br>
Spirit. It is used as the underlying framework for the binary parsers and <br>
generators and it is functioning as advertised.</p>
<p>As a quick test I replaced the internal (older) version of Boost.Endian in
<br>
Spirit with the reviewed version. All of Spirits regression tests still <br>
pass. &quot;<br>
&nbsp;</li>
<li dir="ltr">
<p dir="ltr">Robert Stewart - &quot;There are issues that keep me from saying yes
at this time. &nbsp;There are too many suggested variations and ideas under
consideration to accept the library in its present state. &nbsp;However, a
mini-review should be sufficient to evaluate the final form, once Beman
determines a course of action, and determine whether to accept it or not.&quot;<br>
&nbsp;</li>
<li dir="ltr">
<p dir="ltr">Tim Blechmann - &quot;the library should be accepted, if<br>
<br>
(a) the interface of the conversion functions is changed<br>
(b) the performance can be improved<br>
(c) the documentation integrates better with the rest of the boost<br>
&nbsp; &nbsp;documentation.&quot;<br>
&nbsp;</li>
<li dir="ltr">
<p dir="ltr">Vicente J. Botet Escriba - &quot;No in its current state.<br>
Once the library takes in account the requested modification (that Beman has
already accepted) a mini-review will be necessary to improve the library
before release.&quot;</li>
</ul>
<h3>Executive summary</h3>
<ul>
<li>Common use case scenarios should be developed.</li>
<li>Example programs should be developed for the common use case scenarios.</li>
<li>Documentation should illuminate the differences between endian
integer/float type and endian conversion approaches to the common use case
scenarios, and provide guidelines for choosing the most appropriate approach
for user's applications.</li>
<li>Conversion functions supplying results via <code>return</code> should be
provided.</li>
<li>Platform specific performance enhancements such as use of compiler
intrinsics or relaxed alignment requirements should be supported.</li>
<li>Endian integer (and floating) types should be implemented via the
conversion functions. If that can't be done efficiently, consideration should
be given to expanding the conversion function signatures to resolve the
inefficiencies.</li>
<li>Benchmarks that measure performance should be provided. It should be
possible to compare platform specific performance enhancements against
portable base implementations, and to compare endian integer approaches
against endian conversion approaches for the common use case scenarios.</li>
<li>Float (32-bits) and double (64-bits) should be supported. IEEE 754 is the
primary use case.</li>
<li>Support for user defined types (UDTs) is desirable, and should be
supported where there would be no conflict with the other concerns.</li>
<li>There is some concern that endian integer/float arithmetic operations
might used
inadvertently or inappropriately. The impact of adding an endian_buffer class without arithmetic
operations should be investigated.</li>
<li>Stream insertion and extraction of the endian integer/float types should
be documented and included in the test coverage.</li>
<li>Binary I/O support that was investigated during development of the Endian
library should be put up for min-review for inclusion in the Boost I/O
library.</li>
</ul>
<h3>Docs</h3>
<ul>
<li>Document use of endian integers with stream inserters and extractors.</li>
<li>Either add tutorial or remove from menu bar.</li>
<li>Conversion in note mention similarity to htonl() , etc.</li>
<li>Conversion: add discussion of alignment, packing, etc. Bottom line; use at
your own risk. Use Phil's example:<br>
struct S {<br>
&nbsp;uint16_t a;<br>
&nbsp;uint32_t b;<br>
} __attribute__ ((packed));</li>
<li>Requirements for template parameters. </li>
<li>UDTs<ul>
<li>Integers</li>
<li>Conversion</li>
</ul>
</li>
<li>Distinguish use cases and recommendations for which approach (integers vs
conversion) is appropriate.<ul>
<li><a href="http://lists.boost.org/Archives/boost/2011/09/185698.php">
http://lists.boost.org/Archives/boost/2011/09/185698.php</a></li>
</ul>
</li>
<li>&gt; section `experience': this section gives no insights for people who use
or<br>
&gt; read the code. it mainly tells: &quot;we are not the first and the domain of the<br>
&gt; library is important.&quot;. imo this section can be removed (maybe the part that<br>
&gt; it is not related to any c library can go to the `design considerations'<br>
&gt;<br>
&gt; section &quot;motivating use cases&quot;: this is more a marketing blurb/testimonial.<br>
&gt; maybe this could be changed to a section about possible use cases, listing<br>
&gt; `communicating between different devices' and `reading/writing of binary
file<br>
&gt; formats'.</li>
<li>one other point ... the help file seems to directly link to the c++
headers.<br>
this should be changed:<br>
<br>
* some browsers (at least chromium) will not display the header when clicking<br>
&nbsp;the link, but will save them on disk.<br>
<br>
* providing a direct link to the source code from the docs implies that the<br>
&nbsp;user will get some information that are necessary to use the library by<br>
&nbsp;reading the sources. imo, this is not the case for using boost.endian.<br>
<br>
* if a user opens integer.hpp, the first 60 lines just contain copyright, some<br>
&nbsp;historical notes, compiler-specific stuff, includes and ifdefs. imo, this is<br>
&nbsp;the implementation part, which should not be exposed to a user.<br>
<br>
so i'd suggest to completely remove the links to the c++ headers.<br>
&nbsp;</li>
<li>
<div class="im">
&gt; explaining the other builting types are not considered. Why only
big/little<br>
&gt; endianness has been taken in account?</div>
<p>I'll add FAQ and/or add more entries to the final docs.<br>
<br>
Only big/little endianness is taken into account because these are the<br>
only endian schemes that have any practical value. All the others are<br>
just historical curiosities.</li>
</ul>
<h3>Code</h3>
<p>Also change docs if applicable.</p>
<ul>
<li><span style="background-color: #FFCCFF">Beman: TODO</span><span style="background-color: #FFCCFF">:
</span><span style="background-color: #FFCCFF">Google</span><span style="background-color: #FFCCFF">
&quot;unaligned integer&quot;, look at various entries. For example, http://</span><span style="background-color: #FFCCFF">infocenter.arm.com</span><span style="background-color: #FFCCFF">/help/</span><span style="background-color: #FFCCFF">index.jsp?topic</span><span style="background-color: #FFCCFF">=/</span><span style="background-color: #FFCCFF">com.arm.doc.faqs</span><span style="background-color: #FFCCFF">/ka3544.html</span></li>
<li>Merge conversion2 into conversion.hpp</li>
<li>Use builtins where applicable (GCC, possibly others)</li>
<li>Endian integer types should use the conversion functions where applicable.</li>
<li>Beman: Some platforms (compiler/processor taken together) don't require
alignment for the conversion functions if code is inlined, although speed may
suffer. (test to verify this assertion). On those platforms, conversion
functions (perhaps in-place) can be used to implement unaligned integers.<ul>
<li>Microsoft <a href="http://msdn.microsoft.com/en-us/library/ms253978.aspx">
UNALIGNED / __unaligned</a> keywords for pointers. Also
<a href="http://msdn.microsoft.com/en-us/library/ms253935.aspx">Packing
Structures</a>.</li>
<li>GCC
<a href="http://www.mailinglistarchive.com/gcc@gcc.gnu.org/msg21079.html">
http://www.mailinglistarchive.com/gcc@gcc.gnu.org/msg21079.html</a></li>
<li>Intel performs well on simple unaligned test. See
<a href="../test/unaligned_test.cpp">../test/unaligned_test.cpp</a></li>
</ul>
</li>
<li>Beman: Does the use of the unrolling templates get in the way of processor
specific optimization code?</li>
<li>Test use of endian integers with stream inserters and extractors.</li>
<li>Continue work on benchmarks and timings. Consider using use-case example
programs as benchmarks.</li>
<li>
<div class="im">
&gt; The reorder fuction should provide both reorder in place and returned.</div>
<p>Interesting, but providing two ways of doing something is often<br>
considered the not best design practice. And the tests I've run so far<br>
don't indicate any efficiency concern. Once all other aspects of the<br>
interface and implementation are settled, let's revisit that question.<br>
&nbsp;</li>
<li>&gt; The endianness scoped enum native should be replaced so it is defined<br>
&gt; depending on the endianess of the platform.<br>
&gt;<br>
&gt; &nbsp;BOOST_SCOPED_ENUM_START(<wbr />endianness) { big, little, native=(big or
little)<br>
&gt; }; BOOST_SCOPED_ENUM_END<br>
&gt;<br>
&gt; This will have the advantage to reduce of 1/3 the number of specializations.<br>
<br>
Does this work?<br>
&nbsp;</li>
<li dir="ltr">
<div class="im">
&gt; The library should provide in addition endian conversion functions that
have<br>
&gt; the endiannes as template parameters to make possible generic functions.</div>
<p dir="ltr">Compile time dispatch on an endianness enum was also requested in<br>
another review. That's fine with me, but I haven't had a chance to<br>
figure out the interface details.</li>
</ul>
<h3>Infrastructure</h3>
<ul>
<li>Remove scoped_enum_emulation_test stuff.</li>
<li>Remove timer stuff.</li>
<li>Use Boost.Timer.</li>
<li>
<div class="im">
&gt; endian_operations_test.cpp and endian_in_union_test.cpp ... maybe rename
from<br>
&gt; _test.cpp to _compile_test.cpp? they don't seem to do any run-time tests.
they<br>
&gt; also should not include &lt;cassert&gt; since no assertion statement is needed,
this<br>
&gt; might speed up the compilation time of the testsuite by something like
50ms ;)</div>
<p>Will do.</li>
<li>Make the bin() functionality available</li>
</ul>
<h3>Performance</h3>
<p>&nbsp;</p>
<h3>Acknowledge</h3>
<p>Gordon Woodhull, Hartmut Kaiser, Phil Endecott, tymofey, Giovanni Piero Deretta, Pyry Jahkola,
John Filo, Vitaly Budovski, Tomas Puverle, Vicente J. Botet Escriba, Tim
Blechmann, Daniel James, Mathias Gaunard, Adder, Tim Moore</p>
<p>Paul Bristow docs help </p>
<h2>Floating Point Support</h2>
<p>* Because FP formats vary, just dealing with endianness doesn't ensure<br>
portability.<br>
* The endianness of FP and integer values differs on some platforms,<br>
so we will have to build up a config file with separate entries for<br>
each platform, and that will take time to mature.<br>
* Ditto FP sizes.<br>
* I'm only willing to provide conversion.hpp FP support. Providing<br>
types that mimic FP types is far beyond my knowledge of how to deal<br>
with floating point's notorious arithmetic issues.</p>
<p>Support IEEE754 format (32 bit, 64 bit) only.</p>
<div class="im">
<br>
&nbsp;</div>
<p>&nbsp;</p>
</body>
</html>
+173
View File
@@ -0,0 +1,173 @@
<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 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><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 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>&nbsp;</p>
</body>
</html>
+587
View File
@@ -0,0 +1,587 @@
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<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 Integers</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" width="277" height="86" border="0"></a></td>
<td width="413" align="middle">
<font size="7">Endian Integer Types</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="#Introduction">Introduction</a><br>
<a href="#Example">Example</a><br>
<a href="#Limitations">Limitations</a><br>
<a href="#Feature-set">Feature set</a><br>
<a href="#Types">Typedefs</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Comment-on-naming">Comment on naming</a><br>
<a href="#Class_template_endian">Class template <code>endian</code></a><br>
&nbsp;&nbsp;&nbsp;
<a href="#Synopsis">Synopsis</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Members">Members</a><br>
<a href="#FAQ">FAQ</a><br>
<a href="#Design">Design</a><br>
<a href="#Experience">Experience</a><br>
<a href="#Motivating-use-cases">Motivating use cases</a><br>
<a href="#C++0x">C++0x</a><br>
<a href="#Compilation">Compilation</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="Introduction">Introduction</a></h2>
<p>Header <a href="file:///D:/endian/boost/endian/integers.hpp">&lt;boost/endian/integers.hpp&gt;</a> provides
integer-like byte-holder binary types with explicit control over
byte order, value type, size, and alignment. Typedefs provide easy-to-use names
for common configurations.</p>
<p>These types provide portable byte-holders for integer data, independent of
particular computer architectures. Use cases almost always involve I/O, either via files or
network connections. Although data portability is the primary motivation, these
integer byte-holders may
also be used to reduce memory use, file size, or network activity since they
provide binary integer sizes not otherwise available.</p>
<p>Such integer byte-holder types are traditionally called <b><i>
endian</i></b> types. See the <a href="http://en.wikipedia.org/wiki/Endian">Wikipedia</a> for
a full
exploration of <b><i>endianness</i></b>, including definitions of <i><b>big
endian</b></i> and <i><b>little endian</b></i>.</p>
<p>Boost endian integers provide the same full set of C++ assignment,
arithmetic, and relational operators&nbsp;as C++ standard integral types, with
the standard semantics.</p>
<p>Unary arithmetic operators are <code>+</code>, <code>-</code>, <code>~</code>,
<code>!</code>, prefix and postfix <code>--</code> and <code>++</code>. Binary
arithmetic operators are <code>+</code>, <code>+=</code>, <code>-</code>, <code>
-=</code>, <code>*</code>, <code>*=</code>, <code>/</code>, <code>/=</code>,
<code>%/ %=</code>, <code>&amp;</code>, <code>&amp;=</code>, <code>|</code>, <code>|=</code>,
<code>^</code>, <code>^=</code>, <code>&lt;&lt;</code>, <code>&lt;&lt;=</code>, <code>&gt;&gt;</code>,
<code>&gt;&gt;=</code>. Binary relational operators are <code>==</code>, <code>!=</code>,
<code>&lt;</code>, <code>&lt;=</code>, <code>&gt;</code>, <code>&gt;=</code>.</p>
<p>Automatic conversion is provided to the underlying integer value type.</p>
<h2><a name="Example">Example</a></h2>
<p>The <a href="../example/endian_example.cpp">endian_example.cpp</a> program writes a
binary file containing four byte big-endian and little-endian integers:</p>
<blockquote>
<pre>#include &lt;iostream&gt;
#include &lt;cstdio&gt;
#include &lt;boost/endian/integers.hpp&gt;
#include &lt;boost/static_assert.hpp&gt;
using namespace boost::endian;
namespace
{
// This is an extract from a very widely used GIS file format. I have no idea
// why a designer would mix big and little endians in the same file - but
// this is a real-world format and users wishing to write low level code
// manipulating these files have to deal with the mixed endianness.
struct header
{
big32_t file_code;
big32_t file_length;
little32_t version;
little32_t shape_type;
};
const char * filename = &quot;test.dat&quot;;
}
int main()
{
BOOST_STATIC_ASSERT( sizeof( header ) == 16U ); // check requirement
header h;
h.file_code = 0x01020304;
h.file_length = sizeof( header );
h.version = -1;
h.shape_type = 0x01020304;
// Low-level I/O such as POSIX read/write or &lt;cstdio&gt; fread/fwrite is sometimes
// used for binary file operations when ultimate efficiency is important.
// Such I/O is often performed in some C++ wrapper class, but to drive home the
// point that endian integers are often used in fairly low-level code that
// does bulk I/O operations, &lt;cstdio&gt; fopen/fwrite is used for I/O in this example.
std::FILE * fi;
if ( !(fi = std::fopen( filename, &quot;wb&quot; )) ) // MUST BE BINARY
{
std::cout &lt;&lt; &quot;could not open &quot; &lt;&lt; filename &lt;&lt; '\n';
return 1;
}
if ( std::fwrite( &amp;h, sizeof( header ), 1, fi ) != 1 )
{
std::cout &lt;&lt; &quot;write failure for &quot; &lt;&lt; filename &lt;&lt; '\n';
return 1;
}
std::fclose( fi );
std::cout &lt;&lt; &quot;created file &quot; &lt;&lt; filename &lt;&lt; '\n';
return 0;
}</pre>
</blockquote>
<p>After compiling and executing <a href="endian_example.cpp">endian_example.cpp</a>,
a hex dump of <code>test.dat</code> shows:</p>
<blockquote>
<pre>0102 0304 0000 0010 ffff ffff 0403 0201</pre>
</blockquote>
<h2><a name="Limitations">Limitations</a></h2>
<p>Requires <code>&lt;climits&gt;</code> <code>CHAR_BIT == 8</code>. If <code>CHAR_BIT</code>
is some other value, compilation will result in an <code>#error</code>. This
restriction is in place because the design, implementation, testing, and
documentation has only considered issues related to 8-bit bytes, and there have
been no real-world use cases presented for other sizes.</p>
<p>In C++03, <code>endian</code> does not meet the requirements for POD types
because it has constructors, private data members, and a base class. This means
that common use cases are relying on unspecified behavior in that the C++
Standard does not guarantee memory layout for non-POD types. This has not been a
problem in practice since all known C++ compilers do layout memory as if <code>
endian</code> were a POD type. In C++0x, it will be possible to specify the
default constructor as trivial, and private data members and base classes will
no longer disqualify a type from being a POD. Thus under C++0x, <code>endian</code>
will no longer be relying on unspecified behavior.</p>
<h2><a name="Feature-set">Feature set</a></h2>
<ul>
<li>Big endian| little endian | native endian byte ordering.</li>
<li>Signed | unsigned</li>
<li>Unaligned | aligned</li>
<li>1-8 byte (unaligned) | 2, 4, 8 byte (aligned)</li>
<li>Choice of integer value type</li>
</ul>
<h2><a name="Types">Typedefs</a></h2>
<p>One class template is provided:</p>
<blockquote>
<pre>template &lt;<a href="#endianness">endianness</a>::enum_t E, typename T, std::size_t n_bytes,
<a href="#alignment">alignment</a>::enum_t A = alignment::unaligned&gt;
class endian;
</pre>
</blockquote>
<p>Sixty typedefs, such as <code>big32_t</code>, provide convenient naming
conventions for common use cases:</p>
<blockquote>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="49%">
<tr>
<td width="18%" align="center"><b><i>Name</i></b></td>
<td width="10%" align="center"><b><i>Endianness</i></b></td>
<td width="10%" align="center"><b><i>Sign</i></b></td>
<td width="15%" align="center"><b><i>Sizes in bits (n)</i></b></td>
<td width="49%" align="center"><b><i>Alignment</i></b></td>
</tr>
<tr>
<td width="18%"><code>big</code><b><i>n</i></b><code>_t</code></td>
<td width="10%"><code>big</code></td>
<td width="10%">signed</td>
<td width="15%">8,16,24,32,40,48,56,64</td>
<td width="49%"><code>unaligned</code></td>
</tr>
<tr>
<td width="18%"><code>ubig</code><i><b>n</b></i><code>_t</code></td>
<td width="10%"><code>big</code></td>
<td width="10%">unsigned</td>
<td width="15%">8,16,24,32,40,48,56,64</td>
<td width="49%"><code>unaligned</code></td>
</tr>
<tr>
<td width="18%"><code>little</code><i><b>n</b></i><code>_t</code></td>
<td width="10%"><code>little</code></td>
<td width="10%">signed</td>
<td width="15%">8,16,24,32,40,48,56,64</td>
<td width="49%"><code>unaligned</code></td>
</tr>
<tr>
<td width="18%"><code>ulittle</code><i><b>n</b></i><code>_t</code></td>
<td width="10%"><code>little</code></td>
<td width="10%">unsigned</td>
<td width="15%">8,16,24,32,40,48,56,64</td>
<td width="49%"><code>unaligned</code></td>
</tr>
<tr>
<td width="18%"><code>native</code><i><b>n</b></i><code>_t</code></td>
<td width="10%"><code>native</code></td>
<td width="10%">signed</td>
<td width="15%">8,16,24,32,40,48,56,64</td>
<td width="49%"><code>unaligned</code></td>
</tr>
<tr>
<td width="18%"><code>unative</code><i><b>n</b></i><code>_t</code></td>
<td width="10%"><code>native</code></td>
<td width="10%">unsigned</td>
<td width="15%">8,16,24,32,40,48,56,64</td>
<td width="49%"><code>unaligned</code></td>
</tr>
<tr>
<td width="18%"><code>aligned_big</code><i><b>n</b></i><code>_t</code></td>
<td width="10%"><code>big</code></td>
<td width="10%">signed</td>
<td width="15%">16,32,64</td>
<td width="49%"><code>aligned</code></td>
</tr>
<tr>
<td width="18%"><code>aligned_ubig</code><i><b>n</b></i><code>_t</code></td>
<td width="10%"><code>big</code></td>
<td width="10%">unsigned</td>
<td width="15%">16,32,64</td>
<td width="49%"><code>aligned</code></td>
</tr>
<tr>
<td width="18%"><code>aligned_little</code><i><b>n</b></i><code>_t</code></td>
<td width="10%"><code>little</code></td>
<td width="10%">signed</td>
<td width="15%">16,32,64</td>
<td width="49%"><code>aligned</code></td>
</tr>
<tr>
<td width="18%"><code>aligned_ulittle</code><i><b>n</b></i><code>_t</code></td>
<td width="10%"><code>little</code></td>
<td width="10%">unsigned</td>
<td width="15%">16,32,64</td>
<td width="49%"><code>aligned</code></td>
</tr>
</table>
</blockquote>
<p>The unaligned types do not cause compilers to insert padding bytes in classes
and structs. This is an important characteristic that can be exploited to minimize wasted space in
memory, files, and network transmissions. </p>
<p><font color="#FF0000"><b><i><span style="background-color: #FFFFFF">Warning:</span></i></b></font><span style="background-color: #FFFFFF">
Code that uses a</span>ligned types is inherently non-portable because alignment
requirements vary between hardware architectures and because alignment may be
affected by compiler switches or pragmas. Furthermore, aligned types
are only available on architectures with 16, 32, and 64-bit integer types.</p>
<p><b><i>Note:</i></b> One-byte big-endian, little-endian, and native-endian types provide identical
functionality. All three names are provided to improve code readability and searchability.</p>
<h3><a name="Comment-on-naming">Comment on naming</a></h3>
<p>When first exposed to endian types, programmers often fit them into a mental model
based on the <code>&lt;cstdint&gt;</code> types. Using that model, it is natural to
expect a 56-bit big-endian signed integer to be named <code>int_big56_t</code>
rather than <code>big56_t</code>.</p>
<p>As experience using these type grows, the realization creeps in that they are
lousy arithmetic integers - they are really byte holders that for convenience
support arithmetic operations - and for use in internal interfaces or
anything more than trivial arithmetic computations it is far better to convert
values of these endian types to traditional integer types.</p>
<p>That seems to lead to formation of a new mental model specific to endian byte-holder types. In that model, the endianness
is the key feature, and the integer aspect is downplayed.
Once that mental transition is made, a name like <code>big56_t</code> is a good
reflection of the mental model</p>
<h2><a name="Class_template_endian">Class template <code>endian</code></a></h2>
<p>An endian is an integer byte-holder with user-specified <a href="#endianness">
endianness</a>, value type, size, and <a href="#alignment">alignment</a>. The
usual operations on integers are supplied.</p>
<h3><a name="Synopsis">Synopsis</a></h3>
<pre>namespace boost
{
namespace endian
{
enum class <a name="endianness">endianness</a> { big, little, native }; // scoped enum emulated on C++03
enum class <a name="alignment">alignment</a> { unaligned, aligned }; // scoped enum emulated on C++03
template &lt;endianness E, typename T, std::size_t n_bits,
alignment A = alignment::unaligned&gt;
class endian : <a href="../../../boost/endian/detail/cover_operators.hpp">cover_operators</a>&lt; endian&lt;E, T, n_bits, A&gt;, T &gt;
{
public:
typedef T value_type;
// if BOOST_ENDIAN_FORCE_PODNESS is defined &amp;&amp; C++0x POD's are not
// available then these two constructors will not be present
<a href="#endian">endian</a>() = default; // = default replaced by {} on C++03
explicit <a href="#explicit-endian">endian</a>(T v);
endian&amp; <a href="#operator-eq">operator=</a>(T v);
<a href="#operator-T">operator T</a>() const;
const char* <a href="#data">data</a>() const;
};
// unaligned big endian signed integer types
typedef endian&lt; endianness::big, int_least8_t, 8 &gt; big8_t;
typedef endian&lt; endianness::big, int_least16_t, 16 &gt; big16_t;
typedef endian&lt; endianness::big, int_least32_t, 24 &gt; big24_t;
typedef endian&lt; endianness::big, int_least32_t, 32 &gt; big32_t;
typedef endian&lt; endianness::big, int_least64_t, 40 &gt; big40_t;
typedef endian&lt; endianness::big, int_least64_t, 48 &gt; big48_t;
typedef endian&lt; endianness::big, int_least64_t, 56 &gt; big56_t;
typedef endian&lt; endianness::big, int_least64_t, 64 &gt; big64_t;
// unaligned big endian unsigned integer types
typedef endian&lt; endianness::big, uint_least8_t, 8 &gt; ubig8_t;
typedef endian&lt; endianness::big, uint_least16_t, 16 &gt; ubig16_t;
typedef endian&lt; endianness::big, uint_least32_t, 24 &gt; ubig24_t;
typedef endian&lt; endianness::big, uint_least32_t, 32 &gt; ubig32_t;
typedef endian&lt; endianness::big, uint_least64_t, 40 &gt; ubig40_t;
typedef endian&lt; endianness::big, uint_least64_t, 48 &gt; ubig48_t;
typedef endian&lt; endianness::big, uint_least64_t, 56 &gt; ubig56_t;
typedef endian&lt; endianness::big, uint_least64_t, 64 &gt; ubig64_t;
// unaligned little endian signed integer types
typedef endian&lt; endianness::little, int_least8_t, 8 &gt; little8_t;
typedef endian&lt; endianness::little, int_least16_t, 16 &gt; little16_t;
typedef endian&lt; endianness::little, int_least32_t, 24 &gt; little24_t;
typedef endian&lt; endianness::little, int_least32_t, 32 &gt; little32_t;
typedef endian&lt; endianness::little, int_least64_t, 40 &gt; little40_t;
typedef endian&lt; endianness::little, int_least64_t, 48 &gt; little48_t;
typedef endian&lt; endianness::little, int_least64_t, 56 &gt; little56_t;
typedef endian&lt; endianness::little, int_least64_t, 64 &gt; little64_t;
// unaligned little endian unsigned integer types
typedef endian&lt; endianness::little, uint_least8_t, 8 &gt; ulittle8_t;
typedef endian&lt; endianness::little, uint_least16_t, 16 &gt; ulittle16_t;
typedef endian&lt; endianness::little, uint_least32_t, 24 &gt; ulittle24_t;
typedef endian&lt; endianness::little, uint_least32_t, 32 &gt; ulittle32_t;
typedef endian&lt; endianness::little, uint_least64_t, 40 &gt; ulittle40_t;
typedef endian&lt; endianness::little, uint_least64_t, 48 &gt; ulittle48_t;
typedef endian&lt; endianness::little, uint_least64_t, 56 &gt; ulittle56_t;
typedef endian&lt; endianness::little, uint_least64_t, 64 &gt; ulittle64_t;
// unaligned native endian signed integer types
typedef endian&lt; endianness::native, int_least8_t, 8 &gt; native8_t;
typedef endian&lt; endianness::native, int_least16_t, 16 &gt; native16_t;
typedef endian&lt; endianness::native, int_least32_t, 24 &gt; native24_t;
typedef endian&lt; endianness::native, int_least32_t, 32 &gt; native32_t;
typedef endian&lt; endianness::native, int_least64_t, 40 &gt; native40_t;
typedef endian&lt; endianness::native, int_least64_t, 48 &gt; native48_t;
typedef endian&lt; endianness::native, int_least64_t, 56 &gt; native56_t;
typedef endian&lt; endianness::native, int_least64_t, 64 &gt; native64_t;
// unaligned native endian unsigned integer types
typedef endian&lt; endianness::native, uint_least8_t, 8 &gt; unative8_t;
typedef endian&lt; endianness::native, uint_least16_t, 16 &gt; unative16_t;
typedef endian&lt; endianness::native, uint_least32_t, 24 &gt; unative24_t;
typedef endian&lt; endianness::native, uint_least32_t, 32 &gt; unative32_t;
typedef endian&lt; endianness::native, uint_least64_t, 40 &gt; unative40_t;
typedef endian&lt; endianness::native, uint_least64_t, 48 &gt; unative48_t;
typedef endian&lt; endianness::native, uint_least64_t, 56 &gt; unative56_t;
typedef endian&lt; endianness::native, uint_least64_t, 64 &gt; unative64_t;
// These types only present if platform has exact size integers:
// aligned big endian signed integer types
typedef endian&lt; endianness::big, int16_t, 16, alignment::aligned &gt; aligned_big16_t;
typedef endian&lt; endianness::big, int32_t, 32, alignment::aligned &gt; aligned_big32_t;
typedef endian&lt; endianness::big, int64_t, 64, alignment::aligned &gt; aligned_big64_t;
// aligned big endian unsigned integer types
typedef endian&lt; endianness::big, uint16_t, 16, alignment::aligned &gt; aligned_ubig16_t;
typedef endian&lt; endianness::big, uint32_t, 32, alignment::aligned &gt; aligned_ubig32_t;
typedef endian&lt; endianness::big, uint64_t, 64, alignment::aligned &gt; aligned_ubig64_t;
// aligned little endian signed integer types
typedef endian&lt; endianness::little, int16_t, 16, alignment::aligned &gt; aligned_little2_t;
typedef endian&lt; endianness::little, int32_t, 32, alignment::aligned &gt; aligned_little4_t;
typedef endian&lt; endianness::little, int64_t, 64, alignment::aligned &gt; aligned_little8_t;
// aligned little endian unsigned integer types
typedef endian&lt; endianness::little, uint16_t, 16, alignment::aligned &gt; aligned_ulittle2_t;
typedef endian&lt; endianness::little, uint32_t, 32, alignment::aligned &gt; aligned_ulittle4_t;
typedef endian&lt; endianness::little, uint64_t, 64, alignment::aligned &gt; aligned_ulittle8_t;
// aligned native endian typedefs are not provided because
// &lt;cstdint&gt; types are superior for this use case
} // namespace endian
} // namespace boost</pre>
<h3><a name="Members">Members</a></h3>
<p><code><a name="endian">endian</a>() = default;&nbsp; // C++03: endian(){}</code></p>
<blockquote>
<p><i>Effects:</i> Constructs an object of type <code>endian&lt;E, T, n_bits, A&gt;</code>.</p>
</blockquote>
<p><code><a name="explicit-endian">explicit endian</a>(T v);</code></p>
<blockquote>
<p><i>Effects:</i> Constructs an object of type <code>endian&lt;E, T, n_bits, A&gt;</code>.</p>
<p><i>Postcondition:</i> <code>x == v,</code> where <code>x</code> is the
constructed object.</p>
</blockquote>
<p><code>endian&amp; <a name="operator-eq">operator=</a>(T v);</code></p>
<blockquote>
<p><i>Postcondition:</i> <code>x == v,</code> where <code>x</code> is the
constructed object.</p>
<p><i>Returns:</i> <code>*this</code>.</p>
</blockquote>
<p><code><a name="operator-T">operator T</a>() const;</code></p>
<blockquote>
<p><i>Returns:</i> The current value stored in <code>*this</code>, converted to
<code>value_type</code>.</p>
</blockquote>
<p><code>const char* <a name="data">data</a>() const;</code></p>
<blockquote>
<p><i>Returns:</i> A pointer to the first byte of the endian binary value stored
in <code>*this</code>.</p>
</blockquote>
<h3>Other operators</h3>
<p>Other operators on endian objects are forwarded to the equivalent
operator on <code>value_type</code>.</p>
<h2><a name="FAQ">FAQ</a></h2>
<p><b>Why bother with endian types?</b> External data portability and both speed
and space efficiency. Availability
of additional binary integer sizes and alignments is important in some
applications.</p>
<p><b>Why not just use Boost.Serialization?</b> Serialization involves a
conversion for every object involved in I/O. Endian integers require no
conversion or copying. They are already in the desired format for binary I/O.
Thus they can be read or written in bulk.</p>
<p><b>Why bother with binary I/O? Why not just use C++ Standard Library stream
inserters and extractors?</b> Using binary rather than character representations
can be more space efficient, with a side benefit of faster I/O. CPU time is
minimized because conversions to and from string are eliminated.
Furthermore, binary integers are fixed size, and so fixed-size disk records
are possible, 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>
<p><b>Do these types have any uses outside of I/O?</b> Native endianness can be used for fine grained control over size and
alignment, so may be used to save memory in applications not related to I/O.</p>
<p><b>Is there is a performance hit when doing arithmetic using these types?</b> Yes, for sure,
compared to arithmetic operations on native integer types. However, these types
are usually be faster, and sometimes much faster, for I/O compared to stream
inserters and extractors, or to serialization.</p>
<p><b>Are endian types POD's?</b> Yes for C++0x. No for C++03, although several
<a href="#Compilation">macros</a> are available to force PODness in all cases.</p>
<p><b>What are the implications endian integer types not being POD's with C++03
compilers?</b> They
can't be used in unions. Also, compilers aren't required to align or lay
out storage in portable ways, although this potential problem hasn't prevented
use of Boost.Endian with
real compilers.</p>
<p><b>Which is better, big-endian or little-endian?</b> Big-endian tends to be a
bit more of an industry standard, but little-endian may be preferred for
applications that run primarily on x86 (Intel/AMD) and other little-endian
CPU's. The <a href="http://en.wikipedia.org/wiki/Endian">Wikipedia</a> article
gives more pros and cons.</p>
<p><b>What good is <i>native </i>endianness?</b> It provides alignment and
size guarantees not available from the built-in types. It eases generic
programming.</p>
<p><b>Why bother with the aligned endian types?</b> Aligned integer operations
may be faster (20 times, in one measurement) if the endianness and alignment of
the type matches the endianness and alignment requirements of the machine. On
common CPU architectures, that optimization is only available for aligned types.
That allows I/O of maximally efficient types on an application's primary
platform, yet produces data files are portable to all platforms. The code,
however, is
likely to be more fragile and less portable than with the unaligned types.</p>
<p><b>These types are really just byte-holders. Why provide the arithmetic
operations at all?</b> Providing a full set of operations reduces program
clutter and makes code both easier to write and to read. Consider
incrementing a variable in a record. It is very convenient to write:</p>
<pre wrap> ++record.foo;</pre>
<p wrap>Rather than:</p>
<pre wrap> int temp(record.foo);
++temp;
record.foo = temp;</pre>
<h2><a name="Design">Design</a> considerations for Boost.Endian integers</h2>
<ul>
<li>Must be suitable for I/O - in other words, must be memcpyable.</li>
<li>Must provide exactly the size and internal byte ordering specified.</li>
<li>Must work correctly when the internal integer representation has more bits
that the sum of the bits in the external byte representation. Sign extension
must work correctly when the internal integer representation type has more
bits than the sum of the bits in the external bytes. For example, using
a 64-bit integer internally to represent 40-bit (5 byte) numbers must work for
both positive and negative values.</li>
<li>Must work correctly (including using the same defined external
representation) regardless of whether a compiler treats char as signed or
unsigned.</li>
<li>Unaligned types must not cause compilers to insert padding bytes.</li>
<li>The implementation should supply optimizations only in very limited
circumstances. Experience has shown that optimizations of endian
integers often become pessimizations. While this may be obvious when changing
machines or compilers, it also happens when changing compiler switches,
compiler versions, or CPU models of the same architecture.</li>
<li>It is better software engineering if the same implementation works regardless
of the CPU endianness. In other words, #ifdefs should be avoided where
possible.</li>
</ul>
<h2><a name="Experience">Experience</a></h2>
<p>Classes with similar functionality have been independently developed by
several Boost programmers and used very successful in high-value, high-use
applications for many years. These independently developed endian libraries
often evolved from C libraries that were also widely used. Endian integers have proven widely useful across a wide
range of computer architectures and applications.</p>
<h2><a name="Motivating-use-cases">Motivating use cases</a></h2>
<p>Neil Mayhew writes: &quot;I can also provide a meaningful use-case for this
library: reading TrueType font files from disk and processing the contents. The
data format has fixed endianness (big) and has unaligned values in various
places. Using Boost.Endian simplifies and cleans the code wonderfully.&quot;</p>
<h2><a name="C++0x">C++0x</a></h2>
<p>The availability of the C++0x
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">
Defaulted Functions</a> feature is detected automatically, and will be used if
present to ensure that objects of <code>class endian</code> are trivial, and
thus POD's.</p>
<h2><a name="Compilation">Compilation</a></h2>
<p>Boost.Endian is implemented entirely within headers, with no need to link to
any Boost object libraries.</p>
<p>Several macros allow user control over features:</p>
<ul>
<li>BOOST_ENDIAN_NO_CTORS causes <code>class endian</code> to have no
constructors. The intended use is for compiling user code that must be
portable between compilers regardless of C++0x
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">
Defaulted Functions</a> support. Use of constructors will always fail, <br>
&nbsp;</li>
<li>BOOST_ENDIAN_FORCE_PODNESS causes BOOST_ENDIAN_NO_CTORS to be defined if
the compiler does not support C++0x
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">
Defaulted Functions</a>. This is ensures that , and so can be used in unions.
In C++0x, <code>class endian</code> objects are POD's even though they have
constructors.</li>
</ul>
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
<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>
class template by Beman Dawes, who put the library together, provided
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
differs from endian representation size.</p>
<hr>
<p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05 September, 2011<!--webbot bot="Timestamp" endspan i-checksum="39338" --></p>
<p>© Copyright Beman Dawes, 2006-2009</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>
</body>
</html>