mirror of
https://github.com/boostorg/endian.git
synced 2026-07-05 16:10:56 +02:00
Beman
405 lines
18 KiB
HTML
405 lines
18 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
|
||
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><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>
|
||
{
|
||
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 <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>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> </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><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>
|
||
|
||
<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> |