forked from boostorg/endian
Beman
253 lines
12 KiB
HTML
253 lines
12 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=windows-1252">
|
|
|
|
<title>Boost Endian Conversion Functions</title>
|
|
<link rel="stylesheet" type="text/css" href="../../../doc/src/minimal.css">
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="933">
|
|
<tr>
|
|
<td width="277">
|
|
<a href="../../../index.html">
|
|
<img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86" border="0"></a></td>
|
|
<td width="636" align="middle">
|
|
<font size="7">Endian Conversion Functions</font></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.htm">Boost Home</a>
|
|
<a href="index.html">Endian Home</a>
|
|
<a href="conversion.html">Conversion Functions</a>
|
|
<a href="integers.html">Integer Types</a> Tutorial</b></td>
|
|
</tr>
|
|
</table>
|
|
<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="#Functions">Functions</a><br>
|
|
<a href="#Acknowledgements">Acknowledgements</a></td>
|
|
</tr>
|
|
<tr>
|
|
<td width="100%" bgcolor="#D7EEFF" align="center">
|
|
<b><i>Headers</i></b></td>
|
|
</tr>
|
|
<tr>
|
|
<td width="100%" bgcolor="#E8F5FF">
|
|
<a href="../../../boost/endian/conversion.hpp"><boost/endian/conversion.hpp></a><br>
|
|
<a href="../../../boost/endian/integers.hpp"><boost/endian/integers.hpp></a></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h2><a name="Introduction">Introduction</a></h2>
|
|
|
|
<p>Header <a href="../../../boost/endian/conversion.hpp">boost/endian/conversion.hpp</a>
|
|
provides byte reverse and conversion functions that convert built-in
|
|
integers, <code>float</code>, and <code>double</code> between native byte ordering and <a href="index.html#definition">big or little endian</a> byte
|
|
ordering. User defined types are also supported.</p>
|
|
|
|
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
|
|
<tr>
|
|
<td bgcolor="#FFFFCC">Caution: Only big and little endianness are supported;
|
|
middle endianness is not supported.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h2><a name="Reference">Reference</a></h2>
|
|
|
|
<p><code>noexcept</code> is not present for compilers that do not support it.
|
|
Boost scoped enum emulation is used for compilers that do not support scoped
|
|
enums. Actual functions are <code>inline</code> if appropriate.</p>
|
|
|
|
<h3>
|
|
<a name="Synopsis">Synopsis</a></h3>
|
|
|
|
<pre>namespace boost
|
|
{
|
|
namespace endian
|
|
{
|
|
enum class order {big, little, native};
|
|
|
|
// reverse byte order (i.e. endianness)
|
|
int16_t reverse_value(int16_t x) noexcept;
|
|
int32_t reverse_value(int32_t x) noexcept;
|
|
int64_t reverse_value(int64_t x) noexcept;
|
|
uint16_t reverse_value(uint16_t x) noexcept;
|
|
uint32_t reverse_value(uint32_t x) noexcept;
|
|
uint64_t reverse_value(uint64_t x) noexcept;
|
|
float reverse_value(float x) noexcept;
|
|
double reverse_value(double x) noexcept;
|
|
|
|
void reverse(int16_t& x) noexcept;
|
|
void reverse(int32_t& x) noexcept;
|
|
void reverse(int64_t& x) noexcept;
|
|
void reverse(uint16_t& x) noexcept;
|
|
void reverse(uint32_t& x) noexcept;
|
|
void reverse(uint64_t& x) noexcept;
|
|
void reverse(float& x) noexcept;
|
|
void reverse(double& x) noexcept;
|
|
|
|
// reverse byte order unless native endianness is big
|
|
template <class ReversibleValue >
|
|
ReversibleValue big_endian_value(ReversibleValue x) noexcept;
|
|
template <class Reversible>
|
|
void big_endian(Reversible& x) noexcept;
|
|
|
|
// reverse byte order unless native endianness is little
|
|
template <class ReversibleValue >
|
|
ReversibleValue little_endian_value(ReversibleValue x) noexcept;
|
|
template <class Reversible>
|
|
void little_endian(Reversible& x) noexcept;
|
|
|
|
// synonyms, based on names popularized by BSD (e.g. OS X, Linux)
|
|
// "h" for "host" (i.e. native), "be" for "big endian",
|
|
// "le" for "little endian", "m" for "modify" in place
|
|
template <class T> T bswap(T x) noexcept {return reverse_value(x);}
|
|
template <class T> T htobe(T host) noexcept {return big_endian_value(host);}
|
|
template <class T> T htole(T host) noexcept {return little_endian_value(host);}
|
|
template <class T> T betoh(T big) noexcept {return big_endian_value(big);}
|
|
template <class T> T letoh(T little) noexcept {return little_endian_value(little);}
|
|
|
|
template <class T> void bswapm(T& x) noexcept {reverse(x);}
|
|
template <class T> void htobem(T& host) noexcept {big_endian(host);}
|
|
template <class T> void htole(mT& host noexcept) {little_endian(host);}
|
|
template <class T> void betohm(T& big) noexcept {big_endian(big);}
|
|
template <class T> void letohm(T& little) noexcept {little_endian(little);}
|
|
|
|
// compile-time generic byte order conversion
|
|
template <order From, order To, class ReversibleValue>
|
|
ReversibleValue convert_value(ReversibleValue from) noexcept;
|
|
template <order From, order To, class Reversible>
|
|
void convert(Reversible& x) noexcept;
|
|
|
|
// runtime effective byte order determination
|
|
order effective_order(order x) noexcept;
|
|
|
|
// runtime byte-order conversion
|
|
template <class ReversibleValue>
|
|
ReversibleValue convert_value(ReversibleValue from,
|
|
order from_order, order to_order) noexcept;
|
|
template <class Reversible>
|
|
void convert(Reversible& x,
|
|
order from_order, order to_order) noexcept;
|
|
|
|
} // namespace endian
|
|
} // namespace boost</pre>
|
|
<h3 dir="ltr"><a name="Functions">Functions</a></h3>
|
|
<pre dir="ltr">int16_t reverse_value(int16_t x) noexcept;
|
|
int32_t reverse_value(int32_t x) noexcept;
|
|
int64_t reverse_value(int64_t x) noexcept;
|
|
uint16_t reverse_value(uint16_t x) noexcept;
|
|
uint32_t reverse_value(uint32_t x) noexcept;
|
|
uint64_t reverse_value(uint64_t x) noexcept;
|
|
float reverse_value(float x) noexcept;
|
|
double reverse_value(double x) noexcept;</pre>
|
|
<blockquote>
|
|
<p dir="ltr"><i>Returns:</i> x, with the order of bytes reversed.</p>
|
|
</blockquote>
|
|
<pre dir="ltr">void reverse(int16_t& x) noexcept;
|
|
void reverse(int32_t& x) noexcept;
|
|
void reverse(int64_t& x) noexcept;
|
|
void reverse(uint16_t& x) noexcept;
|
|
void reverse(uint32_t& x) noexcept;
|
|
void reverse(uint64_t& x) noexcept;
|
|
void reverse(float& x) noexcept;
|
|
void reverse(double& x) noexcept;</pre>
|
|
<blockquote>
|
|
<p dir="ltr"><i>Effects:</i> Reverses the order of bytes in <i><code>x</code></i>.</p>
|
|
</blockquote>
|
|
<pre dir="ltr">template <class ReversibleValue >
|
|
ReversibleValue big_endian_value(ReversibleValue x) noexcept;
|
|
template <class Reversible>
|
|
void big_endian(Reversible& x) noexcept;</pre>
|
|
<blockquote>
|
|
<p dir="ltr"><i>Returns (first form)</i>: <code>x</code> if the native byte order is big
|
|
endian, otherwise <code>reverse_value(x)</code>.</p>
|
|
<p dir="ltr"><i>Effects (second form):</i> None if the native byte order is big
|
|
endian, otherwise <code>reverse(x)</code>.</p>
|
|
<p dir="ltr"><i>Example:</i></p>
|
|
<blockquote>
|
|
<pre>int32_t x = <b><i>some-value</i></b>;
|
|
big_endian(x); // reverses the byte order of x, unless
|
|
// the native byte order is big-endian</pre>
|
|
</blockquote>
|
|
</blockquote>
|
|
<pre dir="ltr">template <class ReversibleValue >
|
|
ReversibleValue little_endian_value(ReversibleValue x) noexcept;
|
|
template <class Reversible>
|
|
void little_endian(Reversible& x) noexcept;</pre>
|
|
<blockquote>
|
|
<p dir="ltr"><i>Returns (first form)</i>: <code>x</code> if the native byte order is little
|
|
endian, otherwise <code>reverse_value(x)</code>.</p>
|
|
<p dir="ltr"><i>Effects (second form):</i> None if the native byte order is little
|
|
endian, otherwise <code>reverse(x)</code>.</p>
|
|
<p dir="ltr"><i>Example:</i></p>
|
|
<blockquote>
|
|
<pre>int32_t x = <b><i>some-value</i></b>;
|
|
int32_t y(little_endian(x));
|
|
// y has been set to x; the byte order is reversed unless
|
|
// the native byte order is little-endian.</pre>
|
|
</blockquote>
|
|
</blockquote>
|
|
<pre dir="ltr">template <order From, order To, class ReversibleValue>
|
|
ReversibleValue convert_value(ReversibleValue from) noexcept;
|
|
template <order From, order To, class Reversible>
|
|
void convert(Reversible& x) noexcept;
|
|
</pre>
|
|
<blockquote>
|
|
<p dir="ltr">The <b><i>effective order</i></b> of an order template parameter
|
|
is the same as the order template parameter if the parameter is not <code>
|
|
order::native</code>, otherwise it is the constant <code>order::big</code> or
|
|
<code>order::little</code> that represents the actual native byte order.</p>
|
|
<p dir="ltr"><i>Returns (first form)</i>: <code>from</code> if <code>From</code>
|
|
and <code>To</code> have the same effective order, otherwise <code>
|
|
reverse_value(from)</code>.</p>
|
|
<p dir="ltr"><i>Effects (second form):</i> None if <code>From</code> and <code>
|
|
To</code> have the same effective order, otherwise <code>reverse(x)</code>.</p>
|
|
<p dir="ltr"><i>Example:</i></p>
|
|
<blockquote>
|
|
<pre>int32_t x;
|
|
<i>... read an external big-endian value into x</i>
|
|
convert<order::big, order::native>(x); // more generic equivalent of big_endian(x);</pre>
|
|
</blockquote>
|
|
</blockquote>
|
|
<pre>order effective_order(order x) noexcept;<blockquote><p dir="ltr"><i>Returns:</i> <code>x</code> if <code>x != order::native</code>, otherwise the <code>order</code> constant for the actual native byte order.</p><p dir="ltr"><i>Example:</i></p><blockquote><pre dir="ltr">effective_order(order::big); // returns order::big
|
|
effective_order(order::little); // returns order::little
|
|
effective_order(order::native); // returns order::big if the native order
|
|
// is big-endian, otherwise order::little</pre></blockquote></blockquote><pre dir="ltr">template <class ReversibleValue>
|
|
ReversibleValue convert_value(ReversibleValue from,
|
|
order from_order, order to_order) noexcept;
|
|
template <class Reversible>
|
|
void convert(Reversible& x,
|
|
order from_order, order to_order) noexcept;</pre><blockquote><p dir="ltr"><i>Returns (first form)</i>: <code>from</code> if <code>effect_order(from_order) == effective_order(to_order)</code>, otherwise <code>reverse_value(from)</code>.</p>
|
|
<p dir="ltr"><i>Effects (second form):</i> None if <code>effect_order(from_order) == effective_order(to_order)</code>, otherwise <code>reverse(x)</code>.</p>
|
|
<p dir="ltr"><i>Example:</i></p>
|
|
<blockquote>
|
|
<pre>int32_t x;
|
|
<i>... read an external value of an endianness know only at runtime into x</i>
|
|
convert(x, some_order, order::native); // convert to native byte order if needed</pre>
|
|
</blockquote>
|
|
</blockquote><h2><a name="Acknowledgements">Acknowledgements</a></h2><p>Tomas Puverle was instrumental in identifying and articulating the need to
|
|
support endian conversion as separate from endian types.</p>
|
|
<hr>
|
|
<p>Last revised: <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->18 May, 2013<!--webbot bot="Timestamp" endspan i-checksum="13991" --></p>
|
|
<p>© Copyright Beman Dawes, 2011</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> |