forked from boostorg/endian
Beman
224 lines
9.6 KiB
HTML
224 lines
9.6 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="#Members">Members</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>
|
|
|
|
<h2><a name="Reference">Reference</a></h2>
|
|
|
|
<h3>
|
|
<a name="Synopsis">Synopsis</a></h3>
|
|
|
|
<pre>namespace boost
|
|
{
|
|
namespace endian
|
|
{
|
|
enum class order {big, little, native};
|
|
|
|
// reverse byte order (i.e. endianness)
|
|
//
|
|
inline int16_t reverse_value(int16_t x) noexcept;
|
|
inline int32_t reverse_value(int32_t x) noexcept;
|
|
inline int64_t reverse_value(int64_t x) noexcept;
|
|
inline uint16_t reverse_value(uint16_t x) noexcept;
|
|
inline uint32_t reverse_value(uint32_t x) noexcept;
|
|
inline uint64_t reverse_value(uint64_t x) noexcept;
|
|
inline float reverse_value(float x) noexcept;
|
|
inline double reverse_value(double x) noexcept;
|
|
|
|
// reverse bytes unless native endianness is big
|
|
//
|
|
template <class ReversibleValue >
|
|
inline ReversibleValue big_endian_value(ReversibleValue x) noexcept;
|
|
|
|
// reverse bytes unless native endianness is little
|
|
//
|
|
template <class ReversibleValue >
|
|
inline ReversibleValue little_endian_value(ReversibleValue x) noexcept;
|
|
|
|
// synonyms, based on names popularized by BSD (e.g. OS X, Linux)
|
|
// "h" stands for "host" (i.e. native), "be" for "big endian", "le" for "little endian"
|
|
//
|
|
template <class T> T bswap(T x) {return reverse_value(x);}
|
|
template <class T> T htobe(T host) {return big_endian_value(host);}
|
|
template <class T> T htole(T host) {return little_endian_value(host);}
|
|
template <class T> T betoh(T big) {return big_endian_value(big);}
|
|
template <class T> T letoh(T little) {return little_endian_value(little);}
|
|
|
|
// compile-time generic byte order conversion
|
|
template <order From, order To, class ReversibleValue>
|
|
ReversibleValue convert_value(ReversibleValue from) noexcept;
|
|
|
|
// runtime actual byte-order determination
|
|
order actual_order(order o) noexcept;
|
|
|
|
// runtime byte-order conversion
|
|
template <class ReversibleValue>
|
|
ReversibleValue convert_value(ReversibleValue from,
|
|
order from_order, order to_order) noexcept;
|
|
|
|
//--------------------------------------------------------------------------------------//
|
|
// modify in place interface //
|
|
//--------------------------------------------------------------------------------------//
|
|
|
|
// reverse byte order (i.e. endianness)
|
|
//
|
|
inline void reverse(int16_t& x) noexcept;
|
|
inline void reverse(int32_t& x) noexcept;
|
|
inline void reverse(int64_t& x) noexcept;
|
|
inline void reverse(uint16_t& x) noexcept;
|
|
inline void reverse(uint32_t& x) noexcept;
|
|
inline void reverse(uint64_t& x) noexcept;
|
|
inline void reverse(float& x) noexcept;
|
|
inline void reverse(double& x) noexcept;
|
|
|
|
// reverse unless native endianness is big
|
|
template <class Reversible>
|
|
inline void big_endian(Reversible& x) noexcept;
|
|
// Effects: none if native endian order is big, otherwise reverse(x)
|
|
|
|
// reverse unless native endianness is little
|
|
template <class Reversible>
|
|
inline void little_endian(Reversible& x) noexcept;
|
|
// Effects: none if native endian order is little, otherwise reverse(x);
|
|
|
|
// synonyms based on names popularized by BSD, e.g. OS X, Linux.
|
|
// "h" stands for "host" (i.e. native), "be" for "big endian",
|
|
// "le" for "little endian", "m" for "modify in place"
|
|
template <class T> void mbswap(T& x) {reverse(x);}
|
|
template <class T> void mhtobe(T& host_) {big_endian(host_);}
|
|
template <class T> void mhtole(T& host_) {little_endian(host_);}
|
|
template <class T> void mbetoh(T& big_endian_) {big_endian(big_endian_);}
|
|
template <class T> void mletoh(T& little_endian_) {little_endian(little_endian_);}
|
|
|
|
// compile-time generic byte order conversion
|
|
template <BOOST_SCOPED_ENUM(order) From, BOOST_SCOPED_ENUM(order) To, class Reversible>
|
|
void convert(Reversible& x) noexcept;
|
|
|
|
// runtime byte-order conversion
|
|
template <class Reversible>
|
|
void convert(Reversible& x, BOOST_SCOPED_ENUM(order) from_order,
|
|
BOOST_SCOPED_ENUM(order) to_order) noexcept;
|
|
|
|
} // namespace endian
|
|
} // namespace boost</pre>
|
|
<h3 dir="ltr"><a name="Members">Members</a></h3>
|
|
<pre dir="ltr">inline void reorder(int16_t& x);
|
|
inline void reorder(int32_t& x);
|
|
inline void reorder(int64_t& x);
|
|
inline void reorder(uint16_t& x);
|
|
inline void reorder(uint32_t& x);
|
|
inline void reorder(uint64_t& x);</pre>
|
|
<blockquote>
|
|
<p dir="ltr"><i>Effects:</i> Reverses the byte order of <i><code>x</code></i>.</p>
|
|
</blockquote>
|
|
<pre dir="ltr">inline void reorder(int16_t source, int16_t& target);
|
|
inline void reorder(int32_t source, int32_t& target);
|
|
inline void reorder(int64_t source, int64_t& target);
|
|
inline void reorder(uint16_t source, uint16_t& target);
|
|
inline void reorder(uint32_t source, uint32_t& target);
|
|
inline void reorder(uint64_t source, uint64_t& target);</pre>
|
|
<blockquote>
|
|
<p dir="ltr"><i>Effects:</i> Copies <code>source</code> to <code>target</code>,
|
|
reversing the byte order.</p>
|
|
</blockquote>
|
|
<pre dir="ltr">template <class T> void native_to_big(T& x);
|
|
template <class T> void native_to_little(T& x);
|
|
template <class T> void big_to_native(T& x);
|
|
template <class T> void little_to_native(T& x);</pre>
|
|
<blockquote>
|
|
<p dir="ltr"><i>Effects:</i> If the native byte ordering and byte
|
|
ordering indicated by the function name are different, <code>reorder(x)</code>, otherwise no effect.</p>
|
|
<p dir="ltr"><i>Example:</i></p>
|
|
<blockquote>
|
|
<pre>int32_t x = <b><i>some-value</i></b>;
|
|
native_to_big(x); // converts x to big-endian unless
|
|
// the native representation is already big-endian</pre>
|
|
</blockquote>
|
|
</blockquote>
|
|
<pre dir="ltr">template <class T> void native_to_big(T source, T& target);
|
|
template <class T> void native_to_little(T source, T& target);
|
|
template <class T> void big_to_native(T source, T& target);
|
|
template <class T> void little_to_native(T source, T& target);</pre>
|
|
<blockquote>
|
|
<p dir="ltr"><i>Effects:</i> If the native byte ordering and byte
|
|
ordering indicated by the function name are different, <code>reorder(source, target)</code>, otherwise <code>
|
|
target = source</code>.</p>
|
|
<p dir="ltr"><i>Example:</i></p>
|
|
<blockquote>
|
|
<pre>int32_t x;
|
|
<i>... read an external little-endian value into x ...</i>
|
|
int32_t y;
|
|
little_to_native(x, y); // if native ordering is big-endian, reorder(x, y),
|
|
// otherwise y = x</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> |