feedc0de/boost_endian
1
0
Fork 0
forked from boostorg/endian
Code Pull Requests Activity

Bring docs in sync with implementation. Still somewhat incomplete.

Browse Source
This commit is contained in:
Beman
2014-12-09 07:04:48 -05:00
parent f96cec4f17
commit 28fd6ef4b0
6 changed files with 175 additions and 136 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
doc/arithmetic.html
View File

@@ -71,6 +71,7 @@
<tr> <tr>
<td width="100%" bgcolor="#E8F5FF"> <td width="100%" bgcolor="#E8F5FF">
<a href="../include/boost/endian/conversion.hpp">&lt;boost/endian/conversion.hpp&gt;</a><br> <a href="../include/boost/endian/conversion.hpp">&lt;boost/endian/conversion.hpp&gt;</a><br>
<a href="../include/boost/endian/buffers.hpp">&lt;boost/endian/buffers.hpp&gt;</a><br>
<a href="../include/boost/endian/arithmetic.hpp">&lt;boost/endian/arithmetic.hpp&gt;</a></td> <a href="../include/boost/endian/arithmetic.hpp">&lt;boost/endian/arithmetic.hpp&gt;</a></td>
</tr> </tr>
</table> </table>
@@ -375,19 +376,21 @@ usual operations on integers are supplied.</p>
enum class <a name="alignment">align</a> {no, yes}; enum class <a name="alignment">align</a> {no, yes};
template &lt;order Order, class T, std::size_t n_bits, align A = align::no&gt; template &lt;order Order, class T, std::size_t n_bits, align A = align::no&gt;
class endian class endian_arithmetic
: public endian_buffer&lt;Order, T, n_bits, A&gt;
{ {
public: public:
typedef T value_type; typedef T value_type;
// if BOOST_ENDIAN_FORCE_PODNESS is defined &amp;&amp; C++11 POD's are not // if BOOST_ENDIAN_FORCE_PODNESS is defined &amp;&amp; C++11 POD's are not
// available then these two constructors will not be present // available then these two constructors will not be present
<a href="#endian">endian</a>() noexcept = default; <a href="#endian">endian_arithmetic</a>() noexcept = default;
<a href="#explicit-endian">endian</a>(T v) noexcept; <a href="#explicit-endian">endian_arithmetic</a>(T v) noexcept;
endian&amp; <a href="#operator-eq">operator=</a>(T v) noexcept; endian_arithmetic&amp; <a href="#operator-eq">operator=</a>(T v) noexcept;
<a href="#operator-T">operator T</a>() const noexcept; <a href="#operator-T">operator value_type</a>() const noexcept;
const char* <a href="#data">data</a>() const noexcept; value_type value() const noexcept; // exposition only; see endian_buffer
const char* <a href="#data">data</a>() const noexcept; // exposition only; see endian_buffer
// arithmetic operations // arithmetic operations
// note that additional operations are provided by the value_type // note that additional operations are provided by the value_type
@@ -678,7 +681,7 @@ differs from endian representation size. Vicente Botet and other reviewers
suggested supporting floating point types.</p> 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 -->19 November, 2014<!--webbot bot="Timestamp" endspan i-checksum="39499" --></p> <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38642" --></p>
<p>© Copyright Beman Dawes, 2006-2009, 2013</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>

21
doc/bikeshed.txt
View File

@@ -3,12 +3,17 @@ Conversion function naming bikeshed
return-by-value modify-argument return-by-value modify-argument
------------------ --------------- ------------------ ---------------
reverse_endianness reverse_endianness_in_place <------- reverse_endianness reverse_endianness_in_place
" reverse_endianness_arg " reverse_endianness_arg
endian_reverse endian_reverse_in_place
" endian_reverse_here
" endian_reverse_this
" endian_reverse_self
" endian_reverse_arg
" endian_reverse_in <------
reverse reverse_in_place reverse reverse_in_place
reverse_endian reverse_endian_in_place reverse_endian reverse_endian_in_place
endian_reverse endian_reverse_in_place
swap_endianness swap_endianness_in_place swap_endianness swap_endianness_in_place
swap_endian swap_endian_in_place swap_endian swap_endian_in_place
@@ -31,7 +36,16 @@ Key points:
the various conditional functions instead. So explicitness is more important than the various conditional functions instead. So explicitness is more important than
brevity. brevity.
big_to_native native_to_big reverse_unless_native_big little_to_native native_to_little reverse_unless_native_little
reverse_if_not_big
reverse_if_little
reverse_unless_big
big_to_host host_to_big reverse_unless_host_big
reverse_if_host_little
be_to_ne ne_to_be
from_big, to_big, reverse_unless_big
merriam-webster.com/dictionary merriam-webster.com/dictionary
@@ -49,3 +63,6 @@ flip (verb)
: to move (something) with a quick light movement : to move (something) with a quick light movement

80
doc/buffers.html
View File

@@ -1,4 +1,4 @@
<html> <html>
<head> <head>
<meta http-equiv="Content-Language" content="en-us"> <meta http-equiv="Content-Language" content="en-us">
@@ -64,26 +64,34 @@
</tr> </tr>
<tr> <tr>
<td width="100%" bgcolor="#E8F5FF"> <td width="100%" bgcolor="#E8F5FF">
<p dir="ltr">
<a href="../include/boost/endian/conversion.hpp">&lt;boost/endian/conversion.hpp&gt;</a><br> <a href="../include/boost/endian/conversion.hpp">&lt;boost/endian/conversion.hpp&gt;</a><br>
<a href="../include/boost/endian/buffers.hpp">&lt;boost/endian/buffers.hpp&gt;</a><br>
<a href="../include/boost/endian/arithmetic.hpp">&lt;boost/endian/arithmetic.hpp&gt;</a></td> <a href="../include/boost/endian/arithmetic.hpp">&lt;boost/endian/arithmetic.hpp&gt;</a></td>
</tr> </tr>
</table> </table>
<h2><a name="Introduction">Introduction</a></h2> <h2><a name="Introduction">Introduction</a></h2>
<p>Header <a href="buffers.html">boost/endian/buffers.hpp</a> <p>The internal byte order of arithmetic types is traditionally called <b><i>endianness</i></b>. See the
provides portable integer and floating-point binary buffer types with control over
byte order, value type, size, and alignment independent of the native computer
architecture. Typedefs provide easy-to-use names
for common configurations. Use cases almost always involve I/O, either via files or
network connections.</p>
<p>Although data portability is the primary motivation, these byte-holders may
also be used to reduce memory use, file size, or network activity since they
also
provide binary numeric sizes not otherwise available.</p>
<p>The byte order of arithmetic types is traditionally called <b><i>endianness</i></b>. See the
<a href="http://en.wikipedia.org/wiki/Endian" name="endianness">Wikipedia</a> for <a href="http://en.wikipedia.org/wiki/Endian" name="endianness">Wikipedia</a> for
a full a full
exploration of <b><i>endianness</i></b>, including definitions of <i><b>big exploration of <b><i>endianness</i></b>, including definitions of <i><b>big
endian</b></i> and <i><b>little endian</b></i>.</p> endian</b></i> and <i><b>little endian</b></i>.</p>
<p>Header <a href="buffers.html">boost/endian/buffers.hpp</a>
provides <code>endian_buffer</code>, a portable endian integer and floating-point binary buffer
class template with control over
byte order, value type, size, and alignment independent of the platform&#39;s native
endianness. Typedefs provide easy-to-use names
for common configurations.</p>
<p>Use cases primarily involve data portability, either via files or network
connections, but these byte-holders may
also be used to reduce memory use, file size, or network activity since they
provide binary numeric sizes not otherwise available.</p>
<p dir="ltr">Class <code>endian_buffer</code> is aimed at users who wish
explicit control over when endianness conversions occur. It also serves as the
base class for the <code><a href="arithmetic.html">endian_arithmetic</a></code>
class template, which is aimed at users who wish fully automatic endianness
conversion and direct support for all normal arithmetic operations.</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>
@@ -360,13 +368,11 @@ usual operations on integers are supplied.</p>
public: public:
typedef T value_type; typedef T value_type;
// if BOOST_ENDIAN_FORCE_PODNESS is defined &amp;&amp; C++11 POD's are not
// available then these two constructors will not be present
<a href="#endian">endian_buffer</a>() noexcept = default; <a href="#endian">endian_buffer</a>() noexcept = default;
explicit <a href="#explicit-endian">endian_buffer</a>(T v) noexcept; explicit <a href="#explicit-endian">endian_buffer</a>(T v) noexcept;
endian_buffer&amp; <a href="#operator-eq">operator=</a>(T v) noexcept; endian_buffer&amp; <a href="#operator-eq">operator=</a>(T v) noexcept;
value_type value() const noexcept; value_type <a href="#value">value</a>() const noexcept;
const char* <a href="#data">data</a>() const noexcept; const char* <a href="#data">data</a>() const noexcept;
protected: protected:
<b><i>implementaton-defined</i></b> endian_value; // for exposition only <b><i>implementaton-defined</i></b> endian_value; // for exposition only
@@ -489,35 +495,49 @@ requirements imposed by the <code>Nbits</code> and <code>Align</code> template
parameters.&nbsp; The <code><span style="font-size: 85%">CHAR_BIT</span></code> parameters.&nbsp; The <code><span style="font-size: 85%">CHAR_BIT</span></code>
macro is defined in <code><span style="font-size: 85%">&lt;climits&gt;</span></code>. macro is defined in <code><span style="font-size: 85%">&lt;climits&gt;</span></code>.
The only value of <code><span style="font-size: 85%">CHAR_BIT</span></code> that The only value of <code><span style="font-size: 85%">CHAR_BIT</span></code> that
is required to be supported is 8. </p> is required to be supported is 8.</p>
<p>Template parameter <code><span style="font-size: 85%">T</span></code> is
required to be a standard integer type (C++std, 3.9.1) and <code>
<span style="font-size: 85%">sizeof(T)*CHAR_BIT</span></code> is required to be
greater or equal to <span style="font-size: 85%"> <code>Nbits</code>.</span></p>
<h3><a name="Members">Members</a></h3> <h3><a name="Members">Members</a></h3>
<div dir="ltr"> <pre><code><a name="endian">endian</a>_buffer() noexcept = default;</code></pre>
<pre><code><a name="endian">endian</a>_buffer() = default; // C++03: endian(){}</code></pre>
</div>
<blockquote> <blockquote>
<p><i>Effects:</i> Constructs an object of type <code>endian_buffer&lt;Order, T, <p><i>Effects:</i> Constructs an object of type <code>endian_buffer&lt;Order, T,
Nbits, Align&gt;</code>.</p> Nbits, Align&gt;</code>.</p>
</blockquote> </blockquote>
<pre><code>explicit <a name="explicit-endian">endian</a>_buffer(T v);</code></pre> <pre><code>explicit <a name="explicit-endian">endian</a>_buffer(T v) noexcept;</code></pre>
<blockquote> <blockquote>
<p><i>Effects:</i> Constructs an object of type <code>endian_buffer&lt;Order, T, <p><i>Effects:</i> Constructs an object of type <code>endian_buffer&lt;Order, T,
Nbits, Align&gt;</code>.</p> Nbits, Align&gt;</code>.</p>
<p><i>Postcondition:</i> <code>value() == v</code>.</p> <p><i>Postcondition:</i> <code>value() == v &amp; mask</code>, where <code>mask</code>
is a constant of type <code>value_type</code> with <code>Nbits</code> low-order
bits set to one.</p>
<p><i>Remarks:</i> If <code>Align</code> is <code>align::yes</code> then
endianness conversion if required is performed by <code>
boost::endian::reverse_endianness</code>.</p>
</blockquote> </blockquote>
<pre><code>endian_buffer&amp; <a name="operator-eq">operator=</a>(T v);</code></pre> <pre><code>endian_buffer&amp; <a name="operator-eq">operator=</a>(T v) noexcept;</code></pre>
<blockquote> <blockquote>
<p><i>Postcondition:</i> <code>value() == v</code>.</p> <p><i>Postcondition:</i> <code>value() == v &amp; mask</code>, where <code>mask</code>
is a constant of type <code>value_type</code> with <code>Nbits</code>
low-order bits set to one..</p>
<p><i>Returns:</i> <code>*this</code>.</p> <p><i>Returns:</i> <code>*this</code>.</p>
<p><i>Remarks:</i> If <code>Align</code> is <code>align::yes</code> then
endianness conversion if required is performed by <code>
boost::endian::reverse_endianness</code>.</p>
</blockquote> </blockquote>
<pre>value_type <a name="value">value</a>()<code> const;</code></pre> <pre>value_type <a name="value">value</a>()<code> const noexcept;</code></pre>
<blockquote> <blockquote>
<p><i>Returns:</i> The current value stored in <code>*this</code>, converted to <p><i>Returns:</i> <code>endian_value</code>, converted to <code>value_type</code>
<code>value_type</code>.</p> if necessary and having the endianness of the native platform.</p>
<p><i>Remarks:</i> If <code>Align</code> is <code>align::yes</code> then
endianness conversion if required is performed by <code>
boost::endian::reverse_endianness</code>.</p>
</blockquote> </blockquote>
<pre><code>const char* <a name="data">data</a>() const;</code></pre> <pre><code>const char* <a name="data">data</a>() const noexcept;</code></pre>
<blockquote> <blockquote>
<p><i>Returns:</i> A pointer to the first byte of the endian binary value stored <p><i>Returns:</i> A pointer to the first byte of <code>endian_value</code>.</p>
in <code>*this</code>.</p>
</blockquote> </blockquote>
<h2><a name="FAQ">FAQ</a></h2> <h2><a name="FAQ">FAQ</a></h2>
@@ -597,7 +617,7 @@ any Boost object libraries.</p>
</ul> </ul>
<hr> <hr>
<p>Last revised: <p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38642" --></p> <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->06 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38644" --></p>
<p>© Copyright Beman Dawes, 2006-2009, 2013</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>

177
doc/conversion.html
View File

@@ -1,4 +1,4 @@
<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns="http://www.w3.org/TR/REC-html40"> <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> <head>
<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> <meta name="GENERATOR" content="Microsoft FrontPage 5.0">
@@ -45,7 +45,10 @@
<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;&nbsp;&nbsp; <code><a href="#Reversible">Reversible</a></code><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#Customization-points">Customization for
UDTs</a><br>
<a href="#Functions">Functions</a><br>
<a href="#FAQ">FAQ</a><br> <a href="#FAQ">FAQ</a><br>
<a href="#Acknowledgements">Acknowledgements</a></td> <a href="#Acknowledgements">Acknowledgements</a></td>
</tr> </tr>
@@ -56,6 +59,7 @@
<tr> <tr>
<td width="100%" bgcolor="#E8F5FF"> <td width="100%" bgcolor="#E8F5FF">
<a href="../include/boost/endian/conversion.hpp">&lt;boost/endian/conversion.hpp&gt;</a><br> <a href="../include/boost/endian/conversion.hpp">&lt;boost/endian/conversion.hpp&gt;</a><br>
<a href="../include/boost/endian/buffers.hpp">&lt;boost/endian/buffers.hpp&gt;</a><br>
<a href="../include/boost/endian/arithmetic.hpp">&lt;boost/endian/arithmetic.hpp&gt;</a></td> <a href="../include/boost/endian/arithmetic.hpp">&lt;boost/endian/arithmetic.hpp&gt;</a></td>
</tr> </tr>
</table> </table>
@@ -64,7 +68,7 @@
<p>Header <a href="../include/boost/endian/conversion.hpp">boost/endian/conversion.hpp</a> <p>Header <a href="../include/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 built-in
integer types, and also types <code>float</code> and <code>double,</code> integer types, and also types <code>float</code> and <code>double,</code>
between native, big, or little endian byte between native, big, or little endian byte
ordering. User defined types are also supported.</p> ordering. User defined types are also supported.</p>
@@ -76,6 +80,7 @@ elided for compilers that do not support it.
Boost scoped enum emulation is used so that the library still works for compilers that do not support scoped enums. </p> Boost scoped enum emulation is used so that the library still works for compilers that do not support scoped enums. </p>
<h3> <h3>
Header <code>&lt;boost/endian/conversion.hpp&gt;</code>
<a name="Synopsis">Synopsis</a></h3> <a name="Synopsis">Synopsis</a></h3>
<pre>#define BOOST_ENDIAN_INTRINSIC_MSG &quot;<b><font face="Arial"><i>message describing presence or absence of intrinsics</i></font></b>&quot; <pre>#define BOOST_ENDIAN_INTRINSIC_MSG &quot;<b><font face="Arial"><i>message describing presence or absence of intrinsics</i></font></b>&quot;
@@ -92,16 +97,16 @@ namespace endian
</i></b>}; </i></b>};
// reverse byte order (i.e. endianness) // reverse byte order (i.e. endianness)
int8_t <a href="#reverse_value">reverse_value</a>(int8_t x) noexcept; int8_t <a href="#reverse_endianness">reverse_endianness</a>(int8_t x) noexcept;
int16_t <a href="#reverse_value">reverse_value</a>(int16_t x) noexcept; int16_t <a href="#reverse_endianness">reverse_endianness</a>(int16_t x) noexcept;
int32_t <a href="#reverse_value">reverse_value</a>(int32_t x) noexcept; int32_t <a href="#reverse_endianness">reverse_endianness</a>(int32_t x) noexcept;
int64_t <a href="#reverse_value">reverse_value</a>(int64_t x) noexcept; int64_t <a href="#reverse_endianness">reverse_endianness</a>(int64_t x) noexcept;
uint8_t <a href="#reverse_value">reverse_value</a>(uint8_t x) noexcept; uint8_t <a href="#reverse_endianness">reverse_endianness</a>(uint8_t x) noexcept;
uint16_t <a href="#reverse_value">reverse_value</a>(uint16_t x) noexcept; uint16_t <a href="#reverse_endianness">reverse_endianness</a>(uint16_t x) noexcept;
uint32_t <a href="#reverse_value">reverse_value</a>(uint32_t x) noexcept; uint32_t <a href="#reverse_endianness">reverse_endianness</a>(uint32_t x) noexcept;
uint64_t <a href="#reverse_value">reverse_value</a>(uint64_t x) noexcept; uint64_t <a href="#reverse_endianness">reverse_endianness</a>(uint64_t x) noexcept;
float <a href="#reverse_value">reverse_value</a>(float x) noexcept; float <a href="#reverse_endianness">reverse_endianness</a>(float x) noexcept;
double <a href="#reverse_value">reverse_value</a>(double x) noexcept; double <a href="#reverse_endianness">reverse_endianness</a>(double x) noexcept;
template &lt;class Value&gt; template &lt;class Value&gt;
void <a href="#reverse">reverse</a>(Value&amp; x) noexcept; void <a href="#reverse">reverse</a>(Value&amp; x) noexcept;
@@ -118,30 +123,12 @@ namespace endian
template &lt;class Reversible&gt; template &lt;class Reversible&gt;
void <a href="#little_endian">little_endian</a>(Reversible&amp; x) noexcept; void <a href="#little_endian">little_endian</a>(Reversible&amp; x) noexcept;
// synonyms, based on names popularized by BSD (e.g. OS X, Linux) endian.h
// &quot;h&quot; for &quot;host&quot; (i.e. native), &quot;be&quot; for &quot;big endian&quot;,
// &quot;le&quot; for &quot;little endian&quot;, &quot;m&quot; for &quot;modify&quot; in place
template &lt;class T&gt; T bswap(T x) noexcept {return reverse_value(x);}
template &lt;class T&gt; T htobe(T host) noexcept {return big_endian_value(host);}
template &lt;class T&gt; T htole(T host) noexcept {return little_endian_value(host);}
template &lt;class T&gt; T betoh(T big) noexcept {return big_endian_value(big);}
template &lt;class T&gt; T letoh(T little) noexcept {return little_endian_value(little);}
template &lt;class T&gt; void bswapm(T&amp; x) noexcept {reverse(x);}
template &lt;class T&gt; void htobem(T&amp; host) noexcept {big_endian(host);}
template &lt;class T&gt; void htole(mT&amp; host noexcept) {little_endian(host);}
template &lt;class T&gt; void betohm(T&amp; big) noexcept {big_endian(big);}
template &lt;class T&gt; void letohm(T&amp; little) noexcept {little_endian(little);}
// generic byte order conversion // generic byte order conversion
template &lt;order From, order To, class ReversibleValue&gt; template &lt;order From, order To, class ReversibleValue&gt;
ReversibleValue <a href="#convert_value_generic">convert_value</a>(ReversibleValue from) noexcept; ReversibleValue <a href="#convert_value_generic">convert_value</a>(ReversibleValue from) noexcept;
template &lt;order From, order To, class Reversible&gt; template &lt;order From, order To, class Reversible&gt;
void <a href="#convert_generic">convert</a>(Reversible&amp; x) noexcept; void <a href="#convert_generic">convert</a>(Reversible&amp; x) noexcept;
// runtime effective byte order determination
order <a href="#effective_order">effective_order</a>(order x) noexcept;
// runtime byte-order conversion // runtime byte-order conversion
template &lt;class ReversibleValue&gt; template &lt;class ReversibleValue&gt;
ReversibleValue <a href="#convert_value_runtime">convert_value</a>(ReversibleValue from, ReversibleValue <a href="#convert_value_runtime">convert_value</a>(ReversibleValue from,
@@ -152,67 +139,83 @@ namespace endian
} // namespace endian } // namespace endian
} // namespace boost</pre> } // namespace boost</pre>
<p>The <i><b><code>implementation-defined</code></b></i> text above is either <p dir="ltr">The implementation is required to define the <code>enum class order</code>
<code>big</code> or <code>little</code> according to the endianness of the constant <code>native</code> as
platform.</p> <code>big</code> on big endian platforms and <code>little</code> on little
endian platforms.</p>
<h3><a name="Requirements">Requirements</a></h3> <h3><a name="Requirements">Requirements</a></h3>
<p>The template definitions in this header refer to named <h4>Template argument <code><a name="Reversible">Reversible</a></code> requirements</h4>
requirements whose details are set out in this section. User defined types may <p>This subsection describes names that are used to specify constraints on
be used in the function templates in this header only if they meet the template arguments.</p>
function's template parameter requirements.</p> <p>User-defined types may be used in the function templates in this header only
<h4><a name="ReversibleValue">ReversibleValue</a> requirements</h4> if they meet these requirements.</p>
<p><code>ReversibleValue</code> is an object type to be <p><code>Reversible</code> is an object type to be supplied by a C++ program
supplied by a C++ program instantiating a template; <code>x</code> is a value of instantiating a template.</p>
type (possibly <code>const</code>) <code>ReversibleValue</code>.</p>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111"> <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
<tr> <tr>
<td width="160"><b>Expression</b></td> <td width="160"><b>Expression</b></td>
<td width="150"><b>Return type</b></td> <td width="160"><b>Meaning of x</b></td>
<td width="347"><b>Requirement</b></td> <td width="347"><b>Requirements</b></td>
</tr> </tr>
<tr> <tr>
<td valign="top"> <td valign="top">
<p><code>reverse_value(x)</code></td> <p><code>reverse_endianness(x)</code></td>
<td valign="top"> <td valign="top">
<p><code>ReversibleValue</code></td> <code>x</code> is a value of a possibly <code>const</code> type convertible
to <code>Reversible</code>.</td>
<td> <td>
<p>The returned value is the value of <code>x</code> with the <p>The value of <code>x</code> with the
order of its constituent bytes reversed.</td> order of its constituent bytes reversed is returned.</td>
</tr>
</table>
<h4><a name="Reversible">Reversible</a> requirements</h4>
<p><code>Reversible</code> is an object type to be
supplied by a C++ program instantiating a template; <code>x</code> is a
modifiable lvalue of type <code>Reversible</code>.</p>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
<tr>
<td width="160"><b>Expression</b></td>
<td width="347"><b>Post-condition</b></td>
</tr> </tr>
<tr> <tr>
<td valign="top"> <td valign="top">
<p><code>reverse(x)</code></td> <code>reverse_endianness_in_place(x)</code></td>
<td valign="top">
<code>x</code> is a
modifiable lvalue of type <code>Reversible</code>.</td>
<td> <td>
<p>The order of the constituent bytes of <code>x</code> are The order of the constituent bytes of <code>x</code> are
reversed.</td> reversed.</td>
</tr> </tr>
</table> </table>
<p dir="ltr">See <a href="../example/udt_conversion_example.cpp">
udt_conversion_example.cpp</a> for an example of a UDT that can used in the <blockquote>
<code><a href="#big_endian">big_endian</a></code>, <code>
<a href="#little_endian">little_endian</a></code>, and <code> <p> [<i>Note:</i> A user-defined type meets these requirements by defining a
<a href="#convert_generic">convert</a></code> function templates.</p> non-member function in the same namespace as the UDT itself so that the function
can be found by argument dependent lookup (ADL). <i>&mdash;end note</i>]</p>
</blockquote>
<h4> <a name="Customization-points">Customization points</a> for user-defined types (<a name="UDT">UDT</a>s)</h4>
<p> This subsection describes requirements on the endian library&#39;s own
implementation.</p>
<p> The endianness conversion function templates that return values are
required to perform reversal of endianness if needed by making an unqualified
call to <code>reverse_endianness(<i>argument</i>)</code>, as described in the
preceding table.</p>
<p> The endianness conversion function templates that modify their argument in
place are required to perform reversal of endianness if needed by making an
unqualified call to <code>reverse_endianness_in_place(<i>argument</i>)</code>,
as described in the preceding table.</p>
<p> See <a href="../example/udt_conversion_example.cpp">
udt_conversion_example.cpp</a> for an example user-defined type.</p>
<h3><a name="Functions">Functions</a></h3> <h3><a name="Functions">Functions</a></h3>
<pre><a name="reverse_value"></a>int8_t reverse_value(int8_t x) noexcept; <pre><a name="reverse_endianness"></a>int8_t reverse_endianness(int8_t x) noexcept;
int16_t reverse_value(int16_t x) noexcept; int16_t reverse_endianness(int16_t x) noexcept;
int32_t reverse_value(int32_t x) noexcept; int32_t reverse_endianness(int32_t x) noexcept;
int64_t reverse_value(int64_t x) noexcept; int64_t reverse_endianness(int64_t x) noexcept;
uint8_t reverse_value(uint8_t x) noexcept; uint8_t reverse_endianness(uint8_t x) noexcept;
uint16_t reverse_value(uint16_t x) noexcept; uint16_t reverse_endianness(uint16_t x) noexcept;
uint32_t reverse_value(uint32_t x) noexcept; uint32_t reverse_endianness(uint32_t x) noexcept;
uint64_t reverse_value(uint64_t x) noexcept; uint64_t reverse_endianness(uint64_t x) noexcept;
float reverse_value(float x) noexcept; float reverse_endianness(float x) noexcept;
double reverse_value(double x) noexcept;</pre> double reverse_endianness(double x) noexcept;</pre>
<blockquote> <blockquote>
<p><i>Returns:</i> <i><code>x</code></i>, with the order of its <p><i>Returns:</i> <i><code>x</code></i>, with the order of its
constituent bytes reversed.</p> constituent bytes reversed.</p>
@@ -229,7 +232,7 @@ double reverse_value(double x) noexcept;</pre>
void big_endian(Reversible&amp; x) noexcept;</pre> void big_endian(Reversible&amp; x) noexcept;</pre>
<blockquote> <blockquote>
<p><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_endianness(x)</code>.</p>
<p><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><i>Example:</i></p> <p><i>Example:</i></p>
@@ -245,7 +248,7 @@ big_endian(x); // reverses the byte order of x, unless
void little_endian(Reversible&amp; x) noexcept;</pre> void little_endian(Reversible&amp; x) noexcept;</pre>
<blockquote> <blockquote>
<p><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_endianness(x)</code>.</p>
<p><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><i>Example:</i></p> <p><i>Example:</i></p>
@@ -268,7 +271,7 @@ int32_t y(little_endian(x));
<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><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_endianness(from)</code>.</p>
<p><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><i>Example:</i></p> <p><i>Example:</i></p>
@@ -278,18 +281,12 @@ int32_t y(little_endian(x));
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; <pre><a name="convert_value_runtime"></a>template &lt;class ReversibleValue&gt;
</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><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><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_endianness(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>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> <p><i>Example:</i></p>
<blockquote> <blockquote>
@@ -304,13 +301,13 @@ convert(x, some_order, order::native); // convert to native byte order if neede
<p>See the <a href="index.html#FAQ">Endian home page</a> FAQ for a library-wide <p>See the <a href="index.html#FAQ">Endian home page</a> FAQ for a library-wide
FAQ.</p> FAQ.</p>
<p><b>Why are the template versions of <code>reverse()</code> and <code>reverse_value()</code> <p><b>Why are the template versions of <code>reverse()</code> and <code>reverse_endianness()</code>
in a detail namespace?</b></p> in a detail namespace?</b></p>
<blockquote> <blockquote>
<p>They are unsafe for general use. Consider reversing <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> the bytes of a <code>std::pair</code> as a whole - the bytes from <code>first</code>
would end up in <code>second</code> and visa versa, and this is totally would end up in <code>second</code> and visa versa, and this is totally
wrong!</p> wrong!</p>
@@ -330,11 +327,11 @@ provided.</p>
<h2><a name="Acknowledgements">Acknowledgements</a></h2><p>Tomas Puverle was instrumental in identifying and articulating the need to <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>. 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>.
Pierre Talbot provided the <code>int8_t reverse_value()</code> and templated Pierre Talbot provided the <code>int8_t reverse_endianness()</code> and templated
<code>reverse()</code> implementations.</p> <code>reverse()</code> implementations.</p>
<hr> <hr>
<p>Last revised: <p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->19 November, 2014<!--webbot bot="Timestamp" endspan i-checksum="39499" --></p> <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->07 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38646" --></p>
<p>© Copyright Beman Dawes, 2011, 2013</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>

9
doc/index.html
View File

@@ -58,6 +58,7 @@
<tr> <tr>
<td width="100%" bgcolor="#E8F5FF"> <td width="100%" bgcolor="#E8F5FF">
<a href="../include/boost/endian/conversion.hpp">&lt;boost/endian/conversion.hpp&gt;</a><br> <a href="../include/boost/endian/conversion.hpp">&lt;boost/endian/conversion.hpp&gt;</a><br>
<a href="../include/boost/endian/buffers.hpp">&lt;boost/endian/buffers.hpp&gt;</a><br>
<a href="../include/boost/endian/arithmetic.hpp">&lt;boost/endian/arithmetic.hpp&gt;</a></td> <a href="../include/boost/endian/arithmetic.hpp">&lt;boost/endian/arithmetic.hpp&gt;</a></td>
</tr> </tr>
</table> </table>
@@ -199,8 +200,8 @@ application needs.</p>
<p>These problems are eliminated by defining S like this:</p> <p>These problems are eliminated by defining S like this:</p>
<blockquote> <blockquote>
<p><code>struct S {<br> <p><code>struct S {<br>
&nbsp; big_uint16_t a;<br> &nbsp; big_uint16_ut a;<br>
&nbsp; big_uint32_t b;<br> &nbsp; big_uint32_ut b;<br>
};</code> };</code>
</p></blockquote> </p></blockquote>
</li> </li>
@@ -677,7 +678,7 @@ and 16, 32, and 64-bit aligned integers.</p>
<li><code>order::native</code> is now a synonym for <code>order::big</code> <li><code>order::native</code> is now a synonym for <code>order::big</code>
or <code>order::little</code> according to the endianness of the platform, as or <code>order::little</code> according to the endianness of the platform, as
requested. This reduces the number of template specializations required.</li> requested. This reduces the number of template specializations required.</li>
<li><code>reverse_value()</code> overloads for <code>int8_t</code> and <code> <li><code>reverse_endianness()</code> overloads for <code>int8_t</code> and <code>
uint8_t</code> have been added for improved generality. (Pierre Talbot)</li> uint8_t</code> have been added for improved generality. (Pierre Talbot)</li>
<li>Overloads of <code>reverse()</code> have been replaced with a single <code> <li>Overloads of <code>reverse()</code> have been replaced with a single <code>
reverse()</code> template. (Pierre Talbot)</li> reverse()</code> template. (Pierre Talbot)</li>
@@ -701,7 +702,7 @@ Blechmann, Tim Moore, tymofey, Tomas Puverle, Vincente Botet, Yuval Ronen and
Vitaly Budovski,.</p> Vitaly Budovski,.</p>
<hr> <hr>
<p>Last revised: <p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->19 November, 2014<!--webbot bot="Timestamp" endspan i-checksum="39499" --></p> <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38642" --></p>
<p>© 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>

7
doc/mini_review_topics.html
View File

@@ -71,14 +71,15 @@ the primary use case.</b></p>
<p><b>Support for user defined types (UDTs) is desirable, and should be <p><b>Support for user defined types (UDTs) is desirable, and should be
provided where there would be no conflict with the other concerns.</b></p> provided where there would be no conflict with the other concerns.</b></p>
<blockquote> <blockquote>
<p>Done. <span style="background-color: #FFFF00">Need docs.</span></p> <p>Done. See <a href="conversion.html#Requirements">conversion requirements</a>.</p>
</blockquote> </blockquote>
<p><b>There is some concern that endian integer/float arithmetic operations <p><b>There is some concern that endian integer/float arithmetic operations
might used inadvertently or inappropriately. The impact of adding an endian_buffer might used inadvertently or inappropriately. The impact of adding an endian_buffer
class without arithmetic operations should be investigated.</b></p> class without arithmetic operations should be investigated.</b></p>
<blockquote> <blockquote>
<p>Done. The endian types have been decomposed into class template <code> <p>Done. The endian types have been decomposed into class template <code>
endian_buffer</code> and class template <code>endian_arithmetic</code>. Class <a href="buffers.html">endian_buffer</a></code> and class template <code>
<a href="arithmetic.html">endian_arithmetic</a></code>. Class
<code>endian_buffer</code> is a public base class for <code>endian_arithmetic</code>, <code>endian_buffer</code> is a public base class for <code>endian_arithmetic</code>,
and can also be used by users as a stand-alone class.</p> and can also be used by users as a stand-alone class.</p>
</blockquote> </blockquote>
@@ -98,7 +99,7 @@ might used inadvertently or inappropriately. The impact of adding an endian_buff
</blockquote> </blockquote>
<hr> <hr>
<p>Last revised: <p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->27 November, 2014<!--webbot bot="Timestamp" endspan i-checksum="39496" --></p> <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38642" --></p>
<p><EFBFBD> Copyright Beman Dawes, 2014</p> <p><EFBFBD> Copyright Beman Dawes, 2014</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>