quick-test/doc/conversion.html

<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>
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">

<title>Endian Conversion Functions</title>
<link href="styles.css" rel="stylesheet">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
  <tr>
    <td>
<a href="../../../index.html">
<img src="../../../boost.png" alt="Boost logo" align="middle" border="0" width="277" height="86" ></a></td>
    <td align="middle">
    <b>
    <font size="6">Endian Conversion Functions</font></b></td>
  </tr>
</table>

<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="100%">
  <tr>
    <td><b>
    <a href="index.html">Endian Home</a>&nbsp;&nbsp;&nbsp;&nbsp;
    <a href="conversion.html">Conversion Functions</a>&nbsp;&nbsp;&nbsp;&nbsp;
    <a href="arithmetic.html">Arithmetic Types</a>&nbsp;&nbsp;&nbsp;&nbsp;
    <a href="buffers.html">Buffer Types</a>&nbsp;&nbsp;&nbsp;&nbsp;
    <a href="choosing_approach.html">Choosing Approach</a></b></td>
  </tr>
</table>

<p></p>

<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" align="right">
  <tr>
    <td width="100%" bgcolor="#D7EEFF" align="center">
      <i><b>Contents</b></i></td>
  </tr>
  <tr>
    <td width="100%" bgcolor="#E8F5FF">
      <a href="#Introduction">Introduction</a><br>
      <a href="#Reference">Reference</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Synopsis">Synopsis</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Requirements">Requirements</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code><a href="#EndianReversible">EndianReversible</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="#Acknowledgements">Acknowledgements</a></td>
  </tr>
  </table>

<h2><a name="Introduction">Introduction</a></h2>

<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 
the built-in 
integer types 
between native, big, or little endian byte 
ordering. User defined types are also supported.</p>

<h2><a name="Reference">Reference</a></h2>

<p>Functions are implemented <code>inline</code> if appropriate.<code> </code>
For C++03 compilers, <code> noexcept</code> is 
elided. 
Boost scoped enum emulation is used so that the library still works for compilers that do not support scoped enums.</p>

<h3><a name="Definitions">Definitions</a></h3>
<p><b><i>Endianness</i></b> refers to the ordering of bytes within internal or 
external integers and other arithmetic data. Most-significant byte first is 
called <b><i>big endian</i></b> ordering. Least-significant byte first is called
<b><i>little endian</i></b> ordering. Other orderings are possible and some CPU 
architectures support both big and little ordering.</p>
<blockquote>
<p>[<i>Note:</i> The names are derived from
<a href="http://en.wikipedia.org/wiki/Jonathan_Swift" title="Jonathan Swift">
Jonathan Swift</a>'s satirical novel <i>
<a href="http://en.wikipedia.org/wiki/Gulliver's_Travels" title="Gulliver's Travels">
Gulliver’s Travels</a></i>, where rival kingdoms opened their soft-boiled eggs 
at different ends. Wikipedia has an extensive description of
<a href="https://en.wikipedia.org/wiki/Endianness">Endianness</a>. <i>—end note</i>]</p>
</blockquote>
<p>The standard integral types (C++std 3.9.1) except <code>bool</code> 
are collectively called the <b> <i>endian types</i></b>.</p>

<h3>
Header <code>&lt;boost/endian/conversion.hpp&gt;</code>
<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;

namespace boost
{
namespace endian
{
  enum class <a name="order">order</a>
  {
    native = <b><i>see below,
</i></b>    big    = <b><i>see below</i></b>,
    little = <b><i>see below</i></b>,
 <b><i>  </i></b>};

  int8_t   <a href="#endian_reverse">endian_reverse</a>(int8_t x) noexcept;
  int16_t  <a href="#endian_reverse">endian_reverse</a>(int16_t x) noexcept;
  int32_t  <a href="#endian_reverse">endian_reverse</a>(int32_t x) noexcept;
  int64_t  <a href="#endian_reverse">endian_reverse</a>(int64_t x) noexcept;
  uint8_t  <a href="#endian_reverse">endian_reverse</a>(uint8_t x) noexcept;
  uint16_t <a href="#endian_reverse">endian_reverse</a>(uint16_t x) noexcept;
  uint32_t <a href="#endian_reverse">endian_reverse</a>(uint32_t x) noexcept;
  uint64_t <a href="#endian_reverse">endian_reverse</a>(uint64_t x) noexcept;

  template &lt;class EndianReversible&gt;
    EndianReversible big_to_native(EndianReversible x) noexcept;
  template &lt;class EndianReversible&gt;
    EndianReversible native_to_big(EndianReversible x) noexcept;
  template &lt;class EndianReversible&gt;
    EndianReversible little_to_native(EndianReversible x) noexcept;
  template &lt;class EndianReversible&gt;
    EndianReversible native_to_little(EndianReversible x) noexcept;
  template &lt;order O1, order O2, class EndianReversible&gt;
    EndianReversible conditional_reverse(EndianReversible x) noexcept;
  template &lt;class EndianReversible&gt;
    EndianReversible conditional_reverse(EndianReversible x,
      order order1, order order2) noexcept;
      
  template &lt;class EndianReversible&gt;
    void endian_reverse_inplace(EndianReversible&amp; x) noexcept;

  template &lt;class EndianReversibleInplace&gt;
    void big_to_native_inplace(EndianReversibleInplace&amp; x) noexcept;
  template &lt;class EndianReversibleInplace&gt;
    void native_to_big_inplace(EndianReversibleInplace&amp; x) noexcept;
  template &lt;class EndianReversibleInplace&gt;
    void little_to_native_inplace(EndianReversibleInplace&amp; x) noexcept;
  template &lt;class EndianReversibleInplace&gt;
    void native_to_little_inplace(EndianReversibleInplace&amp; x) noexcept;
  template &lt;order O1, order O2, class EndianReversibleInplace&gt;
    void conditional_reverse_inplace(EndianReversibleInplace&amp; x) noexcept; 
  template &lt;class EndianReversibleInplace&gt;
   void conditional_reverse_inplace(EndianReversibleInplace&amp; x,
     order order1, order order2) noexcept;

} // namespace endian
} // namespace boost</pre>
<p>The values of <code>order::little</code> and <code>order::big</code> shall 
not be equal to one another. </p>
<p><a name="native-order-specification"></a>The value of <code>order::native</code> 
shall be:</p>
<ul>
  <li>equal to <code>order::big</code> if the execution environment is big 
  endian, otherwise</li>
  <li>equal to <code>order::little</code> if the execution environment is little 
  endian, otherwise</li>
  <li>unequal to both <code>order::little</code> and <code>order::big</code>.</li>
</ul>
<h3><a name="Requirements">Requirements</a></h3>
<h4><a name="Template-argument-requirements">Template argument requirements</a></h4>
<p>The template definitions in the <code>boost/endian/conversion.hpp</code> 
header refer to various named requirements whose details are set out in the 
tables in this subsection. In these tables, <code>T</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>T</code>; <code>mlx</code> is a 
modifiable lvalue of type <code>T</code>.</p>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
  <tr>
    <td colspan="3" align="center"><b><code><a name="EndianReversible">EndianReversible</a></code></b> 
    requirements (in addition to <b><code>CopyConstructible</code></b>)</td>
  </tr>
  <tr>
    <td><b>Expression</b></td>
    <td><b>Return<br>
    type</b></td>
    <td><b>Requirements</b></td>
  </tr>
  <tr>
    <td valign="top"><code>endian_reverse(x)</code></td>
    <td align="center" valign="top"><code>T</code></td>
    <td> <code>T</code> is an endian type or a class type.<p>If <code>T</code> is 
    an endian type, returns the value of <code>x</code> with the order of bytes 
    reversed.</p>
    <p>If <code>T</code> is a class type, the function:</p>
    <ul>
      <li>Returns the value of <code>x</code> 
    with the order of bytes reversed for all data members of types or arrays of 
    types that meet the <code>EndianReversible</code> requirements, and;</li>
      <li>Is a non-member function in the same namespace as <code>T</code> that 
can be found by argument dependent lookup (ADL). </li>
    </ul>
    </td>
  </tr>
</table>
<p>&nbsp;</p>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
  <tr>
    <td colspan="2" align="center"><b><code><a name="EndianReversibleInplace">EndianReversibleInplace</a></code></b> 
    requirements (in addition to <b><code>CopyConstructible</code></b>)</td>
  </tr>
  <tr>
    <td><b>Expression</b></td>
    <td><b>Requirements</b></td>
  </tr>
  <tr>
    <td valign="top"><code>endian_reverse_inplace(mlx)</code></td>
    <td> <code>T</code> is an endian type or a class type.<p>If <code>T</code> is 
    an endian type, reverses the order of bytes in <code>mlx</code>.</p>
    <p>If <code>T</code> is a class type, the function:</p>
    <ul>
      <li>Reverses the order of bytes of all data members of <code>mlx</code> 
      that have types or arrays of 
    types that meet the <code>EndianReversible</code> or <code>EndianReversibleInplace</code> 
      requirements, and;</li>
      <li>Is a non-member function in the same namespace as <code>T</code> that 
can be found by argument dependent lookup (ADL).&nbsp; </li>
    </ul>
    </td>
  </tr>
</table>

<p> [<i>Note:</i> Because there is a function template for <code>endian_reverse_inplace</code> 
that calls <code>endian_reverse</code>, only <code>endian_reverse</code> 
is required for a user-defined type to meet the <code>EndianReversibleInplace</code> 
requirements. Although User-defined types are not required to supply an <code>endian_reverse_inplace</code> 
function, doing so may improve efficiency. <i>&nbsp;&mdash;end note</i>]</p>

<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  implementation.</p>

<p> The library&#39;s function templates requiring <code>
<a href="#EndianReversible">EndianReversible</a></code> are 
required to perform reversal of endianness if needed by making an unqualified 
call to <code>endian_reverse()</code>.</p>

<p> The library&#39;s function templates requiring <code>
<a href="#EndianReversibleInplace">EndianReversibleInplace</a></code> are required to perform reversal of endianness if needed by making an 
unqualified call to <code>endian_reverse_inplace()</code>.</p>

<p> See <b><code>example/udt_conversion_example.cpp</code></b> for an example user-defined type.</p>

<h3><a name="Functions">Functions</a></h3>
<pre><a name="endian_reverse"></a>int8_t   endian_reverse(int8_t x) noexcept;
int16_t  endian_reverse(int16_t x) noexcept;
int32_t  endian_reverse(int32_t x) noexcept;
int64_t  endian_reverse(int64_t x) noexcept;
uint8_t  endian_reverse(uint8_t x) noexcept;
uint16_t endian_reverse(uint16_t x) noexcept;
uint32_t endian_reverse(uint32_t x) noexcept;
uint64_t endian_reverse(uint64_t x) noexcept;</pre>
<blockquote>
  <p><i>Returns:</i> <i><code>x</code></i>, with the order of its 
  constituent bytes reversed.</p>
  <p><i>Remarks:</i> The type of <i><code>x</code></i> meets the <code>EndianReversible</code> requirements.</p>
  <p>[<i>Note:</i> The Boost.Endian library does not provide overloads for the C++ standard library 
    supplied types. <i>&mdash;end note</i>]</p>
</blockquote>

<pre>template &lt;class EndianReversible&gt;
EndianReversible big_to_native(EndianReversible x) noexcept;</pre>
    <blockquote>
        <p>
            <i>Returns:</i> <code>conditional_reverse&lt;order::big, order::native&gt;(x)</code>.</p>
    </blockquote>
<pre>template &lt;class EndianReversible&gt;
EndianReversible native_to_big(EndianReversible x) noexcept; </pre>
<blockquote>
  <p><i>Returns:</i> <code>conditional_reverse&lt;order::native, order::big&gt;(x)</code>.</p>
</blockquote>
<pre>template &lt;class EndianReversible&gt;
EndianReversible little_to_native(EndianReversible x) noexcept; </pre>
    <blockquote>
        <p><i>Returns:</i> <code>conditional_reverse&lt;order::little, order::native&gt;(x)</code>.</p>
    </blockquote>
<pre>template &lt;class EndianReversible&gt;
EndianReversible native_to_little(EndianReversible x) noexcept; </pre>
    <blockquote>
        <p><i>Returns:</i> <code>conditional_reverse&lt;order::native, order::little&gt;(x)</code>.</p>
    </blockquote>
<pre>template &lt;order O1, order O2, class EndianReversible&gt;
EndianReversible conditional_reverse(EndianReversible x) noexcept; </pre>
    <blockquote>
        <p><i>Returns:</i> <code>x</code> if <code>O1 == O2,</code> otherwise <code>endian_reverse(x)</code>.</p>
        <p><i>Remarks: </i>Whether <code>x</code> or <code>endian_reverse(x)</code> is to be returned shall be determined at compile time.</p>
    </blockquote>
<pre>template &lt;class EndianReversible&gt;
EndianReversible conditional_reverse(EndianReversible x,
      order order1, order order2) noexcept; </pre>
    <blockquote>
        <p><i>Returns:</i> <code>order1 == order2 ? x : endian_reverse(x)</code>.</p>
    </blockquote>
      
<pre>template &lt;class EndianReversible&gt;
void endian_reverse_inplace(EndianReversible&amp; x) noexcept; </pre>

<blockquote>
        <p><i>Effects:</i> <code>x</code> <code>= endian_reverse(x)</code>.</p>
    </blockquote>

<pre>template &lt;class EndianReversibleInplace&gt;
void big_to_native_inplace(EndianReversibleInplace&amp; x) noexcept; </pre>
<blockquote>
        <p>
            <i>Effects:</i> <code>conditional_reverse_inplace&lt;order::big, order::native&gt;(x)</code>.</p>
    </blockquote>
<pre>template &lt;class EndianReversibleInplace&gt;
void native_to_big_inplace(EndianReversibleInplace&amp; x) noexcept; </pre>
<blockquote>
        <p>
            <i>Effects:</i> <code>conditional_reverse_inplace&lt;order::native, order::big&gt;(x)</code>.</p>
    </blockquote>
<pre>template &lt;class EndianReversibleInplace&gt;
void little_to_native_inplace(EndianReversibleInplace&amp; x) noexcept; </pre>
<blockquote>
        <p>
            <i>Effects:</i> <code>conditional_reverse_inplace&lt;order::little, order::native&gt;(x)</code>.</p>
    </blockquote>
<pre>template &lt;class EndianReversibleInplace&gt;
void native_to_little_inplace(EndianReversibleInplace&amp; x) noexcept; </pre>
<blockquote>
        <p>
            <i>Effects:</i> <code>conditional_reverse_inplace&lt;order::native, order::little&gt;(x)</code>.</p>
    </blockquote>
<pre>template &lt;order O1, order O2, class EndianReversibleInplace&gt;
void conditional_reverse_inplace(EndianReversibleInplace&amp; x) noexcept; </pre> 
<blockquote>
        <p><i>Effects:</i> None if <code>O1 == O2,</code> otherwise <code>endian_reverse_inplace(x)</code>.</p>
        <p><i>Remarks: </i>Which effect applies shall be determined at compile time.</p>
    </blockquote>
<pre>template &lt;class EndianReversibleInplace&gt;
void conditional_reverse_inplace(EndianReversibleInplace&amp; x,
     order order1, order order2) noexcept; </pre>


<blockquote>
        <p><i>Effects: </i>If <code>order1 == order2</code> then <code>endian_reverse_inplace(x)</code>.</p>
    </blockquote>


<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 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>Why are exact-length 8, 16, 32, and 64-bit integers supported rather than the built-in 
char, short, int, long, long long, etc?</b></p>

<blockquote>

<p>The primary use case, portable file or network data, needs these de facto 
standard sizes. Using types that vary with the platform would greatly limit 
portability for both programs and data.</p>

</blockquote>

<p><b>Why not use the Linux names (htobe16, htole16, be16toh, le16toh, etc.) ?</b></p>

<blockquote>

<p>Those names are non-standard and vary even between POSIX-like operating 
systems. A C++ library TS was going to use those names, but found they were 
sometimes implemented as macros. Since macros do not respect scoping and 
namespace rules, to use them would be very error prone.</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  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 <b><code>boost/endian/detail/intrinsic.hpp</code></b>. 
Pierre Talbot provided the <code>int8_t endian_reverse()</code> and templated
<code>endian_reverse_inplace()</code> implementations.</p>
<hr>
<p>Last revised: 
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->14 October, 2015<!--webbot bot="Timestamp" endspan i-checksum="38874" --></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>

</html>
-											Change the specification for native ordering to allow implementations to support orderings in addition to big and little. Thanks to Howard Hinnant for suggesting this change and providing draft wording. Also update headers to reflect actual inclusion hierarchy.
										
										
											2015-10-16 10:30:34 -04:00
+								<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns="http://www.w3.org/TR/REC-html40">
-											Docs work in process, including getting started on conversion.html
										
										
											2011-05-27 20:18:13 +00:00
 								<head>
 								<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
 								<meta name="ProgId" content="FrontPage.Editor.Document">
-											Last pass through docs
										
										
											2013-05-28 11:04:03 -04:00
+								<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
-											Docs work in process, including getting started on conversion.html
										
										
											2011-05-27 20:18:13 +00:00
-											Add overall css style sheet for more uniform presentation and ease of maintenance.
										
										
											2014-11-12 08:26:01 -05:00
+								<title>Endian Conversion Functions</title>
 								<link href="styles.css" rel="stylesheet">
-											Docs work in process, including getting started on conversion.html
										
										
											2011-05-27 20:18:13 +00:00
+								</head>
 								<body>
-											Switch to inline style sheet
										
										
											2013-05-28 17:06:32 -04:00
+								<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
-											Docs work in process, including getting started on conversion.html
										
										
											2011-05-27 20:18:13 +00:00
+								  <tr>
-											Switch to inline style sheet
										
										
											2013-05-28 17:06:32 -04:00
+								    <td>
-											Docs work in process, including getting started on conversion.html
										
										
											2011-05-27 20:18:13 +00:00
+								<a href="../../../index.html">
-											Add docs for BOOST_ENDIAN_DEPRECATED_NAMES compatibility. Fix inspect issues.
										
										
											2015-01-19 07:41:28 -05:00
+								<img src="../../../boost.png" alt="Boost logo" align="middle" border="0" width="277" height="86" ></a></td>
-											Switch to inline style sheet
										
										
											2013-05-28 17:06:32 -04:00
+								    <td align="middle">
-											Preliminary doc changes to reflect addition of buffers.
										
										
											2014-11-19 15:58:15 -05:00
+								    <b>
-											Rename "reverse_endianness" to "endian_reverse". Shorter but still plenty explicit. See bikeshed.txt for alternatives considered.
										
										
											2014-12-10 08:30:30 -05:00
+								    <font size="6">Endian Conversion Functions</font></b></td>
-											Docs work in process, including getting started on conversion.html
										
										
											2011-05-27 20:18:13 +00:00
+								  </tr>
 								</table>
 								<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="100%">
 								  <tr>
-											Refactor "Choosing the approach" into its own page. It was dominating the main home page, yet is really a topic for study after other material is absorbed.
										
										
											2015-01-02 10:46:53 -05:00
+								    <td><b>
-											Docs work in process, including getting started on conversion.html
										
										
											2011-05-27 20:18:13 +00:00
+								    <a href="index.html">Endian Home</a>&nbsp;&nbsp;&nbsp;&nbsp;
-											Continue cleanup
										
										
											2011-09-04 13:51:49 +00:00
+								    <a href="conversion.html">Conversion Functions</a>&nbsp;&nbsp;&nbsp;&nbsp;
-											Preliminary doc changes to reflect addition of buffers.
										
										
											2014-11-19 15:58:15 -05:00
+								    <a href="arithmetic.html">Arithmetic Types</a>&nbsp;&nbsp;&nbsp;&nbsp;
-											Refactor "Choosing the approach" into its own page. It was dominating the main home page, yet is really a topic for study after other material is absorbed.
										
										
											2015-01-02 10:46:53 -05:00
+								    <a href="buffers.html">Buffer Types</a>&nbsp;&nbsp;&nbsp;&nbsp;
 								    <a href="choosing_approach.html">Choosing Approach</a></b></td>
-											Continue cleanup
										
										
											2011-09-04 13:51:49 +00:00
+								  </tr>
 								</table>
-											Spacing and minor content tweak.
										
										
											2013-05-28 21:11:18 -04:00
 								<p></p>
-											Continue cleanup
										
										
											2011-09-04 13:51:49 +00:00
+								<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" align="right">
 								  <tr>
 								    <td width="100%" bgcolor="#D7EEFF" align="center">
 								      <i><b>Contents</b></i></td>
 								  </tr>
 								  <tr>
 								    <td width="100%" bgcolor="#E8F5FF">
 								      <a href="#Introduction">Introduction</a><br>
 								      <a href="#Reference">Reference</a><br>
 								&nbsp;&nbsp;&nbsp; <a href="#Synopsis">Synopsis</a><br>
-											Continue refinement of specs. Add to FAQ. Create function group bookmarks and link to them.
										
										
											2013-05-19 17:08:42 -04:00
+								&nbsp;&nbsp;&nbsp; <a href="#Requirements">Requirements</a><br>
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code><a href="#EndianReversible">EndianReversible</a></code><br>
-											Bring docs in sync with implementation. Still somewhat incomplete.
										
										
											2014-12-09 07:04:48 -05:00
+								&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#Customization-points">Customization for
 								      UDTs</a><br>
 								      <a href="#Functions">Functions</a><br>
-											Last pass through docs
										
										
											2013-05-28 11:04:03 -04:00
+								      <a href="#FAQ">FAQ</a><br>
-											Continue cleanup
										
										
											2011-09-04 13:51:49 +00:00
+								      <a href="#Acknowledgements">Acknowledgements</a></td>
 								  </tr>
-											Don another pass through the docs.
										
										
											2015-01-17 16:53:41 -05:00
+								  </table>
-											Docs work in process, including getting started on conversion.html
										
										
											2011-05-27 20:18:13 +00:00
 								<h2><a name="Introduction">Introduction</a></h2>
-											Fix broken links, tweak content.
										
										
											2013-05-28 21:33:07 -04:00
+								<p>Header <a href="../include/boost/endian/conversion.hpp">boost/endian/conversion.hpp</a>
-											Continue refinement of specs. Add to FAQ. Create function group bookmarks and link to them.
										
										
											2013-05-19 17:08:42 -04:00
+								provides byte order reversal and conversion functions that convert objects of
-											Update docs to reflect removal of floating point support from 1.58.0
										
										
											2015-03-25 08:05:49 -04:00
+								the built-in
 								integer types
-											Continue refinement of specs. Add to FAQ. Create function group bookmarks and link to them.
										
										
											2013-05-19 17:08:42 -04:00
+								between native, big, or little endian byte
-											Start rework of synopsis.
										
										
											2013-05-18 16:53:27 -04:00
+								ordering. User defined types are also supported.</p>
-											Docs work in process, including getting started on conversion.html
										
										
											2011-05-27 20:18:13 +00:00
-											Rename flip() to invert()
										
										
											2011-09-03 17:50:46 +00:00
+								<h2><a name="Reference">Reference</a></h2>
-											Wording tweaks from Rob Stewart. Modify styles.css for more uniform presentation across browsers.
										
										
											2015-02-11 09:02:58 -05:00
+								<p>Functions are implemented <code>inline</code> if appropriate.<code> </code>
 								For C++03 compilers, <code> noexcept</code> is
-											Change the specification for native ordering to allow implementations to support orderings in addition to big and little. Thanks to Howard Hinnant for suggesting this change and providing draft wording. Also update headers to reflect actual inclusion hierarchy.
										
										
											2015-10-16 10:30:34 -04:00
+								elided.
-											Minor editing tweaks.
										
										
											2014-12-10 09:58:01 -05:00
+								Boost scoped enum emulation is used so that the library still works for compilers that do not support scoped enums.</p>
-											Change the specification for native ordering to allow implementations to support orderings in addition to big and little. Thanks to Howard Hinnant for suggesting this change and providing draft wording. Also update headers to reflect actual inclusion hierarchy.
										
										
											2015-10-16 10:30:34 -04:00
+								<h3><a name="Definitions">Definitions</a></h3>
 								<p><b><i>Endianness</i></b> refers to the ordering of bytes within internal or
 								external integers and other arithmetic data. Most-significant byte first is
 								called <b><i>big endian</i></b> ordering. Least-significant byte first is called
 								<b><i>little endian</i></b> ordering. Other orderings are possible and some CPU
 								architectures support both big and little ordering.</p>
 								<blockquote>
 								<p>[<i>Note:</i> The names are derived from
 								<a href="http://en.wikipedia.org/wiki/Jonathan_Swift" title="Jonathan Swift">
 								Jonathan Swift</a>'s satirical novel <i>
 								<a href="http://en.wikipedia.org/wiki/Gulliver's_Travels" title="Gulliver's Travels">
 								Gulliver’s Travels</a></i>, where rival kingdoms opened their soft-boiled eggs
 								at different ends. Wikipedia has an extensive description of
 								<a href="https://en.wikipedia.org/wiki/Endianness">Endianness</a>. <i>—end note</i>]</p>
 								</blockquote>
 								<p>The standard integral types (C++std 3.9.1) except <code>bool</code>
 								are collectively called the <b> <i>endian types</i></b>.</p>
-											Rename flip() to invert()
										
										
											2011-09-03 17:50:46 +00:00
+								<h3>
-											Bring docs in sync with implementation. Still somewhat incomplete.
										
										
											2014-12-09 07:04:48 -05:00
+								Header <code>&lt;boost/endian/conversion.hpp&gt;</code>
-											Rename flip() to invert()
										
										
											2011-09-03 17:50:46 +00:00
+								<a name="Synopsis">Synopsis</a></h3>
-											Docs work in process, including getting started on conversion.html
										
										
											2011-05-27 20:18:13 +00:00
-											Wording tweaks from Rob Stewart. Modify styles.css for more uniform presentation across browsers.
										
										
											2015-02-11 09:02:58 -05:00
+								<pre>#define BOOST_ENDIAN_INTRINSIC_MSG \
 								   &quot;<b><font face="Arial"><i>message describing presence or absence of intrinsics</i></font></b>&quot;
-											Continue refinement of specs. Add to FAQ. Create function group bookmarks and link to them.
										
										
											2013-05-19 17:08:42 -04:00
 								namespace boost
-											Docs work in process, including getting started on conversion.html
										
										
											2011-05-27 20:18:13 +00:00
+								{
 								namespace endian
 								{
-											Do a pass through docs, bringing up to date where needed.
										
										
											2014-08-12 10:34:37 -04:00
+								  enum class <a name="order">order</a>
 								  {
-											Change the specification for native ordering to allow implementations to support orderings in addition to big and little. Thanks to Howard Hinnant for suggesting this change and providing draft wording. Also update headers to reflect actual inclusion hierarchy.
										
										
											2015-10-16 10:30:34 -04:00
+								    native = <b><i>see below,
 								</i></b>    big    = <b><i>see below</i></b>,
 								    little = <b><i>see below</i></b>,
 								 <b><i>  </i></b>};
-											Rename flip() to invert()
										
										
											2011-09-03 17:50:46 +00:00
-											Rename "reverse_endianness" to "endian_reverse". Shorter but still plenty explicit. See bikeshed.txt for alternatives considered.
										
										
											2014-12-10 08:30:30 -05:00
+								  int8_t   <a href="#endian_reverse">endian_reverse</a>(int8_t x) noexcept;
 								  int16_t  <a href="#endian_reverse">endian_reverse</a>(int16_t x) noexcept;
 								  int32_t  <a href="#endian_reverse">endian_reverse</a>(int32_t x) noexcept;
 								  int64_t  <a href="#endian_reverse">endian_reverse</a>(int64_t x) noexcept;
 								  uint8_t  <a href="#endian_reverse">endian_reverse</a>(uint8_t x) noexcept;
 								  uint16_t <a href="#endian_reverse">endian_reverse</a>(uint16_t x) noexcept;
 								  uint32_t <a href="#endian_reverse">endian_reverse</a>(uint32_t x) noexcept;
 								  uint64_t <a href="#endian_reverse">endian_reverse</a>(uint64_t x) noexcept;
-											Docs work in process, including getting started on conversion.html
										
										
											2011-05-27 20:18:13 +00:00
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								  template &lt;class EndianReversible&gt;
 								    EndianReversible big_to_native(EndianReversible x) noexcept;
 								  template &lt;class EndianReversible&gt;
 								    EndianReversible native_to_big(EndianReversible x) noexcept;
 								  template &lt;class EndianReversible&gt;
 								    EndianReversible little_to_native(EndianReversible x) noexcept;
 								  template &lt;class EndianReversible&gt;
 								    EndianReversible native_to_little(EndianReversible x) noexcept;
 								  template &lt;order O1, order O2, class EndianReversible&gt;
 								    EndianReversible conditional_reverse(EndianReversible x) noexcept;
 								  template &lt;class EndianReversible&gt;
 								    EndianReversible conditional_reverse(EndianReversible x,
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								      order order1, order order2) noexcept;
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								  template &lt;class EndianReversible&gt;
 								    void endian_reverse_inplace(EndianReversible&amp; x) noexcept;
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								  template &lt;class EndianReversibleInplace&gt;
 								    void big_to_native_inplace(EndianReversibleInplace&amp; x) noexcept;
 								  template &lt;class EndianReversibleInplace&gt;
 								    void native_to_big_inplace(EndianReversibleInplace&amp; x) noexcept;
 								  template &lt;class EndianReversibleInplace&gt;
 								    void little_to_native_inplace(EndianReversibleInplace&amp; x) noexcept;
 								  template &lt;class EndianReversibleInplace&gt;
 								    void native_to_little_inplace(EndianReversibleInplace&amp; x) noexcept;
 								  template &lt;order O1, order O2, class EndianReversibleInplace&gt;
 								    void conditional_reverse_inplace(EndianReversibleInplace&amp; x) noexcept;
 								  template &lt;class EndianReversibleInplace&gt;
 								   void conditional_reverse_inplace(EndianReversibleInplace&amp; x,
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								     order order1, order order2) noexcept;
-											Rename flip() to invert()
										
										
											2011-09-03 17:50:46 +00:00
 								} // namespace endian
-											Docs work in process, including getting started on conversion.html
										
										
											2011-05-27 20:18:13 +00:00
+								} // namespace boost</pre>
-											Change the specification for native ordering to allow implementations to support orderings in addition to big and little. Thanks to Howard Hinnant for suggesting this change and providing draft wording. Also update headers to reflect actual inclusion hierarchy.
										
										
											2015-10-16 10:30:34 -04:00
+								<p>The values of <code>order::little</code> and <code>order::big</code> shall
 								not be equal to one another. </p>
 								<p><a name="native-order-specification"></a>The value of <code>order::native</code>
 								shall be:</p>
 								<ul>
 								  <li>equal to <code>order::big</code> if the execution environment is big
 								  endian, otherwise</li>
 								  <li>equal to <code>order::little</code> if the execution environment is little
 								  endian, otherwise</li>
 								  <li>unequal to both <code>order::little</code> and <code>order::big</code>.</li>
 								</ul>
-											Add FAQ. Update Acknowledgments. Supply ReversibleValue and Reversible requirements.
										
										
											2013-05-19 11:07:33 -04:00
+								<h3><a name="Requirements">Requirements</a></h3>
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								<h4><a name="Template-argument-requirements">Template argument requirements</a></h4>
-											Change the specification for native ordering to allow implementations to support orderings in addition to big and little. Thanks to Howard Hinnant for suggesting this change and providing draft wording. Also update headers to reflect actual inclusion hierarchy.
										
										
											2015-10-16 10:30:34 -04:00
+								<p>The template definitions in the <code>boost/endian/conversion.hpp</code>
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								header refer to various named requirements whose details are set out in the
 								tables in this subsection. In these tables, <code>T</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>T</code>; <code>mlx</code> is a
 								modifiable lvalue of type <code>T</code>.</p>
-											Add FAQ. Update Acknowledgments. Supply ReversibleValue and Reversible requirements.
										
										
											2013-05-19 11:07:33 -04:00
+								<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
 								  <tr>
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								    <td colspan="3" align="center"><b><code><a name="EndianReversible">EndianReversible</a></code></b>
 								    requirements (in addition to <b><code>CopyConstructible</code></b>)</td>
-											Add FAQ. Update Acknowledgments. Supply ReversibleValue and Reversible requirements.
										
										
											2013-05-19 11:07:33 -04:00
+								  </tr>
 								  <tr>
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								    <td><b>Expression</b></td>
 								    <td><b>Return<br>
 								    type</b></td>
 								    <td><b>Requirements</b></td>
-											Add FAQ. Update Acknowledgments. Supply ReversibleValue and Reversible requirements.
										
										
											2013-05-19 11:07:33 -04:00
+								  </tr>
 								  <tr>
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								    <td valign="top"><code>endian_reverse(x)</code></td>
 								    <td align="center" valign="top"><code>T</code></td>
 								    <td> <code>T</code> is an endian type or a class type.<p>If <code>T</code> is
 								    an endian type, returns the value of <code>x</code> with the order of bytes
 								    reversed.</p>
-											Wording tweaks from Rob Stewart. Modify styles.css for more uniform presentation across browsers.
										
										
											2015-02-11 09:02:58 -05:00
+								    <p>If <code>T</code> is a class type, the function:</p>
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								    <ul>
 								      <li>Returns the value of <code>x</code>
 								    with the order of bytes reversed for all data members of types or arrays of
 								    types that meet the <code>EndianReversible</code> requirements, and;</li>
 								      <li>Is a non-member function in the same namespace as <code>T</code> that
 								can be found by argument dependent lookup (ADL). </li>
 								    </ul>
 								    </td>
 								  </tr>
 								</table>
 								<p>&nbsp;</p>
 								<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
 								  <tr>
 								    <td colspan="2" align="center"><b><code><a name="EndianReversibleInplace">EndianReversibleInplace</a></code></b>
 								    requirements (in addition to <b><code>CopyConstructible</code></b>)</td>
 								  </tr>
 								  <tr>
 								    <td><b>Expression</b></td>
 								    <td><b>Requirements</b></td>
 								  </tr>
 								  <tr>
 								    <td valign="top"><code>endian_reverse_inplace(mlx)</code></td>
 								    <td> <code>T</code> is an endian type or a class type.<p>If <code>T</code> is
 								    an endian type, reverses the order of bytes in <code>mlx</code>.</p>
-											Wording tweaks from Rob Stewart. Modify styles.css for more uniform presentation across browsers.
										
										
											2015-02-11 09:02:58 -05:00
+								    <p>If <code>T</code> is a class type, the function:</p>
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								    <ul>
 								      <li>Reverses the order of bytes of all data members of <code>mlx</code>
 								      that have types or arrays of
 								    types that meet the <code>EndianReversible</code> or <code>EndianReversibleInplace</code>
 								      requirements, and;</li>
 								      <li>Is a non-member function in the same namespace as <code>T</code> that
 								can be found by argument dependent lookup (ADL).&nbsp; </li>
 								    </ul>
 								    </td>
-											Add FAQ. Update Acknowledgments. Supply ReversibleValue and Reversible requirements.
										
										
											2013-05-19 11:07:33 -04:00
+								  </tr>
 								</table>
-											Bring docs in sync with implementation. Still somewhat incomplete.
										
										
											2014-12-09 07:04:48 -05:00
-											Change "in_place" to "inplace". Rationale: shortens names without impacting expressiveness.
										
										
											2014-12-10 09:39:03 -05:00
+								<p> [<i>Note:</i> Because there is a function template for <code>endian_reverse_inplace</code>
-											Rename "reverse_endianness" to "endian_reverse". Shorter but still plenty explicit. See bikeshed.txt for alternatives considered.
										
										
											2014-12-10 08:30:30 -05:00
+								that calls <code>endian_reverse</code>, only <code>endian_reverse</code>
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								is required for a user-defined type to meet the <code>EndianReversibleInplace</code>
 								requirements. Although User-defined types are not required to supply an <code>endian_reverse_inplace</code>
-											Wording tweaks from Rob Stewart. Modify styles.css for more uniform presentation across browsers.
										
										
											2015-02-11 09:02:58 -05:00
+								function, doing so may improve efficiency. <i>&nbsp;&mdash;end note</i>]</p>
-											Bring docs in sync with implementation. Still somewhat incomplete.
										
										
											2014-12-09 07:04:48 -05:00
 								<h4> <a name="Customization-points">Customization points</a> for user-defined types (<a name="UDT">UDT</a>s)</h4>
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								<p> This subsection describes requirements on the Endian library&#39;s  implementation.</p>
-											Bring docs in sync with implementation. Still somewhat incomplete.
										
										
											2014-12-09 07:04:48 -05:00
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								<p> The library&#39;s function templates requiring <code>
 								<a href="#EndianReversible">EndianReversible</a></code> are
-											Bring docs in sync with implementation. Still somewhat incomplete.
										
										
											2014-12-09 07:04:48 -05:00
+								required to perform reversal of endianness if needed by making an unqualified
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								call to <code>endian_reverse()</code>.</p>
-											Bring docs in sync with implementation. Still somewhat incomplete.
										
										
											2014-12-09 07:04:48 -05:00
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								<p> The library&#39;s function templates requiring <code>
 								<a href="#EndianReversibleInplace">EndianReversibleInplace</a></code> are required to perform reversal of endianness if needed by making an
 								unqualified call to <code>endian_reverse_inplace()</code>.</p>
-											Bring docs in sync with implementation. Still somewhat incomplete.
										
										
											2014-12-09 07:04:48 -05:00
-											Don another pass through the docs.
										
										
											2015-01-17 16:53:41 -05:00
+								<p> See <b><code>example/udt_conversion_example.cpp</code></b> for an example user-defined type.</p>
-											Bring docs in sync with implementation. Still somewhat incomplete.
										
										
											2014-12-09 07:04:48 -05:00
-											Add FAQ. Update Acknowledgments. Supply ReversibleValue and Reversible requirements.
										
										
											2013-05-19 11:07:33 -04:00
+								<h3><a name="Functions">Functions</a></h3>
-											Rename "reverse_endianness" to "endian_reverse". Shorter but still plenty explicit. See bikeshed.txt for alternatives considered.
										
										
											2014-12-10 08:30:30 -05:00
+								<pre><a name="endian_reverse"></a>int8_t   endian_reverse(int8_t x) noexcept;
 								int16_t  endian_reverse(int16_t x) noexcept;
 								int32_t  endian_reverse(int32_t x) noexcept;
 								int64_t  endian_reverse(int64_t x) noexcept;
 								uint8_t  endian_reverse(uint8_t x) noexcept;
 								uint16_t endian_reverse(uint16_t x) noexcept;
 								uint32_t endian_reverse(uint32_t x) noexcept;
-											Update docs to reflect removal of floating point support from 1.58.0
										
										
											2015-03-25 08:05:49 -04:00
+								uint64_t endian_reverse(uint64_t x) noexcept;</pre>
-											Rename flip() to invert()
										
										
											2011-09-03 17:50:46 +00:00
+								<blockquote>
-											Change the specification for native ordering to allow implementations to support orderings in addition to big and little. Thanks to Howard Hinnant for suggesting this change and providing draft wording. Also update headers to reflect actual inclusion hierarchy.
										
										
											2015-10-16 10:30:34 -04:00
+								  <p><i>Returns:</i> <i><code>x</code></i>, with the order of its
-											Add FAQ. Update Acknowledgments. Supply ReversibleValue and Reversible requirements.
										
										
											2013-05-19 11:07:33 -04:00
+								  constituent bytes reversed.</p>
-											Wording tweaks from Rob Stewart. Modify styles.css for more uniform presentation across browsers.
										
										
											2015-02-11 09:02:58 -05:00
+								  <p><i>Remarks:</i> The type of <i><code>x</code></i> meets the <code>EndianReversible</code> requirements.</p>
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								  <p>[<i>Note:</i> The Boost.Endian library does not provide overloads for the C++ standard library
 								    supplied types. <i>&mdash;end note</i>]</p>
-											Rename flip() to invert()
										
										
											2011-09-03 17:50:46 +00:00
+								</blockquote>
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								<pre>template &lt;class EndianReversible&gt;
 								EndianReversible big_to_native(EndianReversible x) noexcept;</pre>
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								    <blockquote>
 								        <p>
-											Update docs to reflect removal of floating point support from 1.58.0
										
										
											2015-03-25 08:05:49 -04:00
+								            <i>Returns:</i> <code>conditional_reverse&lt;order::big, order::native&gt;(x)</code>.</p>
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								    </blockquote>
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								<pre>template &lt;class EndianReversible&gt;
 								EndianReversible native_to_big(EndianReversible x) noexcept; </pre>
-											Rename flip() to invert()
										
										
											2011-09-03 17:50:46 +00:00
+								<blockquote>
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								  <p><i>Returns:</i> <code>conditional_reverse&lt;order::native, order::big&gt;(x)</code>.</p>
-											Rename flip() to invert()
										
										
											2011-09-03 17:50:46 +00:00
+								</blockquote>
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								<pre>template &lt;class EndianReversible&gt;
 								EndianReversible little_to_native(EndianReversible x) noexcept; </pre>
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								    <blockquote>
 								        <p><i>Returns:</i> <code>conditional_reverse&lt;order::little, order::native&gt;(x)</code>.</p>
 								    </blockquote>
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								<pre>template &lt;class EndianReversible&gt;
 								EndianReversible native_to_little(EndianReversible x) noexcept; </pre>
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								    <blockquote>
 								        <p><i>Returns:</i> <code>conditional_reverse&lt;order::native, order::little&gt;(x)</code>.</p>
 								    </blockquote>
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								<pre>template &lt;order O1, order O2, class EndianReversible&gt;
 								EndianReversible conditional_reverse(EndianReversible x) noexcept; </pre>
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								    <blockquote>
-											Update docs to reflect removal of floating point support from 1.58.0
										
										
											2015-03-25 08:05:49 -04:00
+								        <p><i>Returns:</i> <code>x</code> if <code>O1 == O2,</code> otherwise <code>endian_reverse(x)</code>.</p>
 								        <p><i>Remarks: </i>Whether <code>x</code> or <code>endian_reverse(x)</code> is to be returned shall be determined at compile time.</p>
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								    </blockquote>
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								<pre>template &lt;class EndianReversible&gt;
 								EndianReversible conditional_reverse(EndianReversible x,
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								      order order1, order order2) noexcept; </pre>
 								    <blockquote>
-											Rename "reverse_endianness" to "endian_reverse". Shorter but still plenty explicit. See bikeshed.txt for alternatives considered.
										
										
											2014-12-10 08:30:30 -05:00
+								        <p><i>Returns:</i> <code>order1 == order2 ? x : endian_reverse(x)</code>.</p>
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								    </blockquote>
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								<pre>template &lt;class EndianReversible&gt;
 								void endian_reverse_inplace(EndianReversible&amp; x) noexcept; </pre>
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
-											Rename flip() to invert()
										
										
											2011-09-03 17:50:46 +00:00
+								<blockquote>
-											Rename "reverse_endianness" to "endian_reverse". Shorter but still plenty explicit. See bikeshed.txt for alternatives considered.
										
										
											2014-12-10 08:30:30 -05:00
+								        <p><i>Effects:</i> <code>x</code> <code>= endian_reverse(x)</code>.</p>
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								    </blockquote>
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								<pre>template &lt;class EndianReversibleInplace&gt;
 								void big_to_native_inplace(EndianReversibleInplace&amp; x) noexcept; </pre>
-											Rename flip() to invert()
										
										
											2011-09-03 17:50:46 +00:00
+								<blockquote>
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								        <p>
-											Update docs to reflect removal of floating point support from 1.58.0
										
										
											2015-03-25 08:05:49 -04:00
+								            <i>Effects:</i> <code>conditional_reverse_inplace&lt;order::big, order::native&gt;(x)</code>.</p>
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								    </blockquote>
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								<pre>template &lt;class EndianReversibleInplace&gt;
 								void native_to_big_inplace(EndianReversibleInplace&amp; x) noexcept; </pre>
-											Semantics complete.
										
										
											2013-05-19 08:26:09 -04:00
+								<blockquote>
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								        <p>
-											Update docs to reflect removal of floating point support from 1.58.0
										
										
											2015-03-25 08:05:49 -04:00
+								            <i>Effects:</i> <code>conditional_reverse_inplace&lt;order::native, order::big&gt;(x)</code>.</p>
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								    </blockquote>
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								<pre>template &lt;class EndianReversibleInplace&gt;
 								void little_to_native_inplace(EndianReversibleInplace&amp; x) noexcept; </pre>
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								<blockquote>
 								        <p>
-											Change "in_place" to "inplace". Rationale: shortens names without impacting expressiveness.
										
										
											2014-12-10 09:39:03 -05:00
+								            <i>Effects:</i> <code>conditional_reverse_inplace&lt;order::little, order::native&gt;(x)</code>.</p>
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								    </blockquote>
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								<pre>template &lt;class EndianReversibleInplace&gt;
 								void native_to_little_inplace(EndianReversibleInplace&amp; x) noexcept; </pre>
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								<blockquote>
 								        <p>
-											Update docs to reflect removal of floating point support from 1.58.0
										
										
											2015-03-25 08:05:49 -04:00
+								            <i>Effects:</i> <code>conditional_reverse_inplace&lt;order::native, order::little&gt;(x)</code>.</p>
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								    </blockquote>
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								<pre>template &lt;order O1, order O2, class EndianReversibleInplace&gt;
 								void conditional_reverse_inplace(EndianReversibleInplace&amp; x) noexcept; </pre>
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								<blockquote>
-											Update docs to reflect removal of floating point support from 1.58.0
										
										
											2015-03-25 08:05:49 -04:00
+								        <p><i>Effects:</i> None if <code>O1 == O2,</code> otherwise <code>endian_reverse_inplace(x)</code>.</p>
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								        <p><i>Remarks: </i>Which effect applies shall be determined at compile time.</p>
 								    </blockquote>
-											Decompose Reversible into EndianReversible and EndianReversibleInplace.
										
										
											2014-12-11 11:41:44 -05:00
+								<pre>template &lt;class EndianReversibleInplace&gt;
 								void conditional_reverse_inplace(EndianReversibleInplace&amp; x,
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								     order order1, order order2) noexcept; </pre>
 								<blockquote>
-											Change "in_place" to "inplace". Rationale: shortens names without impacting expressiveness.
										
										
											2014-12-10 09:39:03 -05:00
+								        <p><i>Effects: </i>If <code>order1 == order2</code> then <code>endian_reverse_inplace(x)</code>.</p>
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								    </blockquote>
-											Continue refinement of specs. Add to FAQ. Create function group bookmarks and link to them.
										
										
											2013-05-19 17:08:42 -04:00
-											Last pass through docs
										
										
											2013-05-28 11:04:03 -04:00
+								<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 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
-											Drop the _unless_big and _unless_little functions. KISS. They were confusing, and less confusing names were never found.
										
										
											2014-12-09 20:43:47 -05:00
+								endian use cases and are more efficient for user-defined types that have
-											Last pass through docs
										
										
											2013-05-28 11:04:03 -04:00
+								members such as string data that do not need to be reversed. Thus both forms are
 								provided.</p>
 								</blockquote>
-											Refined rationale for choice of exact-length types for conversion support.
										
										
											2014-12-16 08:49:01 -05:00
+								<p><b>Why are exact-length 8, 16, 32, and 64-bit integers supported rather than the built-in
-											Add FAQ entry for built-in integer names.
										
										
											2014-12-11 12:05:31 -05:00
+								char, short, int, long, long long, etc?</b></p>
 								<blockquote>
 								<p>The primary use case, portable file or network data, needs these de facto
 								standard sizes. Using types that vary with the platform would greatly limit
 								portability for both programs and data.</p>
 								</blockquote>
-											All Linux names FAQ entry.
										
										
											2015-07-21 14:44:36 -04:00
+								<p><b>Why not use the Linux names (htobe16, htole16, be16toh, le16toh, etc.) ?</b></p>
 								<blockquote>
 								<p>Those names are non-standard and vary even between POSIX-like operating
 								systems. A C++ library TS was going to use those names, but found they were
 								sometimes implemented as macros. Since macros do not respect scoping and
 								namespace rules, to use them would be very error prone.</p>
 								</blockquote>
-											Update docs to reflect removal of floating point support from 1.58.0
										
										
											2015-03-25 08:05:49 -04:00
+								<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  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 <b><code>boost/endian/detail/intrinsic.hpp</code></b>.
-											Rename "reverse_endianness" to "endian_reverse". Shorter but still plenty explicit. See bikeshed.txt for alternatives considered.
										
										
											2014-12-10 08:30:30 -05:00
+								Pierre Talbot provided the <code>int8_t endian_reverse()</code> and templated
-											Minor editing tweaks.
										
										
											2014-12-10 09:58:01 -05:00
+								<code>endian_reverse_inplace()</code> implementations.</p>
-											Docs work in process, including getting started on conversion.html
										
										
											2011-05-27 20:18:13 +00:00
+								<hr>
-											Change the specification for native ordering to allow implementations to support orderings in addition to big and little. Thanks to Howard Hinnant for suggesting this change and providing draft wording. Also update headers to reflect actual inclusion hierarchy.
										
										
											2015-10-16 10:30:34 -04:00
+								<p>Last revised:
 								<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->14 October, 2015<!--webbot bot="Timestamp" endspan i-checksum="38874" --></p>
-											Last pass through docs
										
										
											2013-05-28 11:04:03 -04:00
+								<p>© Copyright Beman Dawes, 2011, 2013</p>
-											Semantics complete.
										
										
											2013-05-19 08:26:09 -04:00
+								<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>
-											Docs work in process, including getting started on conversion.html
										
										
											2011-05-27 20:18:13 +00:00
 								</body>
 								</html>