forked from boostorg/endian
Work-in-progress on endian_buffer docs.
This commit is contained in:
Beman
449
doc/buffers.html
449
doc/buffers.html
@@ -1,4 +1,4 @@
|
||||
<html>
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta http-equiv="Content-Language" content="en-us">
|
||||
@@ -49,20 +49,14 @@
|
||||
<a href="#Limitations">Limitations</a><br>
|
||||
<a href="#Feature-set">Feature set</a><br>
|
||||
<a href="#Types">Enums and typedefs</a><br>
|
||||
<a href="#Class_template_endian">Class template <code>endian</code></a><br>
|
||||
<a href="#Class_template_endian">Class template <code>endian_buffer</code></a><br>
|
||||
|
||||
<a href="#Synopsis">Synopsis</a><br>
|
||||
<a href="#Members">Members</a><br>
|
||||
<a href="#Stream-inserter">Stream inserter</a><br>
|
||||
<a href="#Stream-extractor">Stream extractor</a><br>
|
||||
<a href="#FAQ">FAQ</a><br>
|
||||
<a href="#Design">Design</a><br>
|
||||
<a href="#Experience">Experience</a><br>
|
||||
<a href="#Motivating-use-cases">Motivating use cases</a><br>
|
||||
<a href="#C++0x">C++11</a><br>
|
||||
<a href="#Compilation">Compilation</a><br>
|
||||
<a href="#Acknowledgements">Acknowledgements</a>
|
||||
</td>
|
||||
<a href="#Compilation">Compilation</a></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="100%" bgcolor="#D7EEFF" align="center">
|
||||
@@ -76,58 +70,44 @@
|
||||
</table>
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
<p>Header <a href="buffers.html">boost/endian/buffers.hpp</a>
|
||||
provides integer and floating point binary types with control over
|
||||
byte order, value type, size, and alignment. Typedefs provide easy-to-use names
|
||||
for common configurations.</p>
|
||||
<p>These types provide portable byte-holders for integer data, independent of
|
||||
particular computer architectures. Use cases almost always involve I/O, either via files or
|
||||
network connections. Although data portability is the primary motivation, these
|
||||
integer byte-holders may
|
||||
provides portable integer and floating-point binary buffer types with control over
|
||||
byte order, value type, size, and alignment independent of the native computer
|
||||
architecture. Typedefs provide easy-to-use names
|
||||
for common configurations. Use cases almost always involve I/O, either via files or
|
||||
network connections.</p>
|
||||
<p>Although data portability is the primary motivation, these byte-holders may
|
||||
also be used to reduce memory use, file size, or network activity since they
|
||||
provide binary integer sizes not otherwise available.</p>
|
||||
<p>Such integer byte-holder types are traditionally called <b><i>
|
||||
endian</i></b> types. See the
|
||||
also
|
||||
provide binary numeric sizes not otherwise available.</p>
|
||||
<p>The byte order of arithmetic types is traditionally called <b><i>endianness</i></b>. See the
|
||||
<a href="http://en.wikipedia.org/wiki/Endian" name="endianness">Wikipedia</a> for
|
||||
a full
|
||||
exploration of <b><i>endianness</i></b>, including definitions of <i><b>big
|
||||
endian</b></i> and <i><b>little endian</b></i>.</p>
|
||||
<p>Boost endian integers provide the same full set of C++ assignment,
|
||||
arithmetic, and relational operators as C++ standard integral types, with
|
||||
the standard semantics.</p>
|
||||
<p>Unary arithmetic operators are <code>+</code>, <code>-</code>, <code>~</code>,
|
||||
<code>!</code>, prefix and postfix <code>--</code> and <code>++</code>. Binary
|
||||
arithmetic operators are <code>+</code>, <code>+=</code>, <code>-</code>, <code>
|
||||
-=</code>, <code>*</code>, <code>*=</code>, <code>/</code>, <code>/=</code>,
|
||||
<code>%/ %=</code>, <code>&</code>, <code>&=</code>, <code>|</code>, <code>|=</code>,
|
||||
<code>^</code>, <code>^=</code>, <code><<</code>, <code><<=</code>, <code>>></code>,
|
||||
<code>>>=</code>. Binary relational operators are <code>==</code>, <code>!=</code>,
|
||||
<code><</code>, <code><=</code>, <code>></code>, <code>>=</code>.</p>
|
||||
<p>Automatic implicit conversion to the underlying value type is provided. An
|
||||
conversion constructor from the underlying value type is provided. </p>
|
||||
<h2><a name="Example">Example</a></h2>
|
||||
<p>The <a href="../example/endian_example.cpp">endian_example.cpp</a> program writes a
|
||||
binary file containing four byte big-endian and little-endian integers:</p>
|
||||
<blockquote>
|
||||
<pre>#include <iostream>
|
||||
#include <cstdio>
|
||||
#include <boost/endian/arithmetic.hpp>
|
||||
#include <boost/endian/buffers.hpp>
|
||||
#include <boost/static_assert.hpp>
|
||||
|
||||
using namespace boost::endian;
|
||||
|
||||
namespace
|
||||
{
|
||||
// This is an extract from a very widely used GIS file format. It seems odd
|
||||
// to mix big and little endians in the same file - but this is a real-world
|
||||
// format and users wishing to write low level code manipulating these files
|
||||
// must deal with the mixed endianness.
|
||||
// This is an extract from a very widely used GIS file format. Why the designer
|
||||
// decided to mix big and little endians in the same file is not known. But
|
||||
// this is a real-world format and users wishing to write low level code
|
||||
// manipulating these files have to deal with the mixed endianness.
|
||||
|
||||
struct header
|
||||
{
|
||||
big_int32_t file_code;
|
||||
big_int32_t file_length;
|
||||
little_int32_t version;
|
||||
little_int32_t shape_type;
|
||||
big_int32_<code>buf_</code>t file_code;
|
||||
big_int32_<code>buf_</code>t file_length;
|
||||
little_int32_<code>buf_</code>t version;
|
||||
little_int32_<code>buf_</code>t shape_type;
|
||||
};
|
||||
|
||||
const char* filename = "test.dat";
|
||||
@@ -186,14 +166,14 @@ is some other value, compilation will result in an <code>#error</code>. This
|
||||
restriction is in place because the design, implementation, testing, and
|
||||
documentation has only considered issues related to 8-bit bytes, and there have
|
||||
been no real-world use cases presented for other sizes.</p>
|
||||
<p>In C++03, <code>endian</code> does not meet the requirements for POD types
|
||||
<p>In C++03, <code>endian_buffer</code> does not meet the requirements for POD types
|
||||
because it has constructors, private data members, and a base class. This means
|
||||
that common use cases are relying on unspecified behavior in that the C++
|
||||
Standard does not guarantee memory layout for non-POD types. This has not been a
|
||||
problem in practice since all known C++ compilers do layout memory as if <code>
|
||||
endian</code> were a POD type. In C++11, it is possible to specify the
|
||||
default constructor as trivial, and private data members and base classes will
|
||||
no longer disqualify a type from being a POD. Thus under C++11, <code>endian</code>
|
||||
no longer disqualify a type from being a POD. Thus under C++11, <code>endian_buffer</code>
|
||||
will no longer be relying on unspecified behavior.</p>
|
||||
<h2><a name="Feature-set">Feature set</a></h2>
|
||||
<ul>
|
||||
@@ -213,132 +193,132 @@ enum class align {no, yes}; </pre>
|
||||
</blockquote>
|
||||
<p>One class template is provided:</p>
|
||||
<blockquote>
|
||||
<pre>template <order Order, typename T, std::size_t n_bits, align A = align::no>
|
||||
class endian_arithmetic;
|
||||
<pre>template <order Order, typename T, std::size_t Nbits, align A = align::no>
|
||||
class endian_buffer;
|
||||
</pre>
|
||||
</blockquote>
|
||||
<p>Typedefs, such as <code>big_int32_t</code>, provide convenient naming
|
||||
<p>Typedefs, such as <code>big_int32_buf_t</code>, provide convenient naming
|
||||
conventions for common use cases:</p>
|
||||
<blockquote>
|
||||
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="49%">
|
||||
<tr>
|
||||
<td width="18%" align="center"><b><i>Name</i></b></td>
|
||||
<td width="10%" align="center"><b><i>Endianness</i></b></td>
|
||||
<td width="49%" align="center"><b><i>Alignment</i></b></td>
|
||||
<td width="10%" align="center"><b><i>Sign</i></b></td>
|
||||
<td width="15%" align="center"><b><i>Sizes in bits (n)</i></b></td>
|
||||
<td width="49%" align="center"><b><i>Alignment</i></b></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>big_int</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="18%"><code>big_int</code><i><b>n</b></i><code>_buf_t</code></td>
|
||||
<td width="10%" align="center"><code>big</code></td>
|
||||
<td width="49%" align="center"><code>yes</code></td>
|
||||
<td width="10%" align="center">signed</td>
|
||||
<td width="15%">16,32,64</td>
|
||||
<td width="49%" align="center"><code>yes</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>big_uint</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="18%"><code>big_uint</code><i><b>n</b></i><code>_</code><code>buf_</code><code>t</code></td>
|
||||
<td width="10%" align="center"><code>big</code></td>
|
||||
<td width="49%" align="center"><code>yes</code></td>
|
||||
<td width="10%" align="center">unsigned</td>
|
||||
<td width="15%">16,32,64</td>
|
||||
<td width="49%" align="center"><code>yes</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>big_float</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="18%"><code>big_float</code><i><b>n</b></i><code>_</code><code>buf_</code><code>t</code></td>
|
||||
<td width="10%" align="center"><code>big</code></td>
|
||||
<td width="49%" align="center"><code>yes</code></td>
|
||||
<td width="10%" align="center">signed</td>
|
||||
<td width="15%">32,64</td>
|
||||
<td width="49%" align="center"><code>yes</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>big_int</code><b><i>n</i></b><code>_ut</code></td>
|
||||
<td width="18%"><code>big_int</code><b><i>n</i></b><code>_</code><code>buf_</code><code>ut</code></td>
|
||||
<td width="10%" align="center"><code>big</code></td>
|
||||
<td width="49%" align="center"><code>no</code></td>
|
||||
<td width="10%" align="center">signed</td>
|
||||
<td width="15%">8,16,24,32,40,48,56,64</td>
|
||||
<td width="49%" align="center"><code>no</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>big_uint</code><i><b>n</b></i><code>_ut</code></td>
|
||||
<td width="18%"><code>big_uint</code><i><b>n</b></i><code>_</code><code>buf_</code><code>ut</code></td>
|
||||
<td width="10%" align="center"><code>big</code></td>
|
||||
<td width="49%" align="center"><code>no</code></td>
|
||||
<td width="10%" align="center">unsigned</td>
|
||||
<td width="15%">8,16,24,32,40,48,56,64</td>
|
||||
<td width="49%" align="center"><code>no</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>big_float</code><i><b>n</b></i><code>_ut</code></td>
|
||||
<td width="18%"><code>big_float</code><i><b>n</b></i><code>_</code><code>buf_</code><code>ut</code></td>
|
||||
<td width="10%" align="center"><code>big</code></td>
|
||||
<td width="49%" align="center"><code>no</code></td>
|
||||
<td width="10%" align="center">signed</td>
|
||||
<td width="15%">32,64</td>
|
||||
<td width="49%" align="center"><code>no</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>little_int</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="18%"><code>little_int</code><i><b>n</b></i><code>_</code><code>buf_</code><code>t</code></td>
|
||||
<td width="10%" align="center"><code>little</code></td>
|
||||
<td width="49%" align="center"><code>yes</code></td>
|
||||
<td width="10%" align="center">signed</td>
|
||||
<td width="15%">16,32,64</td>
|
||||
<td width="49%" align="center"><code>yes</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>little_uint</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="18%"><code>little_uint</code><i><b>n</b></i><code>_</code><code>buf_</code><code>t</code></td>
|
||||
<td width="10%" align="center"><code>little</code></td>
|
||||
<td width="49%" align="center"><code>yes</code></td>
|
||||
<td width="10%" align="center">unsigned</td>
|
||||
<td width="15%">16,32,64</td>
|
||||
<td width="49%" align="center"><code>yes</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>little_float</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="18%"><code>little_float</code><i><b>n</b></i><code>_</code><code>buf_</code><code>t</code></td>
|
||||
<td width="10%" align="center"><code>little</code></td>
|
||||
<td width="49%" align="center"><code>yes</code></td>
|
||||
<td width="10%" align="center">signed</td>
|
||||
<td width="15%">32,64</td>
|
||||
<td width="49%" align="center"><code>yes</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>little_int</code><i><b>n</b></i><code>_ut</code></td>
|
||||
<td width="18%"><code>little_int</code><i><b>n</b></i><code>_</code><code>buf_</code><code>ut</code></td>
|
||||
<td width="10%" align="center"><code>little</code></td>
|
||||
<td width="49%" align="center"><code>no</code></td>
|
||||
<td width="10%" align="center">signed</td>
|
||||
<td width="15%">8,16,24,32,40,48,56,64</td>
|
||||
<td width="49%" align="center"><code>no</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>little_uint</code><i><b>n</b></i><code>_ut</code></td>
|
||||
<td width="18%"><code>little_uint</code><i><b>n</b></i><code>_</code><code>buf_</code><code>ut</code></td>
|
||||
<td width="10%" align="center"><code>little</code></td>
|
||||
<td width="49%" align="center"><code>no</code></td>
|
||||
<td width="10%" align="center">unsigned</td>
|
||||
<td width="15%">8,16,24,32,40,48,56,64</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>little_float</code><i><b>n</b></i><code>_ut</code></td>
|
||||
<td width="10%" align="center"><code>little</code></td>
|
||||
<td width="49%" align="center"><code>no</code></td>
|
||||
<td width="10%" align="center">signed</td>
|
||||
<td width="15%">32,64</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>native_float</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="10%" align="center"><code>native</code></td>
|
||||
<td width="49%" align="center"><code>yes</code></td>
|
||||
<td width="18%"><code>little_float</code><i><b>n</b></i><code>_</code><code>buf_</code><code>ut</code></td>
|
||||
<td width="10%" align="center"><code>little</code></td>
|
||||
<td width="10%" align="center">signed</td>
|
||||
<td width="15%">32,64</td>
|
||||
<td width="49%" align="center"><code>no</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>native_float</code><i><b>n</b></i><code>_</code><code>buf_</code><code>t</code></td>
|
||||
<td width="10%" align="center"><code>native</code></td>
|
||||
<td width="10%" align="center">signed</td>
|
||||
<td width="15%">32,64</td>
|
||||
<td width="49%" align="center"><code>yes</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>native_int</code><i><b>n</b></i><code>_ut</code></td>
|
||||
<td width="18%"><code>native_int</code><i><b>n</b></i><code>_</code><code>buf_</code><code>ut</code></td>
|
||||
<td width="10%" align="center"><code>native</code></td>
|
||||
<td width="49%" align="center"><code>no</code></td>
|
||||
<td width="10%" align="center">signed</td>
|
||||
<td width="15%">8,16,24,32,40,48,56,64</td>
|
||||
<td width="49%" align="center"><code>no</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>native_uint</code><i><b>n</b></i><code>_ut</code></td>
|
||||
<td width="18%"><code>native_uint</code><i><b>n</b></i><code>_</code><code>buf_</code><code>ut</code></td>
|
||||
<td width="10%" align="center"><code>native</code></td>
|
||||
<td width="49%" align="center"><code>no</code></td>
|
||||
<td width="10%" align="center">unsigned</td>
|
||||
<td width="15%">8,16,24,32,40,48,56,64</td>
|
||||
<td width="49%" align="center"><code>no</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>native_float</code><i><b>n</b></i><code>_ut</code></td>
|
||||
<td width="18%"><code>native_float</code><i><b>n</b></i><code>_</code><code>buf_</code><code>ut</code></td>
|
||||
<td width="10%" align="center"><code>native</code></td>
|
||||
<td width="49%" align="center"><code>no</code></td>
|
||||
<td width="10%" align="center">signed</td>
|
||||
<td width="15%">32,64</td>
|
||||
<td width="49%" align="center"><code>no</code></td>
|
||||
</tr>
|
||||
</table>
|
||||
</blockquote>
|
||||
@@ -354,8 +334,8 @@ are only available on architectures with 16, 32, and 64-bit integer types. </p>
|
||||
<p><b><i>Note:</i></b> One-byte types
|
||||
have identical
|
||||
functionality. They are provided to improve code readability and searchability.</p>
|
||||
<h2><a name="Class_template_endian">Class template <code>endian</code></a><code>_arithmetic</code></h2>
|
||||
<p>An endian is an integer byte-holder with user-specified <a href="#endianness">
|
||||
<h2><a name="Class_template_endian">Class template <code>endian</code></a><code>_buffer</code></h2>
|
||||
<p>An <code>endian_buffer</code> is an integer byte-holder with user-specified <a href="#endianness">
|
||||
endianness</a>, value type, size, and <a href="#alignment">alignment</a>. The
|
||||
usual operations on integers are supplied.</p>
|
||||
<h3><a name="Synopsis">Synopsis</a></h3>
|
||||
@@ -374,178 +354,162 @@ usual operations on integers are supplied.</p>
|
||||
|
||||
enum class <a name="alignment">align</a> {no, yes};
|
||||
|
||||
template <order Order, class T, std::size_t n_bits, align A = align::no>
|
||||
class endian
|
||||
template <order Order, class T, std::size_t Nbits, align Align = align::no>
|
||||
class endian_buffer
|
||||
{
|
||||
public:
|
||||
typedef T value_type;
|
||||
|
||||
// if BOOST_ENDIAN_FORCE_PODNESS is defined && C++11 POD's are not
|
||||
// available then these two constructors will not be present
|
||||
<a href="#endian">endian</a>() noexcept = default;
|
||||
<a href="#explicit-endian">endian</a>(T v) noexcept;
|
||||
<a href="#endian">endian_buffer</a>() noexcept = default;
|
||||
explicit <a href="#explicit-endian">endian_buffer</a>(T v) noexcept;
|
||||
|
||||
endian& <a href="#operator-eq">operator=</a>(T v) noexcept;
|
||||
<a href="#operator-T">operator T</a>() const noexcept;
|
||||
const char* <a href="#data">data</a>() const noexcept;
|
||||
|
||||
// arithmetic operations
|
||||
// note that additional operations are provided by the value_type
|
||||
value_type operator+(const endian& x) noexcept;
|
||||
endian& operator+=(endian& x, value_type y) noexcept;
|
||||
endian& operator-=(endian& x, value_type y) noexcept;
|
||||
endian& operator*=(endian& x, value_type y) noexcept;
|
||||
endian& operator/=(endian& x, value_type y) noexcept;
|
||||
endian& operator%=(endian& x, value_type y) noexcept;
|
||||
endian& operator&=(endian& x, value_type y) noexcept;
|
||||
endian& operator|=(endian& x, value_type y) noexcept;
|
||||
endian& operator^=(endian& x, value_type y) noexcept;
|
||||
endian& operator<<=(endian& x, value_type y) noexcept;
|
||||
endian& operator>>=(endian& x, value_type y noexcept;
|
||||
value_type operator<<(const endian& x, value_type y) noexcept;
|
||||
value_type operator>>(const endian& x, value_type y) noexcept;
|
||||
endian& operator++(endian& x) noexcept;
|
||||
endian& operator--(endian& x) noexcept;
|
||||
endian operator++(endian& x, int) noexcept;
|
||||
endian operator--(endian& x, int) noexcept;
|
||||
|
||||
// Stream inserter
|
||||
template <class charT, class traits>
|
||||
friend std::basic_ostream<charT, traits>&
|
||||
operator<<(std::basic_ostream<charT, traits>& os, const T& x);
|
||||
|
||||
// Stream extractor
|
||||
template <class charT, class traits>
|
||||
friend std::basic_istream<charT, traits>&
|
||||
operator>>(std::basic_istream<charT, traits>& is, T& x);
|
||||
endian_buffer& <a href="#operator-eq">operator=</a>(T v) noexcept;
|
||||
value_type value() const noexcept;
|
||||
const char* <a href="#data">data</a>() const noexcept;
|
||||
protected:
|
||||
<b><i>implementaton-defined</i></b> endian_value; // for exposition only
|
||||
};
|
||||
|
||||
// typedefs
|
||||
|
||||
// aligned big endian floating point types
|
||||
typedef endian<order::big, float, 32, align::yes> big_float32_t;
|
||||
typedef endian<order::big, double, 64, align::yes> big_float64_t;
|
||||
// aligned big endian floating point buffers
|
||||
typedef endian_buffer<order::big, float, 32, align::yes> big_float32_buf_t;
|
||||
typedef endian_buffer<order::big, double, 64, align::yes> big_float64_buf_t;
|
||||
|
||||
// aligned little endian floating point types
|
||||
typedef endian<order::little, float, 32, align::yes> little_float32_t;
|
||||
typedef endian<order::little, double, 64, align::yes> little_float64_t;
|
||||
// aligned little endian floating point buffers
|
||||
typedef endian_buffer<order::little, float, 32, align::yes> little_float32_buf_t;
|
||||
typedef endian_buffer<order::little, double, 64, align::yes> little_float64_buf_t;
|
||||
|
||||
// unaligned big endian floating point types
|
||||
typedef endian<order::big, float, 32, align::no> big_float32un_t;
|
||||
typedef endian<order::big, double, 64, align::no> big_float64un_t;
|
||||
// unaligned big endian floating point buffers
|
||||
typedef endian_buffer<order::big, float, 32, align::no> big_float32_buf_ut;
|
||||
typedef endian_buffer<order::big, double, 64, align::no> big_float64_buf_ut;
|
||||
|
||||
// unaligned little endian floating point types
|
||||
typedef endian<order::little, float, 32, align::no> little_float32un_t;
|
||||
typedef endian<order::little, double, 64, align::no> little_float64un_t;
|
||||
// unaligned little endian floating point buffers
|
||||
typedef endian_buffer<order::little, float, 32, align::no> little_float32_buf_ut;
|
||||
typedef endian_buffer<order::little, double, 64, align::no> little_float64_buf_ut;
|
||||
|
||||
// aligned big endian signed integer types
|
||||
typedef endian<order::big, int16_t, 16, align::yes> big_int16_t;
|
||||
typedef endian<order::big, int32_t, 32, align::yes> big_int32_t;
|
||||
typedef endian<order::big, int64_t, 64, align::yes> big_int64_t;
|
||||
// aligned big endian signed integer buffers
|
||||
typedef endian_buffer<order::big, int16_t, 16, align::yes> big_int16_buf_t;
|
||||
typedef endian_buffer<order::big, int32_t, 32, align::yes> big_int32_buf_t;
|
||||
typedef endian_buffer<order::big, int64_t, 64, align::yes> big_int64_buf_t;
|
||||
|
||||
// aligned big endian unsigned integer types
|
||||
typedef endian<order::big, uint16_t, 16, align::yes> big_uint16_t;
|
||||
typedef endian<order::big, uint32_t, 32, align::yes> big_uint32_t;
|
||||
typedef endian<order::big, uint64_t, 64, align::yes> big_uint64_t;
|
||||
// aligned big endian unsigned integer buffers
|
||||
typedef endian_buffer<order::big, uint16_t, 16, align::yes> big_uint16_buf_t;
|
||||
typedef endian_buffer<order::big, uint32_t, 32, align::yes> big_uint32_buf_t;
|
||||
typedef endian_buffer<order::big, uint64_t, 64, align::yes> big_uint64_buf_t;
|
||||
|
||||
// aligned little endian signed integer types
|
||||
typedef endian<order::little, int16_t, 16, align::yes> little_int16_t;
|
||||
typedef endian<order::little, int32_t, 32, align::yes> little_int32_t;
|
||||
typedef endian<order::little, int64_t, 64, align::yes> little_int64_t;
|
||||
// aligned little endian signed integer buffers
|
||||
typedef endian_buffer<order::little, int16_t, 16, align::yes> little_int16_buf_t;
|
||||
typedef endian_buffer<order::little, int32_t, 32, align::yes> little_int32_buf_t;
|
||||
typedef endian_buffer<order::little, int64_t, 64, align::yes> little_int64_buf_t;
|
||||
|
||||
// aligned little endian unsigned integer types
|
||||
typedef endian<order::little, uint16_t, 16, align::yes> little_uint16_t;
|
||||
typedef endian<order::little, uint32_t, 32, align::yes> little_uint32_t;
|
||||
typedef endian<order::little, uint64_t, 64, align::yes> little_uint64_t;
|
||||
// aligned little endian unsigned integer buffers
|
||||
typedef endian_buffer<order::little, uint16_t, 16, align::yes> little_uint16_buf_t;
|
||||
typedef endian_buffer<order::little, uint32_t, 32, align::yes> little_uint32_buf_t;
|
||||
typedef endian_buffer<order::little, uint64_t, 64, align::yes> little_uint64_buf_t;
|
||||
|
||||
// aligned native endian typedefs are not provided because
|
||||
// <cstdint> types are superior for that use case
|
||||
// <cstdint> types are superior for this use case
|
||||
|
||||
// unaligned big endian signed integer types
|
||||
typedef endian<order::big, int_least8_t, 8> big_int8_ut;
|
||||
typedef endian<order::big, int_least16_t, 16> big_int16_ut;
|
||||
typedef endian<order::big, int_least32_t, 24> big_int24_ut;
|
||||
typedef endian<order::big, int_least32_t, 32> big_int32_ut;
|
||||
typedef endian<order::big, int_least64_t, 40> big_int40_ut;
|
||||
typedef endian<order::big, int_least64_t, 48> big_int48_ut;
|
||||
typedef endian<order::big, int_least64_t, 56> big_int56_ut;
|
||||
typedef endian<order::big, int_least64_t, 64> big_int64_ut;
|
||||
// unaligned big endian signed integer buffers
|
||||
typedef endian_buffer<order::big, int_least8_t, 8> big_int8_buf_ut;
|
||||
typedef endian_buffer<order::big, int_least16_t, 16> big_int16_buf_ut;
|
||||
typedef endian_buffer<order::big, int_least32_t, 24> big_int24_buf_ut;
|
||||
typedef endian_buffer<order::big, int_least32_t, 32> big_int32_buf_ut;
|
||||
typedef endian_buffer<order::big, int_least64_t, 40> big_int40_buf_ut;
|
||||
typedef endian_buffer<order::big, int_least64_t, 48> big_int48_buf_ut;
|
||||
typedef endian_buffer<order::big, int_least64_t, 56> big_int56_buf_ut;
|
||||
typedef endian_buffer<order::big, int_least64_t, 64> big_int64_buf_ut;
|
||||
|
||||
// unaligned big endian unsigned integer types
|
||||
typedef endian<order::big, uint_least8_t, 8> big_uint8_ut;
|
||||
typedef endian<order::big, uint_least16_t, 16> big_uint16_ut;
|
||||
typedef endian<order::big, uint_least32_t, 24> big_uint24_ut;
|
||||
typedef endian<order::big, uint_least32_t, 32> big_uint32_ut;
|
||||
typedef endian<order::big, uint_least64_t, 40> big_uint40_ut;
|
||||
typedef endian<order::big, uint_least64_t, 48> big_uint48_ut;
|
||||
typedef endian<order::big, uint_least64_t, 56> big_uint56_ut;
|
||||
typedef endian<order::big, uint_least64_t, 64> big_uint64_ut;
|
||||
// unaligned big endian unsigned integer buffers
|
||||
typedef endian_buffer<order::big, uint_least8_t, 8> big_uint8_buf_ut;
|
||||
typedef endian_buffer<order::big, uint_least16_t, 16> big_uint16_buf_ut;
|
||||
typedef endian_buffer<order::big, uint_least32_t, 24> big_uint24_buf_ut;
|
||||
typedef endian_buffer<order::big, uint_least32_t, 32> big_uint32_buf_ut;
|
||||
typedef endian_buffer<order::big, uint_least64_t, 40> big_uint40_buf_ut;
|
||||
typedef endian_buffer<order::big, uint_least64_t, 48> big_uint48_buf_ut;
|
||||
typedef endian_buffer<order::big, uint_least64_t, 56> big_uint56_buf_ut;
|
||||
typedef endian_buffer<order::big, uint_least64_t, 64> big_uint64_buf_ut;
|
||||
|
||||
// unaligned little endian signed integer types
|
||||
typedef endian<order::little, int_least8_t, 8> little_int8_ut;
|
||||
typedef endian<order::little, int_least16_t, 16> little_int16_ut;
|
||||
typedef endian<order::little, int_least32_t, 24> little_int24_ut;
|
||||
typedef endian<order::little, int_least32_t, 32> little_int32_ut;
|
||||
typedef endian<order::little, int_least64_t, 40> little_int40_ut;
|
||||
typedef endian<order::little, int_least64_t, 48> little_int48_ut;
|
||||
typedef endian<order::little, int_least64_t, 56> little_int56_ut;
|
||||
typedef endian<order::little, int_least64_t, 64> little_int64_ut;
|
||||
// unaligned little endian signed integer buffers
|
||||
typedef endian_buffer<order::little, int_least8_t, 8> little_int8_buf_ut;
|
||||
typedef endian_buffer<order::little, int_least16_t, 16> little_int16_buf_ut;
|
||||
typedef endian_buffer<order::little, int_least32_t, 24> little_int24_buf_ut;
|
||||
typedef endian_buffer<order::little, int_least32_t, 32> little_int32_buf_ut;
|
||||
typedef endian_buffer<order::little, int_least64_t, 40> little_int40_buf_ut;
|
||||
typedef endian_buffer<order::little, int_least64_t, 48> little_int48_buf_ut;
|
||||
typedef endian_buffer<order::little, int_least64_t, 56> little_int56_buf_ut;
|
||||
typedef endian_buffer<order::little, int_least64_t, 64> little_int64_buf_ut;
|
||||
|
||||
// unaligned little endian unsigned integer types
|
||||
typedef endian<order::little, uint_least8_t, 8> little_uint8_ut;
|
||||
typedef endian<order::little, uint_least16_t, 16> little_uint16_ut;
|
||||
typedef endian<order::little, uint_least32_t, 24> little_uint24_ut;
|
||||
typedef endian<order::little, uint_least32_t, 32> little_uint32_ut;
|
||||
typedef endian<order::little, uint_least64_t, 40> little_uint40_ut;
|
||||
typedef endian<order::little, uint_least64_t, 48> little_uint48_ut;
|
||||
typedef endian<order::little, uint_least64_t, 56> little_uint56_ut;
|
||||
typedef endian<order::little, uint_least64_t, 64> little_uint64_ut;
|
||||
// unaligned little endian unsigned integer buffers
|
||||
typedef endian_buffer<order::little, uint_least8_t, 8> little_uint8_buf_ut;
|
||||
typedef endian_buffer<order::little, uint_least16_t, 16> little_uint16_buf_ut;
|
||||
typedef endian_buffer<order::little, uint_least32_t, 24> little_uint24_buf_ut;
|
||||
typedef endian_buffer<order::little, uint_least32_t, 32> little_uint32_buf_ut;
|
||||
typedef endian_buffer<order::little, uint_least64_t, 40> little_uint40_buf_ut;
|
||||
typedef endian_buffer<order::little, uint_least64_t, 48> little_uint48_buf_ut;
|
||||
typedef endian_buffer<order::little, uint_least64_t, 56> little_uint56_buf_ut;
|
||||
typedef endian_buffer<order::little, uint_least64_t, 64> little_uint64_buf_ut;
|
||||
|
||||
// unaligned native endian signed integer types
|
||||
typedef <b><i>implementation-defined</i></b>_int8_t native_int8_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_int16_t native_int16_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_int24_t native_int24_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_int32_t native_int32_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_int40_t native_int40_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_int48_t native_int48_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_int56_t native_int56_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_int64_t native_int64_ut;
|
||||
// unaligned native endian signed integer types
|
||||
typedef <b><i>implementation-defined</i></b>_int8_buf_ut native_int8_buf_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_int16_buf_ut native_int16_buf_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_int24_buf_ut native_int24_buf_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_int32_buf_ut native_int32_buf_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_int40_buf_ut native_int40_buf_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_int48_buf_ut native_int48_buf_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_int56_buf_ut native_int56_buf_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_int64_buf_ut native_int64_buf_ut;
|
||||
|
||||
// unaligned native endian unsigned integer types
|
||||
typedef <b><i>implementation-defined</i></b>_uint8_buf_ut native_uint8_buf_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_uint16_buf_ut native_uint16_buf_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_uint24_buf_ut native_uint24_buf_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_uint32_buf_ut native_uint32_buf_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_uint40_buf_ut native_uint40_buf_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_uint48_buf_ut native_uint48_buf_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_uint56_buf_ut native_uint56_buf_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_uint64_buf_ut native_uint64_buf_ut;
|
||||
|
||||
// unaligned native endian unsigned integer types
|
||||
typedef <b><i>implementation-defined</i></b>_uint8_t native_uint8_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_uint16_t native_uint16_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_uint24_t native_uint24_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_uint32_t native_uint32_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_uint40_t native_uint40_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_uint48_t native_uint48_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_uint56_t native_uint56_ut;
|
||||
typedef <b><i>implementation-defined</i></b>_uint64_t native_uint64_ut;
|
||||
|
||||
} // namespace endian
|
||||
} // namespace boost</pre>
|
||||
<p>The <i><b><code>implementation-defined</code></b></i> text above is either
|
||||
<code>big</code> or <code>little</code> according to the endianness of the
|
||||
<p>The <i><b><code>implementation-defined</code></b></i> text in typedefs above is either
|
||||
<code>big</code> or <code>little</code> according to the native endianness of the
|
||||
platform.</p>
|
||||
<p>The expository data member <code>endian_value</code> stores the current value
|
||||
of an <code>endian_value</code> object as a sequence of bytes ordered as
|
||||
specified by the <code>Order</code> template parameter. The <i><b><code>
|
||||
implementation-defined</code></b></i> type of <code>endian_value</code> is a
|
||||
type such as <code><span style="font-size: 85%">char[Nbits/CHAR_BIT]</span></code>
|
||||
or <code><span style="font-size: 85%">T</span></code> that meets the
|
||||
requirements imposed by the <code>Nbits</code> and <code>Align</code> template
|
||||
parameters. The <code><span style="font-size: 85%">CHAR_BIT</span></code>
|
||||
macro is defined in <code><span style="font-size: 85%"><climits></span></code>.
|
||||
The only value of <code><span style="font-size: 85%">CHAR_BIT</span></code> that
|
||||
is required to be supported is 8. </p>
|
||||
<h3><a name="Members">Members</a></h3>
|
||||
<div dir="ltr">
|
||||
<pre><code><a name="endian">endian</a>() = default; // C++03: endian(){}</code></pre>
|
||||
<pre><code><a name="endian">endian</a>_buffer() = default; // C++03: endian(){}</code></pre>
|
||||
</div>
|
||||
<blockquote>
|
||||
<p><i>Effects:</i> Constructs an object of type <code>endian<E, T, n_bits, A></code>.</p>
|
||||
<p><i>Effects:</i> Constructs an object of type <code>endian_buffer<Order, T,
|
||||
Nbits, Align></code>.</p>
|
||||
</blockquote>
|
||||
<pre><code><a name="explicit-endian">endian</a>(T v);</code></pre>
|
||||
<pre><code>explicit <a name="explicit-endian">endian</a>_buffer(T v);</code></pre>
|
||||
<blockquote>
|
||||
<p><i>Effects:</i> Constructs an object of type <code>endian<E, T, n_bits, A></code>.</p>
|
||||
<p><i>Postcondition:</i> <code>x == v,</code> where <code>x</code> is the
|
||||
constructed object.</p>
|
||||
<p><i>Effects:</i> Constructs an object of type <code>endian_buffer<Order, T,
|
||||
Nbits, Align></code>.</p>
|
||||
<p><i>Postcondition:</i> <code>value() == v</code>.</p>
|
||||
</blockquote>
|
||||
<pre><code>endian& <a name="operator-eq">operator=</a>(T v);</code></pre>
|
||||
<pre><code>endian_buffer& <a name="operator-eq">operator=</a>(T v);</code></pre>
|
||||
<blockquote>
|
||||
<p><i>Postcondition:</i> <code>x == v,</code> where <code>x</code> is the
|
||||
constructed object.</p>
|
||||
<p><i>Postcondition:</i> <code>value() == v</code>.</p>
|
||||
<p><i>Returns:</i> <code>*this</code>.</p>
|
||||
</blockquote>
|
||||
<pre><code><a name="operator-T">operator T</a>() const;</code></pre>
|
||||
<pre>value_type <a name="value">value</a>()<code> const;</code></pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> The current value stored in <code>*this</code>, converted to
|
||||
<code>value_type</code>.</p>
|
||||
@@ -555,32 +519,6 @@ constructed object.</p>
|
||||
<p><i>Returns:</i> A pointer to the first byte of the endian binary value stored
|
||||
in <code>*this</code>.</p>
|
||||
</blockquote>
|
||||
<h3>Other operators</h3>
|
||||
<p>Other operators on endian objects are forwarded to the equivalent
|
||||
operator on <code>value_type</code>.</p>
|
||||
<h3><a name="Stream-inserter">Stream inserter</a></h3>
|
||||
<pre>template <class charT, class traits>
|
||||
friend std::basic_ostream<charT, traits>&
|
||||
operator<<(std::basic_ostream<charT, traits>& os, const T& x);
|
||||
</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>os << +x</code>.</p>
|
||||
</blockquote>
|
||||
<h3><a name="Stream-extractor">Stream extractor</a></h3>
|
||||
<pre>template <class charT, class traits>
|
||||
friend std::basic_istream<charT, traits>&
|
||||
operator>>(std::basic_istream<charT, traits>& is, T& x);
|
||||
</pre>
|
||||
<blockquote>
|
||||
<p><i>Effects: </i>As if:</p>
|
||||
<blockquote>
|
||||
<pre>T i;
|
||||
if (is >> i)
|
||||
x = i;
|
||||
</pre>
|
||||
</blockquote>
|
||||
<p><i>Returns: </i><code>is</code><i>.</i></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
|
||||
@@ -614,7 +552,7 @@ incrementing a variable in a record. It is very convenient to write:</p>
|
||||
<pre wrap> int temp(record.foo);
|
||||
++temp;
|
||||
record.foo = temp;</pre>
|
||||
<h2><a name="Design">Design</a> considerations for Boost.Endian types</h2>
|
||||
<h2><a name="Design">Design</a> considerations for Boost.Endian buffers</h2>
|
||||
<ul>
|
||||
<li>Must be suitable for I/O - in other words, must be memcpyable.</li>
|
||||
<li>Must provide exactly the size and internal byte ordering specified.</li>
|
||||
@@ -633,17 +571,6 @@ incrementing a variable in a record. It is very convenient to write:</p>
|
||||
machines or compilers. Pessimizations can also happen when changing compiler switches,
|
||||
compiler versions, or CPU models of the same architecture.</li>
|
||||
</ul>
|
||||
<h2><a name="Experience">Experience</a></h2>
|
||||
<p>Classes with similar functionality have been independently developed by
|
||||
several Boost programmers and used very successful in high-value, high-use
|
||||
applications for many years. These independently developed endian libraries
|
||||
often evolved from C libraries that were also widely used. Endian types have proven widely useful across a wide
|
||||
range of computer architectures and applications.</p>
|
||||
<h2><a name="Motivating-use-cases">Motivating use cases</a></h2>
|
||||
<p>Neil Mayhew writes: "I can also provide a meaningful use-case for this
|
||||
library: reading TrueType font files from disk and processing the contents. The
|
||||
data format has fixed endianness (big) and has unaligned values in various
|
||||
places. Using Boost.Endian simplifies and cleans the code wonderfully."</p>
|
||||
<h2><a name="C++0x">C++11</a></h2>
|
||||
<p>The availability of the C++11
|
||||
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">
|
||||
@@ -668,17 +595,9 @@ any Boost object libraries.</p>
|
||||
In C++11, <code>class endian</code> objects are POD's even though they have
|
||||
constructors.</li>
|
||||
</ul>
|
||||
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
|
||||
<p>Original design developed by Darin Adler based on classes developed by Mark
|
||||
Borgerding. Four original class templates combined into a single <code>endian</code>
|
||||
class template by Beman Dawes, who put the library together, provided
|
||||
documentation, added the typedefs, and also added the <code>unrolled_byte_loops</code>
|
||||
sign partial specialization to correctly extend the sign when cover integer size
|
||||
differs from endian representation size. Vicente Botet and other reviewers
|
||||
suggested supporting floating point types.</p>
|
||||
<hr>
|
||||
<p>Last revised:
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->27 November, 2014<!--webbot bot="Timestamp" endspan i-checksum="39496" --></p>
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38642" --></p>
|
||||
<p>© Copyright Beman Dawes, 2006-2009, 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>
|
||||
|
||||
Reference in New Issue
Block a user