boostorg/endian
1
0
Fork 1
mirror of https://github.com/boostorg/endian.git synced 2025-08-02 05:54:31 +02:00
Code Issues Packages Projects Releases Wiki Activity

Continue cleanup

Browse Source 
git-svn-id: http://svn.boost.org/svn/boost/sandbox/endian@74222 b8fc166d-592f-0410-95f2-cb63ce0dd405
This commit is contained in:
bemandawes
2011-09-04 13:51:49 +00:00
parent d04d3b903e
commit 95ccedc67b
6 changed files with 113 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
boost/endian/integers.hpp
View File

@@ -1,4 +1,4 @@
// boost/endian/types.hpp ------------------------------------------------------------// // boost/endian/integers.hpp ---------------------------------------------------------//
// (C) Copyright Darin Adler 2000 // (C) Copyright Darin Adler 2000
// (C) Copyright Beman Dawes 2006, 2009 // (C) Copyright Beman Dawes 2006, 2009

33
libs/endian/doc/conversion.html
View File

@@ -25,8 +25,31 @@
<tr> <tr>
<td><a href="../../../index.htm">Boost Home</a>&nbsp;&nbsp;&nbsp;&nbsp; <td><a href="../../../index.htm">Boost Home</a>&nbsp;&nbsp;&nbsp;&nbsp;
<a href="index.html">Endian Home</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href="index.html">Endian Home</a>&nbsp;&nbsp;&nbsp;&nbsp;
<a href="conversion.html">Conversion Reference</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href="conversion.html">Conversion Functions</a>&nbsp;&nbsp;&nbsp;&nbsp;
<a href="types.html">Types Reference</a>&nbsp;&nbsp;&nbsp;&nbsp; Tutorial</td> <a href="integers.html">Integer Types</a>&nbsp;&nbsp;&nbsp;&nbsp; Tutorial</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> </tr>
</table> </table>
@@ -34,7 +57,7 @@
<p>Header <a href="../../../boost/endian/conversion.hpp">boost/endian/conversion.hpp</a> <p>Header <a href="../../../boost/endian/conversion.hpp">boost/endian/conversion.hpp</a>
provides functions that convert built-in provides functions that convert built-in
integers from the native byte ordering to or from big or little endian byte integers between native byte ordering and <a href="index.html#definition">big or little endian</a> byte
ordering.</p> ordering.</p>
<h2><a name="Reference">Reference</a></h2> <h2><a name="Reference">Reference</a></h2>
@@ -80,7 +103,7 @@ namespace endian
} // namespace endian } // namespace endian
} // namespace boost</pre> } // namespace boost</pre>
<h3 dir="ltr">Members</h3> <h3 dir="ltr"><a name="Members">Members</a></h3>
<pre dir="ltr">inline void reorder(int16_t&amp; x); <pre dir="ltr">inline void reorder(int16_t&amp; x);
inline void reorder(int32_t&amp; x); inline void reorder(int32_t&amp; x);
inline void reorder(int64_t&amp; x); inline void reorder(int64_t&amp; x);
@@ -122,7 +145,7 @@ template &lt;class T&gt; void little_to_native(T source, T&amp; target);</pre>
support endian conversion as separate from endian types.</p> support endian conversion as separate from endian types.</p>
<hr> <hr>
<p>Last revised: <p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->03 September, 2011<!--webbot bot="Timestamp" endspan i-checksum="39334" --></p> <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04 September, 2011<!--webbot bot="Timestamp" endspan i-checksum="39336" --></p>
<p><EFBFBD> Copyright Beman Dawes, 2011</p> <p><EFBFBD> Copyright Beman Dawes, 2011</p>
<p>Distributed under the Boost Software License, Version 1.0. See <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> <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/ LICENSE_1_0.txt</a></p>

72
libs/endian/doc/index.html
View File

@@ -25,10 +25,56 @@
<tr> <tr>
<td><a href="../../../index.htm">Boost Home</a>&nbsp;&nbsp;&nbsp;&nbsp; <td><a href="../../../index.htm">Boost Home</a>&nbsp;&nbsp;&nbsp;&nbsp;
<a href="index.html">Endian Home</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href="index.html">Endian Home</a>&nbsp;&nbsp;&nbsp;&nbsp;
<a href="conversion.html">Conversion Reference</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href="conversion.html">Conversion Functions</a>&nbsp;&nbsp;&nbsp;&nbsp;
<a href="types.html">Types Reference</a>&nbsp;&nbsp;&nbsp;&nbsp; Tutorial</td> <a href="integers.html">Integer Types</a>&nbsp;&nbsp;&nbsp;&nbsp; Tutorial</td>
</tr> </tr>
</table> </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> <h2><a name="Introduction-to-endianness">Introduction to endianness</a></h2>
@@ -54,23 +100,23 @@ output file produces:</p>
the least-significant byte first, while SPARC CPU's place the most-significant 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 byte first. Some CPU's, such as the PowerPC, allow the operating system to
choose which ordering applies.</p> choose which ordering applies.</p>
<p>The most-significant byte first ordering is traditionally called &quot;big endian&quot; <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 ordering and the least-significant-byte-first is traditionally called
&quot;little-endian&quot; ordering. The names are derived from &quot;little-endian&quot; ordering. The names are derived from
<a href="http://en.wikipedia.org/wiki/Jonathan_Swift" title="Jonathan Swift"> <a href="http://en.wikipedia.org/wiki/Jonathan_Swift" title="Jonathan Swift">
Jonathan Swift</a>'s satirical novel <i> Jonathan Swift</a>'s satirical novel <i>
<a href="http://en.wikipedia.org/wiki/Gulliver's_Travels" title="Gulliver's Travels"> <a href="http://en.wikipedia.org/wiki/Gulliver's_Travels" title="Gulliver's Travels">
Gulliver<EFBFBD>s Travels</a></i>, where rival kingdom's opened their soft-boiled eggs Gulliver<EFBFBD>s Travels</a></i>, where rival kingdoms opened their soft-boiled eggs
at different ends.</p> at different ends.</p>
<p>For a more complete introduction to endianness, see the Wikipedia's <p>See the Wikipedia's
<a href="http://en.wikipedia.org/wiki/Endianness">Endianness</a> article.</p> <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 <p>Except for reading an occasional core dump, most programmers can ignore
endianness. But when exchanging data with other computer systems, whether by endianness. But when exchanging binary integers with other computer systems, whether by
file transfers or over a network, programmers have to deal with endianness when file transfers or over a network, programmers have to deal with endianness. </p>
binary data is involved.</p> <h2><a name="Introduction">Introduction</a> to the Boost.Endian library</h2>
<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 Boost.Endian library provides facilities to deal with integer endianness.</p>
<p>The library provides two approaches to dealing with integer endianness:</p> <p>The library provides two approaches to dealing with integer endianness:</p>
@@ -115,7 +161,7 @@ Tomas Puverle, Vincente Botet, and
Yuval Ronen.</p> Yuval Ronen.</p>
<hr> <hr>
<p>Last revised: <p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->03 September, 2011<!--webbot bot="Timestamp" endspan i-checksum="39334" --></p> <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04 September, 2011<!--webbot bot="Timestamp" endspan i-checksum="39336" --></p>
<p><EFBFBD> Copyright Beman Dawes, 2011</p> <p><EFBFBD> Copyright Beman Dawes, 2011</p>
<p>Distributed under the Boost Software License, Version 1.0. See <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> <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/ LICENSE_1_0.txt</a></p>

78
libs/endian/doc/integers.html
View File

@@ -18,7 +18,7 @@
<a href="../../../index.html"> <a href="../../../index.html">
<img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86" border="0"></a></td> <img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86" border="0"></a></td>
<td width="413" align="middle"> <td width="413" align="middle">
<font size="7">Endian Integers</font> <font size="7">Endian Integer Types</font>
</td> </td>
</tr> </tr>
</table> </table>
@@ -27,8 +27,8 @@
<tr> <tr>
<td><a href="../../../index.htm">Boost Home</a>&nbsp;&nbsp;&nbsp;&nbsp; <td><a href="../../../index.htm">Boost Home</a>&nbsp;&nbsp;&nbsp;&nbsp;
<a href="index.html">Endian Home</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href="index.html">Endian Home</a>&nbsp;&nbsp;&nbsp;&nbsp;
<a href="conversion.html">Conversion Reference</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href="conversion.html">Conversion Functions</a>&nbsp;&nbsp;&nbsp;&nbsp;
<a href="types.html">Types Reference</a>&nbsp;&nbsp;&nbsp;&nbsp; Tutorial</td> <a href="integers.html">Integer Types</a>&nbsp;&nbsp;&nbsp;&nbsp; Tutorial</td>
</tr> </tr>
</table> </table>
@@ -50,7 +50,6 @@
<a href="#Synopsis">Synopsis</a><br> <a href="#Synopsis">Synopsis</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Members">Members</a><br> &nbsp;&nbsp;&nbsp; <a href="#Members">Members</a><br>
<a href="#FAQ">FAQ</a><br> <a href="#FAQ">FAQ</a><br>
<a href="#Binary-I-O-cautions">Binary I/O warnings and cautions</a><br>
<a href="#Example">Example</a><br> <a href="#Example">Example</a><br>
<a href="#Design">Design</a><br> <a href="#Design">Design</a><br>
<a href="#Experience">Experience</a><br> <a href="#Experience">Experience</a><br>
@@ -66,14 +65,12 @@
</tr> </tr>
<tr> <tr>
<td width="100%" bgcolor="#E8F5FF"> <td width="100%" bgcolor="#E8F5FF">
<a href="../../../boost/integer/endian.hpp">&lt;boost/integer/endian.hpp&gt;</a><br> <a href="../../../boost/endian/conversion.hpp">&lt;boost/endian/conversion.hpp&gt;</a><br>
<a href="../../../boost/integer/endian_binary_stream.hpp">&lt;boost/integer/endian_binary_stream.hpp&gt;</a><br> <a href="../../../boost/endian/integers.hpp">&lt;boost/endian/integers.hpp&gt;</a></td>
<a href="../../../boost/binary_stream.hpp">&lt;boost/binary_stream.hpp&gt;</a></td>
</tr> </tr>
</table> </table>
<h2><a name="Introduction">Introduction</a></h2> <h2><a name="Introduction">Introduction</a></h2>
<p>Header <p>Header <a href="file:///D:/endian/boost/endian/integers.hpp">&lt;boost/endian/integers.hpp&gt;</a> provides
<a href="../../../boost/integer/endian.hpp">&lt;boost/integer/endian.hpp&gt;</a> provides
integer-like byte-holder binary types with explicit control over integer-like byte-holder binary types with explicit control over
byte order, value type, size, and alignment. Typedefs provide easy-to-use names byte order, value type, size, and alignment. Typedefs provide easy-to-use names
for common configurations.</p> for common configurations.</p>
@@ -100,13 +97,6 @@ arithmetic operators are <code>+</code>, <code>+=</code>, <code>-</code>, <code>
<code>&gt;&gt;=</code>. Binary relational operators are <code>==</code>, <code>!=</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> <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> <p>Automatic conversion is provided to the underlying integer value type.</p>
<p>Header <a href="../../../boost/integer/endian_binary_stream.hpp">&lt;boost/integer/endian_binary_stream.hpp&gt;</a>
provides operators &lt;= and <code>=&gt;</code> for unformatted binary (as opposed to
formatted character) stream insertion and extraction of endian types.</p>
<p>Header <a href="../../../boost/binary_stream.hpp">&lt;boost/binary_stream.hpp&gt;</a>
provides operators &lt;= and <code>=&gt;</code> for unformatted binary (as opposed to
formatted character) stream insertion and extraction of built-in and std::string
types.</p>
<h2><a name="Hello-endian-world">Hello endian world</a></h2> <h2><a name="Hello-endian-world">Hello endian world</a></h2>
<blockquote> <blockquote>
<pre>#include &lt;boost/integer/endian.hpp&gt; <pre>#include &lt;boost/integer/endian.hpp&gt;
@@ -268,7 +258,7 @@ expect a 56-bit big-endian signed integer to be named <code>int_big56_t</code>
rather than <code>big56_t</code>.</p> rather than <code>big56_t</code>.</p>
<p>As experience using these type grows, the realization creeps in that they are <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 lousy arithmetic integers - they are really byte holders that for convenience
support arithmetic operations - and that for use in internal interfaces or support arithmetic operations - and for use in internal interfaces or
anything more than trivial arithmetic computations it is far better to convert anything more than trivial arithmetic computations it is far better to convert
values of these endian types to traditional integer types.</p> 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 <p>That seems to lead to formation of a new mental model specific to endian byte-holder types. In that model, the endianness
@@ -282,7 +272,7 @@ usual operations on integers are supplied.</p>
<h3><a name="Synopsis">Synopsis</a></h3> <h3><a name="Synopsis">Synopsis</a></h3>
<pre>namespace boost <pre>namespace boost
{ {
namespace integer namespace endian
{ {
enum class <a name="endianness">endianness</a> { big, little, native }; // scoped enum emulated on C++03 enum class <a name="endianness">endianness</a> { big, little, native }; // scoped enum emulated on C++03
@@ -290,7 +280,7 @@ usual operations on integers are supplied.</p>
template &lt;endianness E, typename T, std::size_t n_bits, template &lt;endianness E, typename T, std::size_t n_bits,
alignment A = alignment::unaligned&gt; alignment A = alignment::unaligned&gt;
class endian : <a href="../../../boost/integer/cover_operators.hpp">integer_cover_operators</a>&lt; endian&lt;E, T, n_bits, A&gt;, T &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: public:
typedef T value_type; typedef T value_type;
@@ -300,7 +290,7 @@ usual operations on integers are supplied.</p>
<a href="#endian">endian</a>() = default; // = default replaced by {} on C++03 <a href="#endian">endian</a>() = default; // = default replaced by {} on C++03
explicit <a href="#explicit-endian">endian</a>(T v); explicit <a href="#explicit-endian">endian</a>(T v);
endian &amp; <a href="#operator-eq">operator=</a>(T v); endian&amp; <a href="#operator-eq">operator=</a>(T v);
<a href="#operator-T">operator T</a>() const; <a href="#operator-T">operator T</a>() const;
const char* <a href="#data">data</a>() const; const char* <a href="#data">data</a>() const;
}; };
@@ -391,7 +381,7 @@ usual operations on integers are supplied.</p>
// aligned native endian typedefs are not provided because // aligned native endian typedefs are not provided because
// &lt;cstdint&gt; types are superior for this use case // &lt;cstdint&gt; types are superior for this use case
} // namespace integer } // namespace endian
} // namespace boost</pre> } // namespace boost</pre>
<h3><a name="Members">Members</a></h3> <h3><a name="Members">Members</a></h3>
<p><code><a name="endian">endian</a>() = default;&nbsp; // C++03: endian(){}</code></p> <p><code><a name="endian">endian</a>() = default;&nbsp; // C++03: endian(){}</code></p>
@@ -404,7 +394,7 @@ usual operations on integers are supplied.</p>
<p><i>Postcondition:</i> <code>x == v,</code> where <code>x</code> is the <p><i>Postcondition:</i> <code>x == v,</code> where <code>x</code> is the
constructed object.</p> constructed object.</p>
</blockquote> </blockquote>
<p><code>endian &amp; <a name="operator-eq">operator=</a>(T v);</code></p> <p><code>endian&amp; <a name="operator-eq">operator=</a>(T v);</code></p>
<blockquote> <blockquote>
<p><i>Postcondition:</i> <code>x == v,</code> where <code>x</code> is the <p><i>Postcondition:</i> <code>x == v,</code> where <code>x</code> is the
constructed object.</p> constructed object.</p>
@@ -429,7 +419,7 @@ and space efficiency. Availability
of additional binary integer sizes and alignments is important in some of additional binary integer sizes and alignments is important in some
applications.</p> applications.</p>
<p><b>Why not just use Boost.Serialization?</b> Serialization involves a <p><b>Why not just use Boost.Serialization?</b> Serialization involves a
conversion for every object involved in I/O. Endian objects require no 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. conversion or copying. They are already in the desired format for binary I/O.
Thus they can be read or written in bulk.</p> 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 <p><b>Why bother with binary I/O? Why not just use C++ Standard Library stream
@@ -441,16 +431,15 @@ are possible, easing sorting and allowing direct access. Disadvantages, such as
text utilities on the resulting files, limit usefulness to applications where text utilities on the resulting files, limit usefulness to applications where
the the
binary I/O advantages are paramount.</p> binary I/O advantages are paramount.</p>
<p><b>Do these types have any uses outside of I/O?</b> Probably not, except for <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
native endianness which 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>
alignment.</p>
<p><b>Is there is a performance hit when doing arithmetic using these types?</b> Yes, for sure, <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 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 are usually be faster, and sometimes much faster, for I/O compared to stream
inserters and extractors, or to serialization.</p> 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 <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> <a href="#Compilation">macros</a> are available to force PODness in all cases.</p>
<p><b>What are the implications endian types not being POD's with C++03 <p><b>What are the implications endian integer types not being POD's with C++03
compilers?</b> They compilers?</b> They
can't be used in unions. Also, compilers aren't required to align or lay 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 out storage in portable ways, although this potential problem hasn't prevented
@@ -478,40 +467,19 @@ 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> incrementing a variable in a record. It is very convenient to write:</p>
<pre wrap> ++record.foo;</pre> <pre wrap> ++record.foo;</pre>
<p wrap>Rather than:</p> <p wrap>Rather than:</p>
<pre wrap> int temp( record.foo); <pre wrap> int temp(record.foo);
++temp; ++temp;
record.foo = temp;</pre> record.foo = temp;</pre>
<p wrap><b>Why do binary stream insertion and extraction use operators &lt;= and &gt;=
rather than &lt;&lt;= and &gt;&gt;=?</b> &lt;&lt;= and &gt;&gt;= associate right-to-left, which is the
opposite of &lt;&lt; and &gt;&gt;, so would be very confusing and error prone. &lt;= and &gt;=
associate left-to-right. </p>
<h2><a name="Binary-I-O-cautions">Binary I/O warnings and cautions</a></h2>
<p><font color="#FF0000"><b><i><span style="background-color: #FFFFFF">Warning:</span></i></b></font><span style="background-color: #FFFFFF"> </span>&nbsp;Use
only on streams opened with filemode <code>std::ios_base::binary</code>. Thus
unformatted binary I/O should not be with the standard streams (cout, cin, etc.)
since they are opened in text mode. Use on text streams may produce incorrect
results, such as insertion of unwanted characters or premature end-of-file. For
example, on Windows 0x0D would become 0x0D, 0x0A.</p>
<p><i><b><font color="#FF0000">Caution:</font><font color="#FFFF00"> </font></b>
</i>When mixing formatted (i.e. operator &lt;&lt; or &gt;&gt;) and unformatted (i.e.
operator &lt;= or &gt;=) stream I/O, be aware that &lt;&lt; and &gt;&gt; take precedence over &lt;=
and &gt;=. Use parentheses to force correct order of evaluation. For example:</p>
<blockquote>
<pre>my_stream &lt;&lt; foo &lt;= bar; // no parentheses needed
(my_stream &lt;= foo) &lt;&lt; bar; // parentheses required </pre>
</blockquote>
<p>As a practical matter, it may be easier and safer to never mix the character
and binary insertion or extraction operators in the same statement.</p>
<h2><a name="Example">Example</a></h2> <h2><a name="Example">Example</a></h2>
<p>The <a href="../example/endian_example.cpp">endian_example.cpp</a> program writes a <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> binary file containing four byte big-endian and little-endian integers:</p>
<blockquote> <blockquote>
<pre>#include &lt;iostream&gt; <pre>#include &lt;iostream&gt;
#include &lt;cassert&gt;
#include &lt;cstdio&gt; #include &lt;cstdio&gt;
#include &lt;boost/integer/endian.hpp&gt; #include &lt;boost/endian/integers.hpp&gt;
#include &lt;boost/static_assert.hpp&gt;
using namespace boost::integer; using namespace boost::endian;
namespace namespace
{ {
@@ -533,7 +501,7 @@ namespace
int main() int main()
{ {
assert( sizeof( header ) == 16 ); // requirement for interoperability BOOST_STATIC_ASSERT( sizeof( header ) == 16U ); // check requirement
header h; header h;
@@ -572,7 +540,7 @@ int main()
<blockquote> <blockquote>
<pre>0403 0201 0000 0010 ffff ffff 0102 0304</pre> <pre>0403 0201 0000 0010 ffff ffff 0102 0304</pre>
</blockquote> </blockquote>
<h2><a name="Design">Design</a> considerations for Boost.Endian</h2> <h2><a name="Design">Design</a> considerations for Boost.Endian integers</h2>
<ul> <ul>
<li>Must be suitable for I/O - in other words, must be memcpyable.</li> <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 provide exactly the size and internal byte ordering specified.</li>
@@ -639,7 +607,7 @@ sign partial specialization to correctly extend the sign when cover integer size
differs from endian representation size.</p> differs from endian representation size.</p>
<hr> <hr>
<p>Last revised: <p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->03 September, 2011<!--webbot bot="Timestamp" endspan i-checksum="39334" --></p> <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04 September, 2011<!--webbot bot="Timestamp" endspan i-checksum="39336" --></p>
<p><EFBFBD> Copyright Beman Dawes, 2006-2009</p> <p><EFBFBD> Copyright Beman Dawes, 2006-2009</p>
<p>Distributed under the Boost Software License, Version 1.0. See <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> <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/ LICENSE_1_0.txt</a></p>

5
libs/endian/example/endian_example.cpp
View File

@@ -16,7 +16,6 @@
#include <iostream> #include <iostream>
#include <cstdio> #include <cstdio>
#include <boost/endian/integers.hpp> #include <boost/endian/integers.hpp>
#include <boost/detail/lightweight_main.hpp>
#include <boost/static_assert.hpp> #include <boost/static_assert.hpp>
using namespace boost::endian; using namespace boost::endian;
@@ -39,9 +38,9 @@ namespace
const char * filename = "test.dat"; const char * filename = "test.dat";
} }
int cpp_main(int, char * []) int main(int, char * [])
{ {
BOOST_STATIC_ASSERT( sizeof( header ) == 16U ); // requirement for interoperability BOOST_STATIC_ASSERT( sizeof( header ) == 16U ); // check requirement
header h; header h;

1
libs/endian/test/endian_test.cpp
View File

@@ -20,7 +20,6 @@
#include <boost/endian/integers.hpp> #include <boost/endian/integers.hpp>
#include <boost/cstdint.hpp> #include <boost/cstdint.hpp>
#include <boost/progress.hpp>
#include <boost/detail/lightweight_main.hpp> #include <boost/detail/lightweight_main.hpp>
#include <iostream> #include <iostream>