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

Last pass through docs

Browse Source
This commit is contained in:
Beman
2013-05-28 11:04:03 -04:00
parent 9c25d54d38
commit b541dfb790
4 changed files with 142 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files

155
doc/conversion.html
View File

@@ -3,7 +3,7 @@
<head> <head>
<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> <meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document"> <meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Boost Endian Conversion Functions</title> <title>Boost Endian Conversion Functions</title>
<link rel="stylesheet" type="text/css" href="../../../doc/src/minimal.css"> <link rel="stylesheet" type="text/css" href="../../../doc/src/minimal.css">
@@ -26,7 +26,7 @@
<td><b><a href="../../../index.htm">Boost Home</a>&nbsp;&nbsp;&nbsp;&nbsp; <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="index.html">Endian Home</a>&nbsp;&nbsp;&nbsp;&nbsp;
<a href="conversion.html">Conversion Functions</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href="conversion.html">Conversion Functions</a>&nbsp;&nbsp;&nbsp;&nbsp;
<a href="types.html">Endian Types</a>&nbsp;&nbsp;&nbsp;&nbsp; Tutorial</b></td> <a href="types.html">Endian Types</a></b></td>
</tr> </tr>
</table> </table>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" align="right"> <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" align="right">
@@ -37,12 +37,11 @@
<tr> <tr>
<td width="100%" bgcolor="#E8F5FF"> <td width="100%" bgcolor="#E8F5FF">
<a href="#Introduction">Introduction</a><br> <a href="#Introduction">Introduction</a><br>
<a href="#FAQ">conversion.hpp FAQ</a><br>
<a href="#Reference">Reference</a><br> <a href="#Reference">Reference</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Synopsis">Synopsis</a><br> &nbsp;&nbsp;&nbsp; <a href="#Synopsis">Synopsis</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Requirements">Requirements</a><br> &nbsp;&nbsp;&nbsp; <a href="#Requirements">Requirements</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Functions">Functions</a><br> &nbsp;&nbsp;&nbsp; <a href="#Functions">Functions</a><br>
<a href="#Intrinsic">Intrinsic built-in support</a><br> <a href="#FAQ">FAQ</a><br>
<a href="#Acknowledgements">Acknowledgements</a></td> <a href="#Acknowledgements">Acknowledgements</a></td>
</tr> </tr>
<tr> <tr>
@@ -58,13 +57,6 @@
<h2><a name="Introduction">Introduction</a></h2> <h2><a name="Introduction">Introduction</a></h2>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
<tr>
<td bgcolor="#FFFFCC">Please: If you haven't done so already, read
<a href="index.html#Introduction-to-endianness">Introduction to endianness</a>!</td>
</tr>
</table>
<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 byte order reversal and conversion functions that convert objects of provides byte order reversal and conversion functions that convert objects of
the multi-byte built-in the multi-byte built-in
@@ -79,70 +71,6 @@ ordering. User defined types are also supported.</p>
</tr> </tr>
</table> </table>
<h2>conversion.hpp <a name="FAQ">FAQ</a></h2>
<p><b>Is the implementation header only?</b></p>
<blockquote>
<p>Yes.</p>
</blockquote>
<p><b>Does the implementation use compiler intrinsic built-in byte swapping?</b></p>
<blockquote>
<p>Yes, if available. See <a href="#Intrinsic">Intrinsic built-in support</a>
below.</p>
</blockquote>
<p><b>Why are the template versions of <code>reverse()</code> and <code>reverse_value()</code>
in a detail namespace?</b></p>
<blockquote>
<p>They are unsafe for general use. Consider reversing
the bytes of a <code>std::pai<b>r</b></code> as a whole - the bytes from <code>first</code>
would end up in <code>second</code> and visa versa, and this is totally
wrong!</p>
</blockquote>
<p><b>Why are both value returning and modify-in-place functions provided?</b></p>
<blockquote>
<p>Returning the result by value is the standard C and C++ idiom for functions that compute a
value from an argument. Modify-in-place functions allow cleaner code in many real-world
endian use cases and are more efficient for user defined types that have
members such as string data that do not need to be reversed. Thus both forms are
provided.</p>
</blockquote>
<p><b>What are the limitations of floating point support?</b></p>
<blockquote>
<p>The only supported types are four byte <code>float</code> and eight byte
<code>double</code>. Even after endianness has been accounted for, floating
point values will not be portable between systems that use different floating
point formats. Systems where the integer endianness and floating point
endianness are not supported.</p>
</blockquote>
<p><b>What are the limitations of integer support?</b></p>
<blockquote>
<p>Only 16-bit, 32-bit, and 64-bit integers are supported. Tests have been
performed on machines that use two's complement arithmetic.</p>
</blockquote>
<h2><a name="Reference">Reference</a></h2> <h2><a name="Reference">Reference</a></h2>
<p>Functions are implemented <code>inline</code> if appropriate.<code> noexcept</code> is <p>Functions are implemented <code>inline</code> if appropriate.<code> noexcept</code> is
@@ -152,7 +80,7 @@ Boost scoped enum emulation is used so that the library still works for compiler
<h3> <h3>
<a name="Synopsis">Synopsis</a></h3> <a name="Synopsis">Synopsis</a></h3>
<pre>#define BOOST_ENDIAN_INTRINSIC_MSG &quot;message describing presence or absence of intrinsics&quot; <pre>#define BOOST_ENDIAN_INTRINSIC_MSG &quot;<b><font face="Arial"><i>message describing presence or absence of intrinsics</i></font></b>&quot;
namespace boost namespace boost
{ {
@@ -297,27 +225,27 @@ void reverse(double&amp; x) noexcept;</pre>
<a name="big_endian"></a>template &lt;class Reversible&gt; <a name="big_endian"></a>template &lt;class Reversible&gt;
void big_endian(Reversible&amp; x) noexcept;</pre> void big_endian(Reversible&amp; x) noexcept;</pre>
<blockquote> <blockquote>
<p dir="ltr"><i>Returns (first form)</i>: <code>x</code> if the native byte order is big <p><i>Returns (first form)</i>: <code>x</code> if the native byte order is big
endian, otherwise <code>reverse_value(x)</code>.</p> endian, otherwise <code>reverse_value(x)</code>.</p>
<p dir="ltr"><i>Effects (second form):</i> None if the native byte order is big <p><i>Effects (second form):</i> None if the native byte order is big
endian, otherwise <code>reverse(x)</code>.</p> endian, otherwise <code>reverse(x)</code>.</p>
<p dir="ltr"><i>Example:</i></p> <p><i>Example:</i></p>
<blockquote> <blockquote>
<pre>int32_t x = <b><i>some-value</i></b>; <pre>int32_t x = <b><i>some-value</i></b>;
big_endian(x); // reverses the byte order of x, unless big_endian(x); // reverses the byte order of x, unless
// the native byte order is big-endian</pre> // the native byte order is big-endian</pre>
</blockquote> </blockquote>
</blockquote> </blockquote>
<pre dir="ltr"><a name="little_endian_value"></a>template &lt;class ReversibleValue &gt; <pre><a name="little_endian_value"></a>template &lt;class ReversibleValue &gt;
ReversibleValue little_endian_value(ReversibleValue x) noexcept; ReversibleValue little_endian_value(ReversibleValue x) noexcept;
<a name="little_endian"></a>template &lt;class Reversible&gt; <a name="little_endian"></a>template &lt;class Reversible&gt;
void little_endian(Reversible&amp; x) noexcept;</pre> void little_endian(Reversible&amp; x) noexcept;</pre>
<blockquote> <blockquote>
<p dir="ltr"><i>Returns (first form)</i>: <code>x</code> if the native byte order is little <p><i>Returns (first form)</i>: <code>x</code> if the native byte order is little
endian, otherwise <code>reverse_value(x)</code>.</p> endian, otherwise <code>reverse_value(x)</code>.</p>
<p dir="ltr"><i>Effects (second form):</i> None if the native byte order is little <p><i>Effects (second form):</i> None if the native byte order is little
endian, otherwise <code>reverse(x)</code>.</p> endian, otherwise <code>reverse(x)</code>.</p>
<p dir="ltr"><i>Example:</i></p> <p><i>Example:</i></p>
<blockquote> <blockquote>
<pre>int32_t x = <b><i>some-value</i></b>; <pre>int32_t x = <b><i>some-value</i></b>;
int32_t y(little_endian(x)); int32_t y(little_endian(x));
@@ -325,51 +253,84 @@ int32_t y(little_endian(x));
// the native byte order is little-endian.</pre> // the native byte order is little-endian.</pre>
</blockquote> </blockquote>
</blockquote> </blockquote>
<pre dir="ltr"><a name="convert_value_generic"></a>template &lt;order From, order To, class ReversibleValue&gt; <pre><a name="convert_value_generic"></a>template &lt;order From, order To, class ReversibleValue&gt;
ReversibleValue convert_value(ReversibleValue from) noexcept; ReversibleValue convert_value(ReversibleValue from) noexcept;
<a name="convert_generic"></a>template &lt;order From, order To, class Reversible&gt; <a name="convert_generic"></a>template &lt;order From, order To, class Reversible&gt;
void convert(Reversible&amp; x) noexcept; void convert(Reversible&amp; x) noexcept;
</pre> </pre>
<blockquote> <blockquote>
<p dir="ltr">The <b><i>effective order</i></b> of an order template parameter <p>The <b><i>effective order</i></b> of an order template parameter
is the same as the order template parameter if the parameter is not <code> is the same as the order template parameter if the parameter is not <code>
order::native</code>, otherwise it is the constant <code>order::big</code> or order::native</code>, otherwise it is the constant <code>order::big</code> or
<code>order::little</code> that represents the actual native byte order.</p> <code>order::little</code> that represents the actual native byte order.</p>
<p dir="ltr"><i>Returns (first form)</i>: <code>from</code> if <code>From</code> <p><i>Returns (first form)</i>: <code>from</code> if <code>From</code>
and <code>To</code> have the same effective order, otherwise <code> and <code>To</code> have the same effective order, otherwise <code>
reverse_value(from)</code>.</p> reverse_value(from)</code>.</p>
<p dir="ltr"><i>Effects (second form):</i> None if <code>From</code> and <code> <p><i>Effects (second form):</i> None if <code>From</code> and <code>
To</code> have the same effective order, otherwise <code>reverse(x)</code>.</p> To</code> have the same effective order, otherwise <code>reverse(x)</code>.</p>
<p dir="ltr"><i>Example:</i></p> <p><i>Example:</i></p>
<blockquote> <blockquote>
<pre>int32_t x; <pre>int32_t x;
<i>... read an external big-endian value into x</i> <i>... read an external big-endian value into x</i>
convert&lt;order::big, order::native&gt;(x); // more generic equivalent of big_endian(x);</pre> convert&lt;order::big, order::native&gt;(x); // more generic equivalent of big_endian(x);</pre>
</blockquote> </blockquote>
</blockquote> </blockquote>
<pre><a name="effective_order"></a>order effective_order(order x) noexcept;<blockquote><p dir="ltr"><i>Returns:</i> <code>x</code> if <code>x != order::native</code>, otherwise the <code>order</code> constant for the actual native byte order.</p><p dir="ltr"><i>Example:</i></p><blockquote><pre dir="ltr">effective_order(order::big); // returns order::big <pre><a name="effective_order"></a>order effective_order(order x) noexcept;
</pre>
<blockquote>
<p><i>Returns:</i> <code>x</code> if <code>x != order::native</code>, otherwise the <code>order</code> constant for the actual native byte order.</p><p><i>Example:</i></p><blockquote><pre>effective_order(order::big); // returns order::big
effective_order(order::little); // returns order::little effective_order(order::little); // returns order::little
effective_order(order::native); // returns order::big if the native order effective_order(order::native); // returns order::big if the native order
// is big-endian, otherwise order::little</pre></blockquote></blockquote><pre dir="ltr"><a name="convert_value_runtime"></a>template &lt;class ReversibleValue&gt; // is big-endian, otherwise order::little</pre></blockquote></blockquote><pre><a name="convert_value_runtime"></a>template &lt;class ReversibleValue&gt;
ReversibleValue convert_value(ReversibleValue from, ReversibleValue convert_value(ReversibleValue from,
order from_order, order to_order) noexcept; order from_order, order to_order) noexcept;
<a name="convert_runtime"></a>template &lt;class Reversible&gt; <a name="convert_runtime"></a>template &lt;class Reversible&gt;
void convert(Reversible&amp; x, void convert(Reversible&amp; x,
order from_order, order to_order) noexcept;</pre><blockquote><p dir="ltr"><i>Returns (first form)</i>: <code>from</code> if <code>effect_order(from_order) == effective_order(to_order)</code>, otherwise <code>reverse_value(from)</code>.</p> order from_order, order to_order) noexcept;</pre><blockquote><p><i>Returns (first form)</i>: <code>from</code> if <code>effect_order(from_order) == effective_order(to_order)</code>, otherwise <code>reverse_value(from)</code>.</p>
<p dir="ltr"><i>Effects (second form):</i> None if <code>effect_order(from_order) == effective_order(to_order)</code>, otherwise <code>reverse(x)</code>.</p> <p><i>Effects (second form):</i> None if <code>effect_order(from_order) == effective_order(to_order)</code>, otherwise <code>reverse(x)</code>.</p>
<p dir="ltr"><i>Example:</i></p> <p><i>Example:</i></p>
<blockquote> <blockquote>
<pre>int32_t x; <pre>int32_t x;
<i>... read an external value of an endianness know only at runtime into x</i> <i>... read an external value of an endianness know only at runtime into x</i>
convert(x, some_order, order::native); // convert to native byte order if needed</pre> convert(x, some_order, order::native); // convert to native byte order if needed</pre>
</blockquote> </blockquote>
</blockquote><h2><a name="Intrinsic">Intrinsic</a> built-in support</h2> </blockquote>
<p>Recent compilers, including GCC, Clang, and Microsoft, supply intrinsic built-in support for byte swapping. Such support is automatically detected and used since it results in smaller and much faster generated code for release builds.</p><p>Defining BOOST_ENDIAN_NO_INTRINSICS will suppress use of the intrinsics. Please try defining it if you get compiler errors, such as header byteswap.h not being found.</p><p>The macro BOOST_ENDIAN_INTRINSIC_MSG is defined as either <code>&quot;no byte swap intrinsics&quot;</code> or a string describing the particular set of intrinsics being used.</p><h2><a name="Acknowledgements">Acknowledgements</a></h2><p>Tomas Puverle was instrumental in identifying and articulating the need to <h2> <a name="FAQ">FAQ</a></h2>
<p>See the <a href="index.html#FAQ">Endian home page</a> FAQ for a library-wide
FAQ.</p>
<p><b>Why are the template versions of <code>reverse()</code> and <code>reverse_value()</code>
in a detail namespace?</b></p>
<blockquote>
<p>They are unsafe for general use. Consider reversing
the bytes of a <code>std::pai<b>r</b></code> as a whole - the bytes from <code>first</code>
would end up in <code>second</code> and visa versa, and this is totally
wrong!</p>
</blockquote>
<p><b>Why are both value returning and modify-in-place functions provided?</b></p>
<blockquote>
<p>Returning the result by value is the standard C and C++ idiom for functions that compute a
value from an argument. Modify-in-place functions allow cleaner code in many real-world
endian use cases and are more efficient for user defined types that have
members such as string data that do not need to be reversed. Thus both forms are
provided.</p>
</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 integer types. Phil Endecott suggested the form of the value returning signatures. Vicente Botet and other reviewers suggested supporting floating point types and user defined types. General reverse template implementation approach using std::reverse suggested by Mathias Gaunard. Portable implementation approach for 16, 32, and 64-bit integers suggested by tymofey, with avoidance of undefined behavior as suggested by Giovanni Piero Deretta, and a further refinement suggested by Pyry Jahkola. Intrinsic builtins implementation approach for 16, 32, and 64-bit integers suggested by several reviewers, and by David Stone, who provided his Boost licensed macro implementation that became the starting point for <a href="../include/boost/endian/detail/intrinsic.hpp">boost/endian/detail/intrinsic.hpp</a>.</p> support endian conversion as separate from endian integer types. Phil Endecott suggested the form of the value returning signatures. Vicente Botet and other reviewers suggested supporting floating point types and user defined types. General reverse template implementation approach using std::reverse suggested by Mathias Gaunard. Portable implementation approach for 16, 32, and 64-bit integers suggested by tymofey, with avoidance of undefined behavior as suggested by Giovanni Piero Deretta, and a further refinement suggested by Pyry Jahkola. Intrinsic builtins implementation approach for 16, 32, and 64-bit integers suggested by several reviewers, and by David Stone, who provided his Boost licensed macro implementation that became the starting point for <a href="../include/boost/endian/detail/intrinsic.hpp">boost/endian/detail/intrinsic.hpp</a>.</p>
<hr> <hr>
<p>Last revised: <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->20 May, 2013<!--webbot bot="Timestamp" endspan i-checksum="13976" --></p> <p>Last revised:
<p><EFBFBD> Copyright Beman Dawes, 2011</p> <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->28 May, 2013<!--webbot bot="Timestamp" endspan i-checksum="13992" --></p>
<p>© Copyright Beman Dawes, 2011, 2013</p>
<p>Distributed under the Boost Software License, Version 1.0. See <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/ LICENSE_1_0.txt</a></p> <p>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> </body>

9
doc/done_list.html
View File

@@ -14,19 +14,19 @@
<ul> <ul>
<li>Both the endian types and endian conversion functions now support 32-bit (<code>float)</code> and <li>Both the endian types and endian conversion functions now support 32-bit (<code>float)</code> and
64-bit <code>(double)</code> floating point, as requested.</li> 64-bit <code>(double)</code> floating point, as requested.</li>
<li>Both the endian types and endian conversion functions now support UDTs, as requested.</li>
<li>Both the endian types and endian conversion functions have been renamed, <li>Both the endian types and endian conversion functions have been renamed,
using a naming pattern that is consistent for both integer and floating point, using a naming pattern that is consistent for both integer and floating point,
and that emphasizes that aligned types are usually preferred compared to and that emphasizes that aligned types are usually preferred compared to
unaligned types.</li> unaligned types which are deliberately given slightly uglier names.</li>
<li>The conversion.hpp conversion functions have been much revised, <li>The conversion functions have been much revised,
refactored, and otherwise improved based on review comments.<ul> refactored, and otherwise improved based on review comments.<ul>
<li>UDT's are supported, as requested.</li>
<li>Both return-by-value and modify-in-place interfaces are provided, as <li>Both return-by-value and modify-in-place interfaces are provided, as
requested.</li> requested.</li>
<li>Synonyms for the BSD byte swapping function names popularized by OS X <li>Synonyms for the BSD byte swapping function names popularized by OS X
and Linux are provided, so that that developers already used to these name and Linux are provided, so that that developers already used to these name
can continue to use them if they wish.</li> can continue to use them if they wish.</li>
<li>In addition to the fixed endianness functions, functions that perform <li>In addition to the named-endianness functions, functions that perform
compile-time (via template) and run-time (via function argument) dispatch compile-time (via template) and run-time (via function argument) dispatch
are now provided, as requested.</li> are now provided, as requested.</li>
</ul> </ul>
@@ -34,6 +34,7 @@
<li>Compiler (Clang, GCC, VisualC++, etc.) intrinsics and built-in functions <li>Compiler (Clang, GCC, VisualC++, etc.) intrinsics and built-in functions
are used in the implementation where appropriate, as requested.</li> are used in the implementation where appropriate, as requested.</li>
<li>For the endian types, the implementation uses the endian conversion functions, <li>For the endian types, the implementation uses the endian conversion functions,
and thus the intrinsics,
as requested.</li> as requested.</li>
<li>Headers have been renamed to endian/types.hpp and endian/conversion.hpp. <li>Headers have been renamed to endian/types.hpp and endian/conversion.hpp.
Infrastructure file names changed accordingly.</li> Infrastructure file names changed accordingly.</li>

72
doc/index.html
View File

@@ -3,7 +3,7 @@
<head> <head>
<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> <meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document"> <meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Boost Endian Library</title> <title>Boost Endian Library</title>
<link rel="stylesheet" type="text/css" href="../../../doc/src/minimal.css"> <link rel="stylesheet" type="text/css" href="../../../doc/src/minimal.css">
@@ -26,7 +26,7 @@
<td><b><a href="../../../index.htm">Boost Home</a>&nbsp;&nbsp;&nbsp;&nbsp; <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="index.html">Endian Home</a>&nbsp;&nbsp;&nbsp;&nbsp;
<a href="conversion.html">Conversion Functions</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href="conversion.html">Conversion Functions</a>&nbsp;&nbsp;&nbsp;&nbsp;
<a href="types.html">Endian Types</a>&nbsp;&nbsp;&nbsp;&nbsp; Tutorial</b></td> <a href="types.html">Endian Types</a></b></td>
</tr> </tr>
</table> </table>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" align="right"> <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" align="right">
@@ -40,6 +40,7 @@
<a href="#Introduction-to-endianness">Introduction to endianness</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="#Introduction">Introduction to the Boost.Endian library</a><br>
<a href="#Choosing">Choosing approaches</a><br> <a href="#Choosing">Choosing approaches</a><br>
<a href="#Intrinsic">Intrinsic built-in support</a><br>
<a href="#Performance">Performance</a><br> <a href="#Performance">Performance</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Timings">Timings</a><br> &nbsp;&nbsp;&nbsp; <a href="#Timings">Timings</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Conclusions">Conclusions</a><br> &nbsp;&nbsp;&nbsp; <a href="#Conclusions">Conclusions</a><br>
@@ -79,7 +80,7 @@ floating point, and user defined data.</p>
<blockquote> <blockquote>
<pre>int16_t i = 0x0102; <pre>int16_t i = 0x0102;
FILE * file = fopen(&quot;test.bin&quot;, &quot;wb&quot;); // MUST BE BINARY FILE * file = fopen(&quot;test.bin&quot;, &quot;wb&quot;); // binary file!
fwrite(&amp;i, sizeof(int16_t), 1, file); fwrite(&amp;i, sizeof(int16_t), 1, file);
fclose(file);</pre> fclose(file);</pre>
</blockquote> </blockquote>
@@ -103,7 +104,7 @@ ordering and the least-significant-byte-first is traditionally called
<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 kingdoms opened their soft-boiled eggs Gulliver’s Travels</a></i>, where rival kingdoms opened their soft-boiled eggs
at different ends.</p> at different ends.</p>
<p>See the Wikipedia's <p>See the Wikipedia's
<a href="http://en.wikipedia.org/wiki/Endianness">Endianness</a> article for an <a href="http://en.wikipedia.org/wiki/Endianness">Endianness</a> article for an
@@ -195,6 +196,18 @@ application needs.</p>
</tr> </tr>
</table> </table>
<h2><a name="Intrinsic">Intrinsic</a> built-in support</h2>
<p>Recent compilers, including GCC, Clang, and Microsoft, supply intrinsic
built-in support for byte swapping. Such support is automatically detected and
used since it may in smaller and faster generated code, particularly for release
builds.</p>
<p dir="ltr">Defining <code>BOOST_ENDIAN_NO_INTRINSICS</code> will suppress use
of the intrinsics. Please try defining it if you get compiler errors, such as
header byteswap.h not being found.</p>
<p dir="ltr">The macro <code>BOOST_ENDIAN_INTRINSIC_MSG</code> is defined as
either <code>&quot;no byte swap intrinsics&quot;</code> or a string describing the
particular set of intrinsics being used.</p>
<h2><a name="Performance">Performance</a></h2> <h2><a name="Performance">Performance</a></h2>
<p>Consider this problem:</p> <p>Consider this problem:</p>
@@ -425,6 +438,23 @@ stores, multiple instructions are required.</p>
<h2>Overall <a name="FAQ">FAQ</a></h2> <h2>Overall <a name="FAQ">FAQ</a></h2>
<p><b>Is the implementation header only?</b></p>
<blockquote>
<p>Yes.</p>
</blockquote>
<p><b>Does the implementation use compiler intrinsic built-in byte swapping?</b></p>
<blockquote>
<p>Yes, if available. See <a href="#Intrinsic">Intrinsic built-in support</a>.</p>
</blockquote>
<p><b>Why bother with endianness?</b></p> <p><b>Why bother with endianness?</b></p>
<blockquote> <blockquote>
<p>Binary data portability is the primary use case.</p> <p>Binary data portability is the primary use case.</p>
@@ -448,6 +478,15 @@ files, limit usefulness to applications where the binary I/O advantages are
paramount.</p> paramount.</p>
</blockquote> </blockquote>
<p><b>Which is better, big-endian or little-endian?</b></p>
<blockquote>
<p>Big-endian tends to be a
bit more of an industry standard, but little-endian may be preferred for
applications that run primarily Intel/AMD on x86, x64, and other little-endian
CPU's. The <a href="http://en.wikipedia.org/wiki/Endian">Wikipedia</a> article
gives more pros and cons.</p>
</blockquote>
<p><b>Why is only big, little, and native endianness supported?</b></p> <p><b>Why is only big, little, and native endianness supported?</b></p>
<blockquote> <blockquote>
<p>These are the only endian schemes that have any practical value today. PDP-11 <p>These are the only endian schemes that have any practical value today. PDP-11
@@ -455,12 +494,33 @@ and the other middle endian approaches are interesting historical curiosities
but have no relevance to C++ developers.</p> but have no relevance to C++ developers.</p>
</blockquote> </blockquote>
<p><b>What are the limitations of floating point support?</b></p>
<blockquote>
<p>The only supported types are four byte <code>float</code> and eight byte
<code>double</code>. Even after endianness has been accounted for, floating
point values will not be portable between systems that use different floating
point formats. Systems where the integer endianness differs from floating point
endianness are not supported.</p>
</blockquote>
<p><b>What are the limitations of integer support?</b></p>
<blockquote>
<p>Only 16-bit, 32-bit, and 64-bit integers are supported. Tests have only been
performed on machines that use two's complement arithmetic.</p>
</blockquote>
<h2><a name="Acknowledgements">Acknowledgements</a></h2> <h2><a name="Acknowledgements">Acknowledgements</a></h2>
<p>Comments and suggestions were <p>Comments and suggestions were
received from received from
Adder, Benaka Moorthi, Adder, Benaka Moorthi,
Christopher Kohlhoff, Christopher Kohlhoff,
Cliff Green,Daniel James, Gennaro Proto, Cliff Green, Daniel James, Gennaro Proto,
Giovanni Piero Deretta, Gordon Woodhull, dizzy, Hartmut Kaiser, Jeff Flinn, Giovanni Piero Deretta, Gordon Woodhull, dizzy, Hartmut Kaiser, Jeff Flinn,
John Filo, John Maddock, John Filo, John Maddock,
Kim Barrett, Kim Barrett,
@@ -474,7 +534,7 @@ and Vitaly Budovski,.</p>
<hr> <hr>
<p>Last revised: <p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->28 May, 2013<!--webbot bot="Timestamp" endspan i-checksum="13992" --></p> <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->28 May, 2013<!--webbot bot="Timestamp" endspan i-checksum="13992" --></p>
<p><EFBFBD> Copyright Beman Dawes, 2011, 2013</p> <p>© Copyright Beman Dawes, 2011, 2013</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>

49
doc/types.html
View File

@@ -4,7 +4,7 @@
<meta http-equiv="Content-Language" content="en-us"> <meta http-equiv="Content-Language" content="en-us">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> <meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document"> <meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Boost Endian Integers</title> <title>Boost Endian Integers</title>
<link rel="stylesheet" type="text/css" href="../../../doc/src/minimal.css"> <link rel="stylesheet" type="text/css" href="../../../doc/src/minimal.css">
</head> </head>
@@ -28,7 +28,7 @@
<td><b><a href="../../../index.htm">Boost Home</a>&nbsp;&nbsp;&nbsp;&nbsp; <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="index.html">Endian Home</a>&nbsp;&nbsp;&nbsp;&nbsp;
<a href="conversion.html">Conversion Functions</a>&nbsp;&nbsp;&nbsp;&nbsp; <a href="conversion.html">Conversion Functions</a>&nbsp;&nbsp;&nbsp;&nbsp;
<a href="types.html">Endian Types</a>&nbsp;&nbsp;&nbsp;&nbsp; Tutorial</b></td> <a href="types.html">Endian Types</a></b></td>
</tr> </tr>
</table> </table>
@@ -510,29 +510,14 @@ in <code>*this</code>.</p>
<p>Other operators on endian objects are forwarded to the equivalent <p>Other operators on endian objects are forwarded to the equivalent
operator on <code>value_type</code>.</p> operator on <code>value_type</code>.</p>
<h2><a name="FAQ">FAQ</a></h2> <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 <p>See the <a href="index.html#FAQ">Endian home page</a> FAQ for a library-wide
of additional binary integer sizes and alignments is important in some FAQ.</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 integers 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
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++11. No for C++03, although several <p><b>Are endian types POD's?</b> Yes for C++11. 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 integer types not being POD's with C++03 <p><b>What are the implications endian integer types not being POD's with C++03
@@ -541,24 +526,15 @@ 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
use of Boost.Endian with use of Boost.Endian with
real compilers.</p> 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 Intel/AMD on x86, x64, 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 <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 size guarantees not available from the built-in types. It eases generic
programming.</p> programming.</p>
<p><b>Why bother with the aligned endian types?</b> Aligned integer operations <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 may be faster (as much as 10 to 20 times faster) if the endianness and alignment of
the type matches the endianness and alignment requirements of the machine. On the type matches the endianness and alignment requirements of the machine. The code,
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 however, is
likely to be somewhat less portable than with the unaligned types.</p> likely to be somewhat less portable than with the unaligned types.</p>
<p><b>The endian types are really just byte-holders. Why provide the arithmetic <p><b>Why provide the arithmetic operations?</b> Providing a full set of operations reduces program
operations at all?</b> Providing a full set of operations reduces program
clutter and makes code both easier to write and to read. Consider 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>
@@ -629,11 +605,12 @@ Borgerding. Four original class templates combined into a single <code>endian</c
class template by Beman Dawes, who put the library together, provided class template by Beman Dawes, who put the library together, provided
documentation, added the typedefs, and also added the <code>unrolled_byte_loops</code> 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 sign partial specialization to correctly extend the sign when cover integer size
differs from endian representation size.</p> differs from endian representation size. Vicente Botet and other reviewers
suggested supporting floating point types.</p>
<hr> <hr>
<p>Last revised: <p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->26 May, 2013<!--webbot bot="Timestamp" endspan i-checksum="13988" --></p> <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->28 May, 2013<!--webbot bot="Timestamp" endspan i-checksum="13992" --></p>
<p>© Copyright Beman Dawes, 2006-2009</p> <p>© Copyright Beman Dawes, 2006-2009, 2013</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>