Last pass through docs

This commit is contained in:
Beman committed 2013-05-28 11:04:03 -04:00
1 parent 9c25d54d38
commit b541dfb790
4 files changed
+142 -143

No files matched your search

+58 -97
View File
@@ -3,7 +3,7 @@
<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">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Boost Endian Conversion Functions</title>
<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;
<a href="index.html">Endian Home</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>
</table>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" align="right">
@@ -37,12 +37,11 @@
<tr>
<td width="100%" bgcolor="#E8F5FF">
<a href="#Introduction">Introduction</a><br>
<a href="#FAQ">conversion.hpp FAQ</a><br>
<a href="#Reference">Reference</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="#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>
</tr>
<tr>
@@ -58,13 +57,6 @@
<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>
provides byte order reversal and conversion functions that convert objects of
the multi-byte built-in
@@ -79,70 +71,6 @@ ordering. User defined types are also supported.</p>
</tr>
</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>
<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>
<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
{
@@ -297,27 +225,27 @@ void reverse(double&amp; x) noexcept;</pre>
<a name="big_endian"></a>template &lt;class Reversible&gt;
void big_endian(Reversible&amp; x) noexcept;</pre>
<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>
<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>
<p dir="ltr"><i>Example:</i></p>
<p><i>Example:</i></p>
<blockquote>
<pre>int32_t x = <b><i>some-value</i></b>;
big_endian(x); // reverses the byte order of x, unless
// the native byte order is big-endian</pre>
</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;
<a name="little_endian"></a>template &lt;class Reversible&gt;
void little_endian(Reversible&amp; x) noexcept;</pre>
<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>
<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>
<p dir="ltr"><i>Example:</i></p>
<p><i>Example:</i></p>
<blockquote>
<pre>int32_t x = <b><i>some-value</i></b>;
int32_t y(little_endian(x));
@@ -325,51 +253,84 @@ int32_t y(little_endian(x));
// the native byte order is little-endian.</pre>
</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;
<a name="convert_generic"></a>template &lt;order From, order To, class Reversible&gt;
void convert(Reversible&amp; x) noexcept;
</pre>
<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>
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>
<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>
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>
<p dir="ltr"><i>Example:</i></p>
<p><i>Example:</i></p>
<blockquote>
<pre>int32_t x;
<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>
</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::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,
order from_order, order to_order) noexcept;
<a name="convert_runtime"></a>template &lt;class Reversible&gt;
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>
<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 dir="ltr"><i>Example:</i></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><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>Example:</i></p>
<blockquote>
<pre>int32_t x;
<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>
</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>
<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>© Copyright Beman Dawes, 2011</p>
<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>
<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>
</body>