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

Add FAQ. Update Acknowledgments. Supply ReversibleValue and Reversible requirements.

Browse Source
This commit is contained in:
Beman
2013-05-19 11:07:33 -04:00
parent e4a92a56b0
commit 29d65d2e2f
1 changed files with 57 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
doc/conversion.html
View File

@@ -67,6 +67,14 @@ ordering. User defined types are also supported.</p>
</tr>
</table>
<h2><a name="FAQ">FAQ</a></h2>
<p><b>Why are <code>reverse()</code> and <code>reverse_value()</code> templates
in a detail namespace?</b> They are unsafe for general use. Consider reversing
the bytes of a <b><code>std::pair</code></b> - the bytes from <b><code>first</code></b>
would end up in <b><code>second</code></b> and visa versa, and this is totally
wrong!</p>
<h2><a name="Reference">Reference</a></h2>
<p><code>noexcept</code> is not present for compilers that do not support it.
@@ -147,8 +155,48 @@ namespace endian
} // namespace endian
} // namespace boost</pre>
<h3 dir="ltr"><a name="Functions">Functions</a></h3>
<pre dir="ltr">int16_t reverse_value(int16_t x) noexcept;
<h3><a name="Requirements">Requirements</a></h3>
<p>The template definitions in this library refer to various named
requirements whose details are set out in this section. </p>
<h4><a name="ReversibleValue">ReversibleValue</a> requirements</h4>
<p><code>ReversibleValue</code> is an object or reference type to be
supplied by a C++ program instantiating a template; <code>x</code> is a value of
type (possibly <code>const</code>) <code>ReversibleValue</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="150"><b>Return type</b></td>
<td width="347"><b>Requirement</b></td>
</tr>
<tr>
<td valign="top">
<p><code>reverse_value(x)</code></td>
<td valign="top">
<p><a name="ReversibleValue"><code>ReversibleValue</code></a></td>
<td>
<p>The returned value is the value of <code>x</code> with the
order of its constituent bytes reversed.</td>
</tr>
</table>
<h4><a name="Reversible">Reversible</a> requirements</h4>
<p><code>Reversible</code> is an object or reference 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>
<td valign="top">
<p><code>reverse(x)</code></td>
<td>
<p>The order of the constituent bytes of <code>x</code> are
reversed.</td>
</tr>
</table>
<h3><a name="Functions">Functions</a></h3>
<pre>int16_t reverse_value(int16_t x) noexcept;
int32_t reverse_value(int32_t x) noexcept;
int64_t reverse_value(int64_t x) noexcept;
uint16_t reverse_value(uint16_t x) noexcept;
@@ -157,9 +205,10 @@ uint64_t reverse_value(uint64_t x) noexcept;
float reverse_value(float x) noexcept;
double reverse_value(double x) noexcept;</pre>
<blockquote>
<p dir="ltr"><i>Returns:</i> x, with the order of bytes reversed.</p>
<p><i>Returns:</i> <i><code>x</code></i>, with the order of its
constituent bytes reversed.</p>
</blockquote>
<pre dir="ltr">void reverse(int16_t&amp; x) noexcept;
<pre>void reverse(int16_t&amp; x) noexcept;
void reverse(int32_t&amp; x) noexcept;
void reverse(int64_t&amp; x) noexcept;
void reverse(uint16_t&amp; x) noexcept;
@@ -168,9 +217,10 @@ void reverse(uint64_t&amp; x) noexcept;
void reverse(float&amp; x) noexcept;
void reverse(double&amp; x) noexcept;</pre>
<blockquote>
<p dir="ltr"><i>Effects:</i> Reverses the order of bytes in <i><code>x</code></i>.</p>
<p><i>Postconditions:</i> The order of the constituent bytes of
<code>x</code> are reversed.</p>
</blockquote>
<pre dir="ltr">template &lt;class ReversibleValue &gt;
<pre>template &lt;class ReversibleValue &gt;
ReversibleValue big_endian_value(ReversibleValue x) noexcept;
template &lt;class Reversible&gt;
void big_endian(Reversible&amp; x) noexcept;</pre>
@@ -242,7 +292,7 @@ template &lt;class Reversible&gt;
convert(x, some_order, order::native); // convert to native byte order if needed</pre>
</blockquote>
</blockquote><h2><a name="Acknowledgements">Acknowledgements</a></h2><p>Tomas Puverle was instrumental in identifying and articulating the need to
support endian conversion as separate from endian types.</p>
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 -->18 May, 2013<!--webbot bot="Timestamp" endspan i-checksum="13991" --></p>
<p><EFBFBD> Copyright Beman Dawes, 2011</p>