forked from boostorg/endian
Directory reorg to follow Boost Git practice.
This commit is contained in:
1 parent
d549e3bdd3
commit
d131123327
27 files changed
No files matched your search
@@ -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>
|
||||
<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="#Introduction">Introduction</a><br>
|
||||
<a href="#Reference">Reference</a><br>
|
||||
<a href="#Synopsis">Synopsis</a><br>
|
||||
<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"><boost/endian/conversion.hpp></a><br>
|
||||
<a href="../../../boost/endian/integers.hpp"><boost/endian/integers.hpp></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& x);
|
||||
inline void reorder(int32_t& x);
|
||||
inline void reorder(int64_t& x);
|
||||
inline void reorder(uint16_t& x);
|
||||
inline void reorder(uint32_t& x);
|
||||
inline void reorder(uint64_t& x);
|
||||
|
||||
// unconditional non-modifying reverse byte order copy
|
||||
|
||||
inline void reorder(int16_t source, int16_t& target);
|
||||
inline void reorder(int32_t source, int32_t& target);
|
||||
inline void reorder(int64_t source, int64_t& target);
|
||||
inline void reorder(uint16_t source, uint16_t& target);
|
||||
inline void reorder(uint32_t source, uint32_t& target);
|
||||
inline void reorder(uint64_t source, uint64_t& target);
|
||||
|
||||
// conditional modifying (i.e. in-place) reverse byte order
|
||||
|
||||
template <class T> void native_to_big(T& x);
|
||||
template <class T> void native_to_little(T& x);
|
||||
template <class T> void big_to_native(T& x);
|
||||
template <class T> void little_to_native(T& x);
|
||||
|
||||
// non-modifying conditional reverse byte order copy
|
||||
|
||||
template <class T> void native_to_big(T source, T& target);
|
||||
template <class T> void native_to_little(T source, T& target);
|
||||
template <class T> void big_to_native(T source, T& target);
|
||||
template <class T> void little_to_native(T source, T& target);
|
||||
|
||||
} // namespace endian
|
||||
} // namespace boost</pre>
|
||||
<h3 dir="ltr"><a name="Members">Members</a></h3>
|
||||
<pre dir="ltr">inline void reorder(int16_t& x);
|
||||
inline void reorder(int32_t& x);
|
||||
inline void reorder(int64_t& x);
|
||||
inline void reorder(uint16_t& x);
|
||||
inline void reorder(uint32_t& x);
|
||||
inline void reorder(uint64_t& 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& target);
|
||||
inline void reorder(int32_t source, int32_t& target);
|
||||
inline void reorder(int64_t source, int64_t& target);
|
||||
inline void reorder(uint16_t source, uint16_t& target);
|
||||
inline void reorder(uint32_t source, uint32_t& target);
|
||||
inline void reorder(uint64_t source, uint64_t& 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 <class T> void native_to_big(T& x);
|
||||
template <class T> void native_to_little(T& x);
|
||||
template <class T> void big_to_native(T& x);
|
||||
template <class T> void little_to_native(T& 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 <class T> void native_to_big(T source, T& target);
|
||||
template <class T> void native_to_little(T source, T& target);
|
||||
template <class T> void big_to_native(T source, T& target);
|
||||
template <class T> void little_to_native(T source, T& 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>
|
||||
@@ -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 - "Absolutely. I'd like to see support for float and
|
||||
double, but<br>
|
||||
even without those additions, I still vote yes." "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."<br>
|
||||
</li>
|
||||
<li dir="ltr">
|
||||
<p dir="ltr">Hartmut Kaiser - "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. "<br>
|
||||
</li>
|
||||
<li dir="ltr">
|
||||
<p dir="ltr">Robert Stewart - "There are issues that keep me from saying yes
|
||||
at this time. There are too many suggested variations and ideas under
|
||||
consideration to accept the library in its present state. 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."<br>
|
||||
</li>
|
||||
<li dir="ltr">
|
||||
<p dir="ltr">Tim Blechmann - "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>
|
||||
documentation."<br>
|
||||
</li>
|
||||
<li dir="ltr">
|
||||
<p dir="ltr">Vicente J. Botet Escriba - "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."</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>
|
||||
uint16_t a;<br>
|
||||
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>> section `experience': this section gives no insights for people who use
|
||||
or<br>
|
||||
> read the code. it mainly tells: "we are not the first and the domain of the<br>
|
||||
> library is important.". imo this section can be removed (maybe the part that<br>
|
||||
> it is not related to any c library can go to the `design considerations'<br>
|
||||
><br>
|
||||
> section "motivating use cases": this is more a marketing blurb/testimonial.<br>
|
||||
> maybe this could be changed to a section about possible use cases, listing<br>
|
||||
> `communicating between different devices' and `reading/writing of binary
|
||||
file<br>
|
||||
> 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>
|
||||
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>
|
||||
user will get some information that are necessary to use the library by<br>
|
||||
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>
|
||||
historical notes, compiler-specific stuff, includes and ifdefs. imo, this is<br>
|
||||
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>
|
||||
</li>
|
||||
<li>
|
||||
<div class="im">
|
||||
> explaining the other builting types are not considered. Why only
|
||||
big/little<br>
|
||||
> 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">
|
||||
"unaligned integer", 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">
|
||||
> 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>
|
||||
</li>
|
||||
<li>> The endianness scoped enum native should be replaced so it is defined<br>
|
||||
> depending on the endianess of the platform.<br>
|
||||
><br>
|
||||
> BOOST_SCOPED_ENUM_START(<wbr />endianness) { big, little, native=(big or
|
||||
little)<br>
|
||||
> }; BOOST_SCOPED_ENUM_END<br>
|
||||
><br>
|
||||
> This will have the advantage to reduce of 1/3 the number of specializations.<br>
|
||||
<br>
|
||||
Does this work?<br>
|
||||
</li>
|
||||
<li dir="ltr">
|
||||
<div class="im">
|
||||
> The library should provide in addition endian conversion functions that
|
||||
have<br>
|
||||
> 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">
|
||||
> endian_operations_test.cpp and endian_in_union_test.cpp ... maybe rename
|
||||
from<br>
|
||||
> _test.cpp to _compile_test.cpp? they don't seem to do any run-time tests.
|
||||
they<br>
|
||||
> also should not include <cassert> since no assertion statement is needed,
|
||||
this<br>
|
||||
> 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> </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>
|
||||
</div>
|
||||
<p> </p>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
+173
@@ -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>
|
||||
<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>
|
||||
@@ -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>
|
||||
<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="#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>
|
||||
<a href="#Comment-on-naming">Comment on naming</a><br>
|
||||
<a href="#Class_template_endian">Class template <code>endian</code></a><br>
|
||||
|
||||
<a href="#Synopsis">Synopsis</a><br>
|
||||
<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"><boost/endian/conversion.hpp></a><br>
|
||||
<a href="../../../boost/endian/integers.hpp"><boost/endian/integers.hpp></a></td>
|
||||
</tr>
|
||||
</table>
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
<p>Header <a href="file:///D:/endian/boost/endian/integers.hpp"><boost/endian/integers.hpp></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 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>&</code>, <code>&=</code>, <code>|</code>, <code>|=</code>,
|
||||
<code>^</code>, <code>^=</code>, <code><<</code>, <code><<=</code>, <code>>></code>,
|
||||
<code>>>=</code>. Binary relational operators are <code>==</code>, <code>!=</code>,
|
||||
<code><</code>, <code><=</code>, <code>></code>, <code>>=</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 <iostream>
|
||||
#include <cstdio>
|
||||
#include <boost/endian/integers.hpp>
|
||||
#include <boost/static_assert.hpp>
|
||||
|
||||
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 = "test.dat";
|
||||
}
|
||||
|
||||
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 <cstdio> 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, <cstdio> fopen/fwrite is used for I/O in this example.
|
||||
|
||||
std::FILE * fi;
|
||||
|
||||
if ( !(fi = std::fopen( filename, "wb" )) ) // MUST BE BINARY
|
||||
{
|
||||
std::cout << "could not open " << filename << '\n';
|
||||
return 1;
|
||||
}
|
||||
|
||||
if ( std::fwrite( &h, sizeof( header ), 1, fi ) != 1 )
|
||||
{
|
||||
std::cout << "write failure for " << filename << '\n';
|
||||
return 1;
|
||||
}
|
||||
|
||||
std::fclose( fi );
|
||||
|
||||
std::cout << "created file " << filename << '\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><climits></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 <<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>
|
||||
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><cstdint></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 <endianness E, typename T, std::size_t n_bits,
|
||||
alignment A = alignment::unaligned>
|
||||
class endian : <a href="../../../boost/endian/detail/cover_operators.hpp">cover_operators</a>< endian<E, T, n_bits, A>, T >
|
||||
{
|
||||
public:
|
||||
typedef T value_type;
|
||||
|
||||
// if BOOST_ENDIAN_FORCE_PODNESS is defined && 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& <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< endianness::big, int_least8_t, 8 > big8_t;
|
||||
typedef endian< endianness::big, int_least16_t, 16 > big16_t;
|
||||
typedef endian< endianness::big, int_least32_t, 24 > big24_t;
|
||||
typedef endian< endianness::big, int_least32_t, 32 > big32_t;
|
||||
typedef endian< endianness::big, int_least64_t, 40 > big40_t;
|
||||
typedef endian< endianness::big, int_least64_t, 48 > big48_t;
|
||||
typedef endian< endianness::big, int_least64_t, 56 > big56_t;
|
||||
typedef endian< endianness::big, int_least64_t, 64 > big64_t;
|
||||
|
||||
// unaligned big endian unsigned integer types
|
||||
typedef endian< endianness::big, uint_least8_t, 8 > ubig8_t;
|
||||
typedef endian< endianness::big, uint_least16_t, 16 > ubig16_t;
|
||||
typedef endian< endianness::big, uint_least32_t, 24 > ubig24_t;
|
||||
typedef endian< endianness::big, uint_least32_t, 32 > ubig32_t;
|
||||
typedef endian< endianness::big, uint_least64_t, 40 > ubig40_t;
|
||||
typedef endian< endianness::big, uint_least64_t, 48 > ubig48_t;
|
||||
typedef endian< endianness::big, uint_least64_t, 56 > ubig56_t;
|
||||
typedef endian< endianness::big, uint_least64_t, 64 > ubig64_t;
|
||||
|
||||
// unaligned little endian signed integer types
|
||||
typedef endian< endianness::little, int_least8_t, 8 > little8_t;
|
||||
typedef endian< endianness::little, int_least16_t, 16 > little16_t;
|
||||
typedef endian< endianness::little, int_least32_t, 24 > little24_t;
|
||||
typedef endian< endianness::little, int_least32_t, 32 > little32_t;
|
||||
typedef endian< endianness::little, int_least64_t, 40 > little40_t;
|
||||
typedef endian< endianness::little, int_least64_t, 48 > little48_t;
|
||||
typedef endian< endianness::little, int_least64_t, 56 > little56_t;
|
||||
typedef endian< endianness::little, int_least64_t, 64 > little64_t;
|
||||
|
||||
// unaligned little endian unsigned integer types
|
||||
typedef endian< endianness::little, uint_least8_t, 8 > ulittle8_t;
|
||||
typedef endian< endianness::little, uint_least16_t, 16 > ulittle16_t;
|
||||
typedef endian< endianness::little, uint_least32_t, 24 > ulittle24_t;
|
||||
typedef endian< endianness::little, uint_least32_t, 32 > ulittle32_t;
|
||||
typedef endian< endianness::little, uint_least64_t, 40 > ulittle40_t;
|
||||
typedef endian< endianness::little, uint_least64_t, 48 > ulittle48_t;
|
||||
typedef endian< endianness::little, uint_least64_t, 56 > ulittle56_t;
|
||||
typedef endian< endianness::little, uint_least64_t, 64 > ulittle64_t;
|
||||
|
||||
// unaligned native endian signed integer types
|
||||
typedef endian< endianness::native, int_least8_t, 8 > native8_t;
|
||||
typedef endian< endianness::native, int_least16_t, 16 > native16_t;
|
||||
typedef endian< endianness::native, int_least32_t, 24 > native24_t;
|
||||
typedef endian< endianness::native, int_least32_t, 32 > native32_t;
|
||||
typedef endian< endianness::native, int_least64_t, 40 > native40_t;
|
||||
typedef endian< endianness::native, int_least64_t, 48 > native48_t;
|
||||
typedef endian< endianness::native, int_least64_t, 56 > native56_t;
|
||||
typedef endian< endianness::native, int_least64_t, 64 > native64_t;
|
||||
|
||||
// unaligned native endian unsigned integer types
|
||||
typedef endian< endianness::native, uint_least8_t, 8 > unative8_t;
|
||||
typedef endian< endianness::native, uint_least16_t, 16 > unative16_t;
|
||||
typedef endian< endianness::native, uint_least32_t, 24 > unative24_t;
|
||||
typedef endian< endianness::native, uint_least32_t, 32 > unative32_t;
|
||||
typedef endian< endianness::native, uint_least64_t, 40 > unative40_t;
|
||||
typedef endian< endianness::native, uint_least64_t, 48 > unative48_t;
|
||||
typedef endian< endianness::native, uint_least64_t, 56 > unative56_t;
|
||||
typedef endian< endianness::native, uint_least64_t, 64 > unative64_t;
|
||||
|
||||
// These types only present if platform has exact size integers:
|
||||
|
||||
// aligned big endian signed integer types
|
||||
typedef endian< endianness::big, int16_t, 16, alignment::aligned > aligned_big16_t;
|
||||
typedef endian< endianness::big, int32_t, 32, alignment::aligned > aligned_big32_t;
|
||||
typedef endian< endianness::big, int64_t, 64, alignment::aligned > aligned_big64_t;
|
||||
|
||||
// aligned big endian unsigned integer types
|
||||
typedef endian< endianness::big, uint16_t, 16, alignment::aligned > aligned_ubig16_t;
|
||||
typedef endian< endianness::big, uint32_t, 32, alignment::aligned > aligned_ubig32_t;
|
||||
typedef endian< endianness::big, uint64_t, 64, alignment::aligned > aligned_ubig64_t;
|
||||
|
||||
// aligned little endian signed integer types
|
||||
typedef endian< endianness::little, int16_t, 16, alignment::aligned > aligned_little2_t;
|
||||
typedef endian< endianness::little, int32_t, 32, alignment::aligned > aligned_little4_t;
|
||||
typedef endian< endianness::little, int64_t, 64, alignment::aligned > aligned_little8_t;
|
||||
|
||||
// aligned little endian unsigned integer types
|
||||
typedef endian< endianness::little, uint16_t, 16, alignment::aligned > aligned_ulittle2_t;
|
||||
typedef endian< endianness::little, uint32_t, 32, alignment::aligned > aligned_ulittle4_t;
|
||||
typedef endian< endianness::little, uint64_t, 64, alignment::aligned > aligned_ulittle8_t;
|
||||
|
||||
|
||||
// aligned native endian typedefs are not provided because
|
||||
// <cstdint> 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; // C++03: endian(){}</code></p>
|
||||
<blockquote>
|
||||
<p><i>Effects:</i> Constructs an object of type <code>endian<E, T, n_bits, A></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<E, T, n_bits, A></code>.</p>
|
||||
<p><i>Postcondition:</i> <code>x == v,</code> where <code>x</code> is the
|
||||
constructed object.</p>
|
||||
</blockquote>
|
||||
<p><code>endian& <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: "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."</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>
|
||||
</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>
|
||||
Reference in new issue
Block a user