mirror of
https://github.com/boostorg/endian.git
synced 2026-07-05 16:10:56 +02:00
Beman
378 lines
17 KiB
HTML
378 lines
17 KiB
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>
|
|
<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, and also types <code>float</code> and <code>double,</code>
|
|
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>
|
|
|
|
<p> </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;
|
|
float <a href="#endian_reverse">endian_reverse</a>(float x) noexcept;
|
|
double <a href="#endian_reverse">endian_reverse</a>(double 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>,
|
|
and the floating point types <code>float</code> and <code>double</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;
|
|
float endian_reverse(float x) noexcept;
|
|
double endian_reverse(double 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 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
|
|
<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 -->09 February, 2015<!--webbot bot="Timestamp" endspan i-checksum="40544" --></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> |