| <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> |
| <a href="conversion.html">Conversion Functions</a> |
| <a href="arithmetic.html">Arithmetic Types</a> |
| <a href="buffers.html">Buffer Types</a> |
| <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> |
| <a href="#Synopsis">Synopsis</a><br> |
| <a href="#Requirements">Requirements</a><br> |
| <code><a href="#EndianReversible">EndianReversible</a></code><br> |
| <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> |
| Header <code><boost/endian/conversion.hpp></code> |
| <a name="Synopsis">Synopsis</a></h3> |
| |
| <pre>#define BOOST_ENDIAN_INTRINSIC_MSG \ |
| "<b><font face="Arial"><i>message describing presence or absence of intrinsics</i></font></b>" |
| |
| namespace boost |
| { |
| namespace endian |
| { |
| enum class <a name="order">order</a> |
| { |
| big, // big endian |
| little, // little endian |
| native = <b><i>implementation-defined-as-big-or-little |
| </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 <class EndianReversible> |
| EndianReversible big_to_native(EndianReversible x) noexcept; |
| template <class EndianReversible> |
| EndianReversible native_to_big(EndianReversible x) noexcept; |
| template <class EndianReversible> |
| EndianReversible little_to_native(EndianReversible x) noexcept; |
| template <class EndianReversible> |
| EndianReversible native_to_little(EndianReversible x) noexcept; |
| template <order O1, order O2, class EndianReversible> |
| EndianReversible conditional_reverse(EndianReversible x) noexcept; |
| template <class EndianReversible> |
| EndianReversible conditional_reverse(EndianReversible x, |
| order order1, order order2) noexcept; |
| |
| template <class EndianReversible> |
| void endian_reverse_inplace(EndianReversible& x) noexcept; |
| |
| template <class EndianReversibleInplace> |
| void big_to_native_inplace(EndianReversibleInplace& x) noexcept; |
| template <class EndianReversibleInplace> |
| void native_to_big_inplace(EndianReversibleInplace& x) noexcept; |
| template <class EndianReversibleInplace> |
| void little_to_native_inplace(EndianReversibleInplace& x) noexcept; |
| template <class EndianReversibleInplace> |
| void native_to_little_inplace(EndianReversibleInplace& x) noexcept; |
| template <order O1, order O2, class EndianReversibleInplace> |
| void conditional_reverse_inplace(EndianReversibleInplace& x) noexcept; |
| template <class EndianReversibleInplace> |
| void conditional_reverse_inplace(EndianReversibleInplace& x, |
| order order1, order order2) noexcept; |
| |
| } // namespace endian |
| } // namespace boost</pre> |
| <p dir="ltr">The implementation is required to define the <code>enum class order</code> |
| constant <code>native</code> as |
| <code>big</code> on big endian platforms and <code>little</code> on little |
| endian platforms.</p> |
| <h3 dir="ltr"><a name="Definitions">Definitions</a></h3> |
| <p dir="ltr">The standard integral types (C++std 3.9.1) except <code>bool</code>, |
| are collectively called the <i>endian types</i>.</p> |
| <h3><a name="Requirements">Requirements</a></h3> |
| <h4><a name="Template-argument-requirements">Template argument requirements</a></h4> |
| <p dir="ltr">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> </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). </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> —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's implementation.</p> |
| |
| <p> The library'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'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 dir="ltr"><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>—end note</i>]</p> |
| </blockquote> |
| |
| <pre>template <class EndianReversible> |
| EndianReversible big_to_native(EndianReversible x) noexcept;</pre> |
| <blockquote> |
| <p> |
| <i>Returns:</i> <code>conditional_reverse<order::big, order::native>(x)</code>.</p> |
| </blockquote> |
| <pre>template <class EndianReversible> |
| EndianReversible native_to_big(EndianReversible x) noexcept; </pre> |
| <blockquote> |
| <p><i>Returns:</i> <code>conditional_reverse<order::native, order::big>(x)</code>.</p> |
| </blockquote> |
| <pre>template <class EndianReversible> |
| EndianReversible little_to_native(EndianReversible x) noexcept; </pre> |
| <blockquote> |
| <p><i>Returns:</i> <code>conditional_reverse<order::little, order::native>(x)</code>.</p> |
| </blockquote> |
| <pre>template <class EndianReversible> |
| EndianReversible native_to_little(EndianReversible x) noexcept; </pre> |
| <blockquote> |
| <p><i>Returns:</i> <code>conditional_reverse<order::native, order::little>(x)</code>.</p> |
| </blockquote> |
| <pre>template <order O1, order O2, class EndianReversible> |
| 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 <class EndianReversible> |
| 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 <class EndianReversible> |
| void endian_reverse_inplace(EndianReversible& x) noexcept; </pre> |
| |
| <blockquote> |
| <p><i>Effects:</i> <code>x</code> <code>= endian_reverse(x)</code>.</p> |
| </blockquote> |
| |
| <pre>template <class EndianReversibleInplace> |
| void big_to_native_inplace(EndianReversibleInplace& x) noexcept; </pre> |
| <blockquote> |
| <p> |
| <i>Effects:</i> <code>conditional_reverse_inplace<order::big, order::native>(x)</code>.</p> |
| </blockquote> |
| <pre>template <class EndianReversibleInplace> |
| void native_to_big_inplace(EndianReversibleInplace& x) noexcept; </pre> |
| <blockquote> |
| <p> |
| <i>Effects:</i> <code>conditional_reverse_inplace<order::native, order::big>(x)</code>.</p> |
| </blockquote> |
| <pre>template <class EndianReversibleInplace> |
| void little_to_native_inplace(EndianReversibleInplace& x) noexcept; </pre> |
| <blockquote> |
| <p> |
| <i>Effects:</i> <code>conditional_reverse_inplace<order::little, order::native>(x)</code>.</p> |
| </blockquote> |
| <pre>template <class EndianReversibleInplace> |
| void native_to_little_inplace(EndianReversibleInplace& x) noexcept; </pre> |
| <blockquote> |
| <p> |
| <i>Effects:</i> <code>conditional_reverse_inplace<order::native, order::little>(x)</code>.</p> |
| </blockquote> |
| <pre>template <order O1, order O2, class EndianReversibleInplace> |
| void conditional_reverse_inplace(EndianReversibleInplace& 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 <class EndianReversibleInplace> |
| void conditional_reverse_inplace(EndianReversibleInplace& 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> |
| |
| <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 -->26 March, 2015<!--webbot bot="Timestamp" endspan i-checksum="28922" --></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> |
