forked from boostorg/endian
copy from develop
This commit is contained in:
Beman
@@ -1,4 +1,4 @@
|
||||
<html>
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta http-equiv="Content-Language" content="en-us">
|
||||
@@ -17,7 +17,7 @@
|
||||
<tr>
|
||||
<td>
|
||||
<a href="../../../index.html">
|
||||
<img src="http://www.boost.org/boost.png" alt="Boost logo" align="middle" border="0" width="277" height="86"></a></td>
|
||||
<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 Arithmetic Types</font> </b>
|
||||
@@ -27,11 +27,12 @@
|
||||
|
||||
<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>
|
||||
<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></b></td>
|
||||
<a href="buffers.html">Buffer Types</a>
|
||||
<a href="choosing_approach.html">Choosing Approach</a></b></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
@@ -64,17 +65,7 @@
|
||||
<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="../include/boost/endian/conversion.hpp"><boost/endian/conversion.hpp></a><br>
|
||||
<a href="../include/boost/endian/buffers.hpp"><boost/endian/buffers.hpp></a><br>
|
||||
<a href="../include/boost/endian/arithmetic.hpp"><boost/endian/arithmetic.hpp></a></td>
|
||||
</tr>
|
||||
</table>
|
||||
</table>
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
<p>Header <a href="arithmetic.html">boost/endian/arithmetic.hpp</a>
|
||||
provides integer and floating point binary types with control over
|
||||
@@ -118,10 +109,11 @@ 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
|
||||
{
|
||||
@@ -145,11 +137,13 @@ int main(int, char* [])
|
||||
h.version = 1;
|
||||
h.shape_type = 0x01020304;
|
||||
|
||||
// Low-level I/O such as POSIX read/write or <cstdio> fread/fwrite is sometimes
|
||||
// used for binary file operations when ultimate efficiency is important. Such
|
||||
// I/O is often performed in some C++ wrapper class, but to drive home the
|
||||
// point that endian integers are often used in fairly low-level code that does
|
||||
// bulk I/O operations, <cstdio> fopen/fwrite is used for I/O in this example.
|
||||
// Low-level I/O such as POSIX read/write or <cstdio>
|
||||
// fread/fwrite is sometimes used for binary file operations
|
||||
// when ultimate efficiency is important. Such I/O is often
|
||||
// performed in some C++ wrapper class, but to drive home the
|
||||
// point that endian integers are often used in fairly
|
||||
// low-level code that does bulk I/O operations, <cstdio>
|
||||
// fopen/fwrite is used for I/O in this example.
|
||||
|
||||
std::FILE* fi = std::fopen(filename, "wb"); // MUST BE BINARY
|
||||
|
||||
@@ -214,8 +208,9 @@ 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 n_bits,
|
||||
align Align = align::no>
|
||||
class endian_arithmetic;
|
||||
</pre>
|
||||
</blockquote>
|
||||
<p>Typedefs, such as <code>big_int32_t</code>, provide convenient naming
|
||||
@@ -375,9 +370,10 @@ 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>
|
||||
template <order Order, class T, std::size_t n_bits,
|
||||
align Align = align::no>
|
||||
class endian_arithmetic
|
||||
: public endian_buffer<Order, T, n_bits, A>
|
||||
: public endian_buffer<Order, T, n_bits, Align>
|
||||
{
|
||||
public:
|
||||
typedef T value_type;
|
||||
@@ -389,8 +385,8 @@ usual operations on integers are supplied.</p>
|
||||
|
||||
endian_arithmetic& <a href="#operator-eq">operator=</a>(T v) noexcept;
|
||||
<a href="#operator-T">operator value_type</a>() const noexcept;
|
||||
value_type value() const noexcept; // exposition only; see endian_buffer
|
||||
const char* <a href="#data">data</a>() const noexcept; // exposition only; see endian_buffer
|
||||
value_type value() const noexcept; // for exposition; see endian_buffer
|
||||
const char* <a href="#data">data</a>() const noexcept; // for exposition; see endian_buffer
|
||||
|
||||
// arithmetic operations
|
||||
// note that additional operations are provided by the value_type
|
||||
@@ -426,35 +422,35 @@ usual operations on integers are supplied.</p>
|
||||
// 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;
|
||||
typedef endian<order::big, float, 32, align::yes> big_float32_t;
|
||||
typedef endian<order::big, double, 64, align::yes> big_float64_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;
|
||||
typedef endian<order::little, float, 32, align::yes> little_float32_t;
|
||||
typedef endian<order::little, double, 64, align::yes> little_float64_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;
|
||||
typedef endian<order::big, float, 32, align::no> big_float32_ut;
|
||||
typedef endian<order::big, double, 64, align::no> big_float64_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;
|
||||
typedef endian<order::little, float, 32, align::no> little_float32_ut;
|
||||
typedef endian<order::little, double, 64, align::no> little_float64_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;
|
||||
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 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;
|
||||
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 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;
|
||||
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 unsigned integer types
|
||||
typedef endian<order::little, uint16_t, 16, align::yes> little_uint16_t;
|
||||
@@ -681,7 +677,7 @@ 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 -->05 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38642" --></p>
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->19 January, 2015<!--webbot bot="Timestamp" endspan i-checksum="38903" --></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>
|
||||
|
||||
103
buffers.html
103
buffers.html
@@ -1,4 +1,4 @@
|
||||
<html>
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta http-equiv="Content-Language" content="en-us">
|
||||
@@ -17,7 +17,7 @@
|
||||
<tr>
|
||||
<td>
|
||||
<a href="../../../index.html">
|
||||
<img src="http://www.boost.org/boost.png" alt="Boost logo" align="middle" border="0" width="277" height="86"></a></td>
|
||||
<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 Buffer Types</font> </b>
|
||||
@@ -27,11 +27,12 @@
|
||||
|
||||
<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>
|
||||
<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></b></td>
|
||||
<a href="buffers.html">Buffer Types</a>
|
||||
<a href="choosing_approach.html">Choosing Approach</a></b></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
@@ -53,30 +54,20 @@
|
||||
|
||||
<a href="#Synopsis">Synopsis</a><br>
|
||||
<a href="#Members">Members</a><br>
|
||||
<a href="#Non-member-functions">Non-Members</a><br>
|
||||
<a href="#FAQ">FAQ</a><br>
|
||||
<a href="#Design">Design</a><br>
|
||||
<a href="#C++0x">C++11</a><br>
|
||||
<a href="#Compilation">Compilation</a></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="100%" bgcolor="#D7EEFF" align="center">
|
||||
<b><i>Headers</i></b></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="100%" bgcolor="#E8F5FF">
|
||||
<p dir="ltr">
|
||||
<a href="../include/boost/endian/conversion.hpp"><boost/endian/conversion.hpp></a><br>
|
||||
<a href="../include/boost/endian/buffers.hpp"><boost/endian/buffers.hpp></a><br>
|
||||
<a href="../include/boost/endian/arithmetic.hpp"><boost/endian/arithmetic.hpp></a></td>
|
||||
</tr>
|
||||
</table>
|
||||
</table>
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
<p>The internal 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>Header <a href="buffers.html">boost/endian/buffers.hpp</a>
|
||||
<p>Header <b><code>boost/endian/buffers.hpp</code></b>
|
||||
provides <code>endian_buffer</code>, a portable endian integer and floating-point binary buffer
|
||||
class template with control over
|
||||
byte order, value type, size, and alignment independent of the platform's native
|
||||
@@ -93,22 +84,23 @@ base class for the <code><a href="arithmetic.html">endian_arithmetic</a></code>
|
||||
class template, which is aimed at users who wish fully automatic endianness
|
||||
conversion and direct support for all normal arithmetic operations.</p>
|
||||
<h2><a name="Example">Example</a></h2>
|
||||
<p>The <a href="../example/endian_example.cpp">endian_example.cpp</a> program writes a
|
||||
<p>The <b><code>example/endian_example.cpp</code></b> program writes a
|
||||
binary file containing four byte big-endian and little-endian integers:</p>
|
||||
<blockquote>
|
||||
<pre>#include <iostream>
|
||||
#include <cstdio>
|
||||
#include <boost/endian/buffers.hpp>
|
||||
#include <boost/endian/buffers.hpp> // see <a href="#Synopsis">Synopsis</a> below
|
||||
#include <boost/static_assert.hpp>
|
||||
|
||||
using namespace boost::endian;
|
||||
|
||||
namespace
|
||||
{
|
||||
// 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.
|
||||
// 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
|
||||
{
|
||||
@@ -132,11 +124,13 @@ int main(int, char* [])
|
||||
h.version = 1;
|
||||
h.shape_type = 0x01020304;
|
||||
|
||||
// Low-level I/O such as POSIX read/write or <cstdio> fread/fwrite is sometimes
|
||||
// used for binary file operations when ultimate efficiency is important. Such
|
||||
// I/O is often performed in some C++ wrapper class, but to drive home the
|
||||
// point that endian integers are often used in fairly low-level code that does
|
||||
// bulk I/O operations, <cstdio> fopen/fwrite is used for I/O in this example.
|
||||
// Low-level I/O such as POSIX read/write or <cstdio>
|
||||
// fread/fwrite is sometimes used for binary file operations
|
||||
// when ultimate efficiency is important. Such I/O is often
|
||||
// performed in some C++ wrapper class, but to drive home the
|
||||
// point that endian integers are often used in fairly
|
||||
// low-level code that does bulk I/O operations, <cstdio>
|
||||
// fopen/fwrite is used for I/O in this example.
|
||||
|
||||
std::FILE* fi = std::fopen(filename, "wb"); // MUST BE BINARY
|
||||
|
||||
@@ -160,7 +154,7 @@ int main(int, char* [])
|
||||
}
|
||||
</pre>
|
||||
</blockquote>
|
||||
<p>After compiling and executing <a href="../example/endian_example.cpp">endian_example.cpp</a>,
|
||||
<p>After compiling and executing <b><code>example/endian_example.cpp</code></b>,
|
||||
a hex dump of <code>test.dat</code> shows:</p>
|
||||
<blockquote>
|
||||
<pre>01020304 00000010 01000000 04030201</pre>
|
||||
@@ -201,8 +195,9 @@ enum class align {no, yes}; </pre>
|
||||
</blockquote>
|
||||
<p>One class template is provided:</p>
|
||||
<blockquote>
|
||||
<pre>template <order Order, typename T, std::size_t Nbits, align A = align::no>
|
||||
class endian_buffer;
|
||||
<pre>template <order Order, typename T, std::size_t Nbits,
|
||||
align Align = align::no>
|
||||
class endian_buffer;
|
||||
</pre>
|
||||
</blockquote>
|
||||
<p>Typedefs, such as <code>big_int32_buf_t</code>, provide convenient naming
|
||||
@@ -339,7 +334,7 @@ requirements vary between hardware architectures and because alignment may be
|
||||
affected by compiler switches or pragmas. For example, alignment of an 64-bit
|
||||
integer may be to a 32-bit boundary on a 32-bit machine. Furthermore, aligned types
|
||||
are only available on architectures with 16, 32, and 64-bit integer types. </p>
|
||||
<p><b><i>Note:</i></b> One-byte types
|
||||
<p><b><i>Note:</i></b> One-byte big and little buffer 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>_buffer</code></h2>
|
||||
@@ -362,7 +357,8 @@ usual operations on integers are supplied.</p>
|
||||
|
||||
enum class <a name="alignment">align</a> {no, yes};
|
||||
|
||||
template <order Order, class T, std::size_t Nbits, align Align = align::no>
|
||||
template <order Order, class T, std::size_t Nbits,
|
||||
align Align = align::no>
|
||||
class endian_buffer
|
||||
{
|
||||
public:
|
||||
@@ -377,6 +373,20 @@ usual operations on integers are supplied.</p>
|
||||
protected:
|
||||
<b><i>implementaton-defined</i></b> endian_value; // for exposition only
|
||||
};
|
||||
|
||||
// stream inserter
|
||||
template <class charT, class traits, order Order, class T,
|
||||
std::size_t n_bits, align Align>
|
||||
std::basic_ostream<charT, traits>&
|
||||
<a href="#inserter">operator<<</a>(std::basic_ostream<charT, traits>& os,
|
||||
const endian_buffer<Order, T, n_bits, Align>& x);
|
||||
|
||||
// stream extractor
|
||||
template <class charT, class traits, order Order, class T,
|
||||
std::size_t n_bits, align A>
|
||||
std::basic_istream<charT, traits>&
|
||||
<a href="#extractor">operator>></a>(std::basic_istream<charT, traits>& is,
|
||||
endian_buffer<Order, T, n_bits, Align>& x);
|
||||
|
||||
// typedefs
|
||||
|
||||
@@ -479,7 +489,6 @@ usual operations on integers are supplied.</p>
|
||||
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;
|
||||
|
||||
|
||||
} // namespace endian
|
||||
} // namespace boost</pre>
|
||||
<p>The <i><b><code>implementation-defined</code></b></i> text in typedefs above is either
|
||||
@@ -539,6 +548,30 @@ boost::endian::endian_reverse</code>.</p>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> A pointer to the first byte of <code>endian_value</code>.</p>
|
||||
</blockquote>
|
||||
<h3><a name="Non-member-functions">Non-member functions</a></h3>
|
||||
<pre>template <class charT, class traits, order Order, class T,
|
||||
std::size_t n_bits, align Align>
|
||||
std::basic_ostream<charT, traits>& <a name="inserter">operator<<</a>(std::basic_ostream<charT, traits>& os,
|
||||
const endian_buffer<Order, T, n_bits, Align>& x);
|
||||
</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>os << x.value()</code>.</p>
|
||||
</blockquote>
|
||||
<pre>template <class charT, class traits, order Order, class T,
|
||||
std::size_t n_bits, align A>
|
||||
std::basic_istream<charT, traits>& <a name="extractor">operator>></a>(std::basic_istream<charT, traits>& is,
|
||||
endian_buffer<Order, T, n_bits, Align>& 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>.</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
|
||||
@@ -617,7 +650,7 @@ any Boost object libraries.</p>
|
||||
</ul>
|
||||
<hr>
|
||||
<p>Last revised:
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->06 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38644" --></p>
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->19 January, 2015<!--webbot bot="Timestamp" endspan i-checksum="38903" --></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>
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns="http://www.w3.org/TR/REC-html40">
|
||||
<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">
|
||||
@@ -15,7 +15,7 @@
|
||||
<tr>
|
||||
<td>
|
||||
<a href="../../../index.html">
|
||||
<img src="http://www.boost.org/boost.png" alt="Boost logo" align="middle" border="0" width="277" height="86" ></a></td>
|
||||
<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>
|
||||
@@ -24,11 +24,12 @@
|
||||
|
||||
<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>
|
||||
<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></b></td>
|
||||
<a href="buffers.html">Buffer Types</a>
|
||||
<a href="choosing_approach.html">Choosing Approach</a></b></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
@@ -52,17 +53,7 @@
|
||||
<a href="#FAQ">FAQ</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="../include/boost/endian/conversion.hpp"><boost/endian/conversion.hpp></a><br>
|
||||
<a href="../include/boost/endian/buffers.hpp"><boost/endian/buffers.hpp></a><br>
|
||||
<a href="../include/boost/endian/arithmetic.hpp"><boost/endian/arithmetic.hpp></a></td>
|
||||
</tr>
|
||||
</table>
|
||||
</table>
|
||||
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
|
||||
@@ -232,8 +223,7 @@ call to <code>endian_reverse()</code>.</p>
|
||||
<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 <a href="../example/udt_conversion_example.cpp">
|
||||
udt_conversion_example.cpp</a> for an example user-defined type.</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;
|
||||
@@ -371,12 +361,13 @@ 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 <a href="../include/boost/endian/detail/intrinsic.hpp">boost/endian/detail/intrinsic.hpp</a>.
|
||||
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 -->16 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38645" --></p>
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->19 January, 2015<!--webbot bot="Timestamp" endspan i-checksum="38903" --></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>
|
||||
|
||||
|
||||
594
index.html
594
index.html
@@ -15,23 +15,26 @@
|
||||
<tr>
|
||||
<td width="339">
|
||||
<a href="../../../index.html">
|
||||
<img src="http://www.boost.org/boost.png" alt="Boost logo" align="middle" border="0" width="277" height="86"></a></td>
|
||||
<img src="../../../boost.png" alt="Boost logo" align="middle" border="0" width="277" height="86"></a></td>
|
||||
<td align="middle" width="1253">
|
||||
<b>
|
||||
<font size="6">Endian Library</font></b></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="100%">
|
||||
<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>
|
||||
<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></b></td>
|
||||
<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">
|
||||
@@ -42,40 +45,22 @@
|
||||
<a href="#Abstract">Abstract</a><br>
|
||||
<a href="#Introduction-to-endianness">Introduction to endianness</a><br>
|
||||
<a href="#Introduction">Introduction to the Boost.Endian library</a><br>
|
||||
<a href="#Choosing">Choosing between conversion, buffer types,</a><br>
|
||||
<a href="#Choosing">and arithmetic types</a><br>
|
||||
<a href="#Characteristics">Characteristics</a><br>
|
||||
<a href="#Endianness-invariants">Endianness invariants</a><br>
|
||||
<a href="#Conversion-explicitness">Conversion explicitness</a><br>
|
||||
<a href="#Arithmetic-operations">Arithmetic operations</a><br>
|
||||
<a href="#Sizes">Sizes</a><br>
|
||||
<a href="#Alignments">Alignments</a><br>
|
||||
<a href="#Use-cases">Use cases</a><br>
|
||||
<a href="#Porting-endian-unaware-codebase">Porting endian unaware codebase</a><br>
|
||||
<a href="#Porting-endian-aware-codebase">Porting endian aware codebase</a><br>
|
||||
<a href="#Reliability-arithmetic-speed">Reliability and arithmetic-speed</a><br>
|
||||
<a href="#Reliability-ease-of-use">Reliability and ease-of-use</a><br>
|
||||
<a href="#Choosing">Choosing between conversion functions,</a><br>
|
||||
<a href="#Choosing">buffer types, and arithmetic types</a><br>
|
||||
<a href="#Intrinsic">Built-in support for Intrinsics</a><br>
|
||||
<a href="#Performance">Performance</a><br>
|
||||
<a href="#Timings">Timings for Example 2</a><br>
|
||||
<a href="#Conclusions">Conclusions</a><br>
|
||||
<a href="#Timings">Timings</a><br>
|
||||
<a href="#FAQ">Overall FAQ</a><br>
|
||||
<a href="#Release-history">Release history</a><br>
|
||||
<a href="#Changes-since-formal-review">Changes since formal review</a><br>
|
||||
<a href="#Changes-requested-by-formal-review">Changes
|
||||
requested by formal review</a><br>
|
||||
<a href="#Other-changes-since-formal-review">Other changes since
|
||||
formal review</a><br>
|
||||
<a href="#Compatibility">Compatibility with interim releases</a><br>
|
||||
<a href="#Acknowledgements">Acknowledgements</a><br>
|
||||
</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="../include/boost/endian/conversion.hpp"><boost/endian/conversion.hpp></a><br>
|
||||
<a href="../include/boost/endian/buffers.hpp"><boost/endian/buffers.hpp></a><br>
|
||||
<a href="../include/boost/endian/arithmetic.hpp"><boost/endian/arithmetic.hpp></a></td>
|
||||
</tr>
|
||||
</table>
|
||||
</table>
|
||||
|
||||
<h2><a name="Abstract">Abstract</a></h2>
|
||||
|
||||
@@ -83,7 +68,11 @@
|
||||
<a href="#Introduction-to-endianness">endianness</a> of integers,
|
||||
floating point numbers, and user-defined types.</p>
|
||||
<ul>
|
||||
<li>Primary use cases:<br>
|
||||
<li>Three approaches to endianness are supported. Each has a
|
||||
long history of successful use, and each approach has use cases where it is
|
||||
preferred over the other approaches.<br>
|
||||
</li>
|
||||
<li>Primary uses:<br>
|
||||
<ul>
|
||||
<li>Data portability. The Endian library supports binary data exchange, via either external media or network transmission,
|
||||
regardless of platform endianness.<br>
|
||||
@@ -97,17 +86,11 @@ floating point numbers, and user-defined types.</p>
|
||||
</ul>
|
||||
|
||||
</li>
|
||||
<li>Secondary use case: Minimizing data size via sizes and/or alignments not supported by the
|
||||
<li>Secondary use: Minimizing data size via sizes and/or alignments not supported by the
|
||||
standard C++ arithmetic types.<br>
|
||||
<br></li>
|
||||
<li>Three approaches to dealing with endianness are supported. Each has a
|
||||
long history of successful use, and each approach has use cases where it is
|
||||
preferred over the other approaches.</li>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<p> </p>
|
||||
<p> </p>
|
||||
|
||||
<h2><a name="Introduction-to-endianness">Introduction to endianness</a></h2>
|
||||
|
||||
<p>Consider the following code:</p>
|
||||
@@ -181,189 +164,35 @@ integers. The types may be aligned.</p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<p>Boost Endian is a header-only library.</p>
|
||||
<p>Boost Endian is a header-only library. C++03 compilers are supported. C++11 features
|
||||
affecting interfaces, such as <code>noexcept</code>, are used only if available.</p>
|
||||
|
||||
<h2><a name="Choosing">Choosing</a> between conversion functions, buffer types,
|
||||
and arithmetic types</h2>
|
||||
|
||||
<p>The best approach to endianness for a particular use case depends on interactions between
|
||||
the approach characteristics and
|
||||
the application needs.</p>
|
||||
|
||||
<p><b>Recommendation:</b> If you are uncertain, new to endianness, concerned
|
||||
about security, concerned about reliability, or don't want to invest time making
|
||||
engineering trade-offs, use the <a href="arithmetic.html">endian arithmetic types</a>. They are safer, easier
|
||||
to use, and your code will be easier to maintain.</p>
|
||||
|
||||
<h3><a name="Characteristics">Characteristics</a></h3>
|
||||
|
||||
<p>The characteristics that differentiate the three approaches to endianness are the endianness
|
||||
invariants, conversion explicitness, arithmetic operations, sizes available, and
|
||||
alignment requirements.</p>
|
||||
|
||||
<h4><a name="Endianness-invariants">Endianness invariants</a></h4>
|
||||
|
||||
<blockquote>
|
||||
|
||||
<p><b>Endian conversion functions</b> use objects of the ordinary C++ arithmetic
|
||||
types like <code>int</code> or <code>unsigned short</code> to hold values. That
|
||||
breaks the implicit invariant that the C++ language rules apply. The usual
|
||||
language rules only apply if the endianness of the object is currently set by
|
||||
the conversion functions to the native endianness for the platform. That can
|
||||
make it very hard to reason about complex logic flow, and result in difficult to
|
||||
find bugs.</p>
|
||||
|
||||
<p><b>Endian buffer and arithmetic types</b> hold values internally as arrays of
|
||||
characters with an invariant that the endianness of the array never changes.
|
||||
That makes these types easier to use and programs easier to maintain.</p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="Conversion-explicitness">Conversion explicitness</a></h4>
|
||||
|
||||
<blockquote>
|
||||
|
||||
<p><b>Endian conversion functions</b> and <b>buffer types</b> never perform
|
||||
implicit conversions. This gives users explicit control of when conversion
|
||||
occurs, and may help avoid unnecessary conversions.</p>
|
||||
|
||||
<p><b>Endian arithmetic types</b> perform conversion implicitly. That makes
|
||||
these types very easy to use, but can result in unnecessary conversions. Failure
|
||||
to hoist conversions out of inner loops can bring a performance penalty.</p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="Arithmetic-operations">Arithmetic operations</a></h4>
|
||||
|
||||
<blockquote>
|
||||
|
||||
<p><b>Endian conversion functions</b> do not supply arithmetic
|
||||
operations, but this is not a concern since this approach uses ordinary C++
|
||||
arithmetic types to hold values.</p>
|
||||
|
||||
<p><b>Endian buffer types</b> do not supply arithmetic operations. Although this
|
||||
approach avoids unnecessary conversions, it can result in the introduction of
|
||||
additional variables and confuse maintenance programmers.</p>
|
||||
|
||||
<p><b>Endian</b> <b>arithmetic types</b> do supply arithmetic operations. They
|
||||
are very easy to use if lots of arithmetic is involved. </p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="Sizes">Sizes</a></h4>
|
||||
|
||||
<blockquote>
|
||||
|
||||
<p><b>Endianness conversion functions</b> only support 1, 2, 4, and 8 byte
|
||||
integers. That's sufficient for many applications.</p>
|
||||
|
||||
<p><b>Endian buffer and arithmetic types</b> support 1, 2, 3, 4, 5, 6, 7, and 8
|
||||
byte integers. For an application where memory use or I/O speed is the limiting
|
||||
factor, using sizes tailored to application needs can be useful.</p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<h4><a name="Alignments">Alignments</a></h4>
|
||||
|
||||
<blockquote>
|
||||
|
||||
<p><b>Endianness conversion functions</b> only support aligned integer and
|
||||
floating-point types. That's sufficient for most applications.</p>
|
||||
|
||||
<p><b>Endian buffer and arithmetic types</b> support both aligned and unaligned
|
||||
integer and floating-point types. Unaligned types are rarely needed, but when
|
||||
needed they are often very useful and workarounds are painful. For example,</p>
|
||||
|
||||
<blockquote>
|
||||
<p>Non-portable code like this:<blockquote>
|
||||
<p><code>struct S {<br>
|
||||
uint16_t a; // big endian<br>
|
||||
uint32_t b; // big endian<br>
|
||||
} __attribute__ ((packed));</code>
|
||||
</p></blockquote>
|
||||
<p>Can be replaced with portable code like this:</p>
|
||||
<blockquote>
|
||||
<p><code>struct S {<br>
|
||||
big_uint16_ut a;<br>
|
||||
big_uint32_ut b;<br>
|
||||
};</code>
|
||||
</p></blockquote>
|
||||
</blockquote>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<h3><a name="Use-cases">Use cases</a></h3>
|
||||
|
||||
<h4><a name="Porting-endian-unaware-codebase">Porting endian unaware codebase</a></h4>
|
||||
|
||||
<p>An existing codebase runs on big endian systems. It does not
|
||||
currently deal with endianness. The codebase needs to be modified so it can run
|
||||
on little endian systems under various operating systems. To ease
|
||||
transition and protect value of existing files, external data will continue to
|
||||
be maintained as big endian.</p>
|
||||
|
||||
<p dir="ltr">The <a href="arithmetic.html">endian
|
||||
arithmetic approach</a> is recommended to meet these needs. A relatively small
|
||||
number of header files dealing with binary I/O layouts need to change types like
|
||||
<code>short</code> or <code>int16_t</code> to <code>big_int16_t</code>, and
|
||||
<code>int</code> or <code>int32_t</code> to <code>bif_int32_t</code>. No
|
||||
changes are required for <code>.cpp</code> files.</p>
|
||||
|
||||
<h4><a name="Porting-endian-aware-codebase">Porting endian aware codebase</a></h4>
|
||||
|
||||
<p>An existing codebase runs on little-endian Linux systems. It already
|
||||
deals with endianness via
|
||||
<a href="http://man7.org/linux/man-pages/man3/endian.3.html">Linux provided
|
||||
functions</a>. Because of a business merger, the codebase has to be quickly
|
||||
modified for Windows and possibly other operating systems, while still
|
||||
supporting Linux. The codebase is reliable and the programmers are all
|
||||
well-aware of endian issues. </p>
|
||||
|
||||
<p dir="ltr">These factors all argue for an <a href="conversion.html">endian conversion
|
||||
approach</a> that just mechanically changes the calls to <code>htobe32</code>,
|
||||
etc. to <code>boost::endian::native_to_big</code>, etc. and replaces <code><endian.h></code>
|
||||
with <code><boost/endian/conversion.hpp></code>.</p>
|
||||
|
||||
<h4><a name="Reliability-arithmetic-speed">Reliability and arithmetic-speed</a></h4>
|
||||
|
||||
<p>A new, complex, multi-threaded application is to be developed that must run
|
||||
on little endian machines, but do big endian network I/O. The developers believe
|
||||
computational speed for endian variable is critical but have seen numerous bugs
|
||||
result from inability to reason about endian conversion state. They are also
|
||||
worried that future maintenance changes could inadvertently introduce a lot of
|
||||
slow conversions if full-blown endian arithmetic types are used.</p>
|
||||
|
||||
<p>The <a href="buffers.html">endian buffers</a> approach is made-to-order for
|
||||
this use case.</p>
|
||||
|
||||
<h4><a name="Reliability-ease-of-use">Reliability and ease-of-use</a></h4>
|
||||
|
||||
<p>A new, complex, multi-threaded application is to be developed that must run
|
||||
on little endian machines, but do big endian network I/O. The developers believe
|
||||
computational speed for endian variables is <b>not critical</b> but have seen
|
||||
numerous bugs result from inability to reason about endian conversion state.
|
||||
They are also concerned about ease-of-use both during development and long-term
|
||||
maintenance.</p>
|
||||
|
||||
<p>Removing concern about conversion speed and adding concern about ease-of-use
|
||||
tips the balance strongly in favor the <a href="arithmetic.html">endian
|
||||
arithmetic approach</a>.</p>
|
||||
<p>This section has been moved to its own <a href="choosing_approach.html">
|
||||
Choosing the Approach</a> page. </p>
|
||||
|
||||
<h2>Built-in support for <a name="Intrinsic">Intrinsic</a>s</h2>
|
||||
<p>Supply compilers, including GCC, Clang, and Visual C++, supply built-in support for byte swapping intrinsics.
|
||||
The library uses these intrinsics when available since they may result in smaller and faster generated code, particularly for release
|
||||
<p>Most compilers, including GCC, Clang, and Visual C++, supply built-in support for byte swapping intrinsics.
|
||||
The Endian library uses these intrinsics when available since they may result in smaller and faster generated code, particularly for release
|
||||
builds.</p>
|
||||
<p>Defining <code>BOOST_ENDIAN_NO_INTRINSICS</code> will suppress use
|
||||
<p>Defining the macro <code>BOOST_ENDIAN_NO_INTRINSICS</code> will suppress use
|
||||
of the intrinsics. Useful when intrinsic headers such as
|
||||
<code>byteswap.h </code>are not being found on your platform.</p>
|
||||
<code>byteswap.h </code>are not being found by your compiler, perhaps because it
|
||||
is an older release or has very limited supporting libraries.</p>
|
||||
<p>The macro <code>BOOST_ENDIAN_INTRINSIC_MSG</code> is defined as
|
||||
either <code>"no byte swap intrinsics"</code> or a string describing the
|
||||
particular set of intrinsics being used.</p>
|
||||
particular set of intrinsics being used. Useful for eliminating missing
|
||||
intrinsics as a source of performance issues.</p>
|
||||
|
||||
<h2><a name="Performance">Performance</a></h2>
|
||||
|
||||
<p>Consider this problem:</p>
|
||||
|
||||
<div align="center">
|
||||
<center>
|
||||
|
||||
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
|
||||
<tr>
|
||||
<td colspan="2">
|
||||
@@ -404,15 +233,20 @@ native_to_big_inplace(x);
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
</center>
|
||||
</div>
|
||||
|
||||
<p><b>There will be no performance difference between the two approaches in
|
||||
release builds,
|
||||
regardless of the native endianness of the machine.</b> That's because optimizing compilers will likely
|
||||
generate exactly the same code for each. That conclusion was confirmed by
|
||||
regardless of the native endianness of the machine.</b> That's because optimizing compilers will generate exactly the same code for each. That conclusion was confirmed by
|
||||
studying the generated assembly code for GCC and Visual C++. Furthermore, time
|
||||
spent doing I/O will determine the speed of this application.</p>
|
||||
|
||||
<p>Now consider a slightly different problem: </p>
|
||||
|
||||
<div align="center">
|
||||
<center>
|
||||
|
||||
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
|
||||
<tr>
|
||||
<td colspan="2">
|
||||
@@ -456,230 +290,63 @@ native_to_big_inplace(x);
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
</center>
|
||||
</div>
|
||||
|
||||
<p>With the Endian arithmetic approach, on little endian platforms an implicit conversion from and then back to
|
||||
big endian is done inside the loop. With the Endian conversion function
|
||||
approach, the user has ensured the conversions are done outside the loop, so the
|
||||
code may run more quickly on little endian platforms.</p>
|
||||
|
||||
<h3><a name="Timings">Timings</a> for Example 2 (conversion functions hoisted
|
||||
out of loop)</h3>
|
||||
<h3><a name="Timings">Timings</a></h3>
|
||||
<p>These tests were run against release builds on a circa 2012 4-core little endian X64 Intel Core i5-3570K
|
||||
CPU @ 3.40GHz under Windows 7.</p>
|
||||
|
||||
<p><b>Caveat emptor: The Windows CPU timer has very high granularity. Repeated
|
||||
runs of the same tests often yield considerably different results.</b></p>
|
||||
|
||||
<p>See <a href="../test/loop_time_test.cpp">loop_time_test.cpp</a> and
|
||||
<a href="../build/Jamfile.v2">Jamfile.v2</a> for the actual code and build
|
||||
setup.
|
||||
(For GCC 4.7, there are no 16-bit intrinsics, so they are emulated by using
|
||||
32-bit intrinsics.)</p>
|
||||
<p>See <b>test/loop_time_test.cpp</b> for the actual code and <b>benchmark/Jamfile.v2</b> for the build
|
||||
setup.</p>
|
||||
|
||||
|
||||
<div align="center">
|
||||
<center>
|
||||
<table border="1" cellpadding="5" cellspacing="0"style="border-collapse: collapse" bordercolor="#111111">
|
||||
<tr><td colspan="6" align="center"><b><font size="2">GNU C++ version 4.7.0</font></b></td></tr>
|
||||
<tr><td colspan="6" align="center"><b> <font size="2">Iterations: 1000000000, Intrinsics: __builtin_bswap16, etc.</font></b></td></tr>
|
||||
<tr><td><b><font size="2">Test Case</font></b></td>
|
||||
<td align="center"><b><font size="2">Endian<br>arithmetic</font></b></td>
|
||||
<td align="center"><b><font size="2">Endian<br>conversion<br>function</font></b></td>
|
||||
<tr><td colspan="6" align="center"><b>GNU C++ version 4.8.2 on Linux virtual
|
||||
machine</b></td></tr>
|
||||
<tr><td colspan="6" align="center"><b> Iterations: 10'000'000'000, Intrinsics: __builtin_bswap16, etc.</b></td></tr>
|
||||
<tr><td><b>Test Case</b></td>
|
||||
<td align="center"><b>Endian<br>arithmetic<br>type</b></td>
|
||||
<td align="center"><b>Endian<br>conversion<br>function</b></td>
|
||||
</tr>
|
||||
<tr><td><font size="2">16-bit aligned big endian</font></td>
|
||||
<td align="right"><font size="2">1.37 s</font></td>
|
||||
<td align="right"><font size="2">0.81 s</font></td></tr>
|
||||
<tr><td><font size="2">16-bit aligned little endian</font></td>
|
||||
<td align="right"><font size="2">0.83 s</font></td>
|
||||
<td align="right"><font size="2">0.81 s</font></td></tr>
|
||||
<tr><td><font size="2">16-bit unaligned big endian</font></td>
|
||||
<td align="right"><font size="2">1.09 s</font></td>
|
||||
<td align="right"><font size="2">0.83 s</font></td></tr>
|
||||
<tr><td><font size="2">16-bit unaligned little endian</font></td>
|
||||
<td align="right"><font size="2">1.09 s</font></td>
|
||||
<td align="right"><font size="2">0.81 s</font></td></tr>
|
||||
<tr><td><b><font size="2">32-bit aligned big endian</font></b></td>
|
||||
<td align="right"><b><font size="2">0.98 s</font></b></td>
|
||||
<td align="right"><b><font size="2">0.27 s</font></b></td></tr>
|
||||
<tr><td><font size="2">32-bit aligned little endian</font></td>
|
||||
<td align="right"><font size="2">0.28 s</font></td>
|
||||
<td align="right"><font size="2">0.27 s</font></td></tr>
|
||||
<tr><td><font size="2">32-bit unaligned big endian</font></td>
|
||||
<td align="right"><font size="2">3.82 s</font></td>
|
||||
<td align="right"><font size="2">0.27 s</font></td></tr>
|
||||
<tr><td><font size="2">32-bit unaligned little endian</font></td>
|
||||
<td align="right"><font size="2">3.82 s</font></td>
|
||||
<td align="right"><font size="2">0.27 s</font></td></tr>
|
||||
<tr><td><font size="2">64-bit aligned big endian</font></td>
|
||||
<td align="right"><font size="2">1.65 s</font></td>
|
||||
<td align="right"><font size="2">0.41 s</font></td></tr>
|
||||
<tr><td><font size="2">64-bit aligned little endian</font></td>
|
||||
<td align="right"><font size="2">0.41 s</font></td>
|
||||
<td align="right"><font size="2">0.41 s</font></td></tr>
|
||||
<tr><td><font size="2">64-bit unaligned big endian</font></td>
|
||||
<td align="right"><font size="2">17.53 s</font></td>
|
||||
<td align="right"><font size="2">0.41 s</font></td></tr>
|
||||
<tr><td><font size="2">64-bit unaligned little endian</font></td>
|
||||
<td align="right"><font size="2">17.52 s</font></td>
|
||||
<td align="right"><font size="2">0.41 s</font></td></tr>
|
||||
|
||||
<tr><td colspan="6" align="center"><b> <font size="2">Iterations: 1000000000, Intrinsics: no byte swap intrinsics</font></b></td></tr>
|
||||
<tr><td><b><font size="2">Test Case</font></b></td>
|
||||
<td align="center"><b><font size="2">Endian<br>arithmetic</font></b></td>
|
||||
<td align="center"><b><font size="2">Endian<br>conversion<br>function</font></b></td>
|
||||
</tr>
|
||||
<tr><td><font size="2">16-bit aligned big endian</font></td>
|
||||
<td align="right"><font size="2">1.95 s</font></td>
|
||||
<td align="right"><font size="2">0.81 s</font></td></tr>
|
||||
<tr><td><font size="2">16-bit aligned little endian</font></td>
|
||||
<td align="right"><font size="2">0.83 s</font></td>
|
||||
<td align="right"><font size="2">0.81 s</font></td></tr>
|
||||
<tr><td><font size="2">16-bit unaligned big endian</font></td>
|
||||
<td align="right"><font size="2">1.19 s</font></td>
|
||||
<td align="right"><font size="2">0.81 s</font></td></tr>
|
||||
<tr><td><font size="2">16-bit unaligned little endian</font></td>
|
||||
<td align="right"><font size="2">1.20 s</font></td>
|
||||
<td align="right"><font size="2">0.81 s</font></td></tr>
|
||||
<tr><td><b><font size="2">32-bit aligned big endian</font></b></td>
|
||||
<td align="right"><b><font size="2">0.97 s</font></b></td>
|
||||
<td align="right"><b><font size="2">0.28 s</font></b></td></tr>
|
||||
<tr><td><font size="2">32-bit aligned little endian</font></td>
|
||||
<td align="right"><font size="2">0.27 s</font></td>
|
||||
<td align="right"><font size="2">0.28 s</font></td></tr>
|
||||
<tr><td><font size="2">32-bit unaligned big endian</font></td>
|
||||
<td align="right"><font size="2">4.10 s</font></td>
|
||||
<td align="right"><font size="2">0.27 s</font></td></tr>
|
||||
<tr><td><font size="2">32-bit unaligned little endian</font></td>
|
||||
<td align="right"><font size="2">4.10 s</font></td>
|
||||
<td align="right"><font size="2">0.27 s</font></td></tr>
|
||||
<tr><td><font size="2">64-bit aligned big endian</font></td>
|
||||
<td align="right"><font size="2">1.64 s</font></td>
|
||||
<td align="right"><font size="2">0.42 s</font></td></tr>
|
||||
<tr><td><font size="2">64-bit aligned little endian</font></td>
|
||||
<td align="right"><font size="2">0.41 s</font></td>
|
||||
<td align="right"><font size="2">0.41 s</font></td></tr>
|
||||
<tr><td><font size="2">64-bit unaligned big endian</font></td>
|
||||
<td align="right"><font size="2">17.52 s</font></td>
|
||||
<td align="right"><font size="2">0.42 s</font></td></tr>
|
||||
<tr><td><font size="2">64-bit unaligned little endian</font></td>
|
||||
<td align="right"><font size="2">17.52 s</font></td>
|
||||
<td align="right"><font size="2">0.41 s</font></td></tr>
|
||||
<tr><td>16-bit aligned big endian</td><td align="right">8.46 s</td><td align="right">5.28 s</td></tr>
|
||||
<tr><td>16-bit aligned little endian</td><td align="right">5.28 s</td><td align="right">5.22 s</td></tr>
|
||||
<tr><td>32-bit aligned big endian</td><td align="right">8.40 s</td><td align="right">2.11 s</td></tr>
|
||||
<tr><td>32-bit aligned little endian</td><td align="right">2.11 s</td><td align="right">2.10 s</td></tr>
|
||||
<tr><td>64-bit aligned big endian</td><td align="right">14.02 s</td><td align="right">3.10 s</td></tr>
|
||||
<tr><td>64-bit aligned little endian</td><td align="right">3.00 s</td><td align="right">3.03 s</td></tr>
|
||||
|
||||
</table>
|
||||
</center>
|
||||
</div>
|
||||
<p></p>
|
||||
|
||||
<p><b>Comment:</b> Note that the <b><font size="2">32-bit aligned big endian </font></b>
|
||||
timings are the same with or without intrinsics turned on. Presumably the
|
||||
optimizer is recognizing the byte swapping and applying the intrinsics itself.</p>
|
||||
|
||||
<div align="center"> <center>
|
||||
<table border="1" cellpadding="5" cellspacing="0"style="border-collapse: collapse" bordercolor="#111111">
|
||||
<tr><td colspan="6" align="center"><b><font size="2">Microsoft Visual C++ version 11.0</font></b></td></tr>
|
||||
<tr><td colspan="6" align="center"><b> <font size="2">Iterations: 1000000000, Intrinsics: cstdlib _byteswap_ushort, etc.</font></b></td></tr>
|
||||
<tr><td><b><font size="2">Test Case</font></b></td>
|
||||
<td align="center"><b><font size="2">Endian<br>type</font></b></td>
|
||||
<td align="center"><b><font size="2">Endian<br>conversion<br>function</font></b></td>
|
||||
<tr><td colspan="6" align="center"><b>Microsoft Visual C++ version 14.0</b></td></tr>
|
||||
<tr><td colspan="6" align="center"><b> Iterations: 10'000'000'000, Intrinsics: cstdlib _byteswap_ushort, etc.</b></td></tr>
|
||||
<tr><td><b>Test Case</b></td>
|
||||
<td align="center"><b>Endian<br>arithmetic<br>type</b></td>
|
||||
<td align="center"><b>Endian<br>conversion<br>function</b></td>
|
||||
</tr>
|
||||
<tr><td><font size="2">16-bit aligned big endian</font></td>
|
||||
<td align="right"><font size="2">0.83 s</font></td>
|
||||
<td align="right"><font size="2">0.51 s</font></td></tr>
|
||||
<tr><td><font size="2">16-bit aligned little endian</font></td>
|
||||
<td align="right"><font size="2">0.51 s</font></td>
|
||||
<td align="right"><font size="2">0.50 s</font></td></tr>
|
||||
<tr><td><font size="2">16-bit unaligned big endian</font></td>
|
||||
<td align="right"><font size="2">1.37 s</font></td>
|
||||
<td align="right"><font size="2">0.51 s</font></td></tr>
|
||||
<tr><td><font size="2">16-bit unaligned little endian</font></td>
|
||||
<td align="right"><font size="2">1.37 s</font></td>
|
||||
<td align="right"><font size="2">0.50 s</font></td></tr>
|
||||
<tr><td><b><font size="2">32-bit aligned big endian</font></b></td>
|
||||
<td align="right"><b><font size="2">0.81 s</font></b></td>
|
||||
<td align="right"><b><font size="2">0.50 s</font></b></td></tr>
|
||||
<tr><td><font size="2">32-bit aligned little endian</font></td>
|
||||
<td align="right"><font size="2">0.51 s</font></td>
|
||||
<td align="right"><font size="2">0.51 s</font></td></tr>
|
||||
<tr><td><font size="2">32-bit unaligned big endian</font></td>
|
||||
<td align="right"><font size="2">2.98 s</font></td>
|
||||
<td align="right"><font size="2">0.53 s</font></td></tr>
|
||||
<tr><td><font size="2">32-bit unaligned little endian</font></td>
|
||||
<td align="right"><font size="2">3.00 s</font></td>
|
||||
<td align="right"><font size="2">0.51 s</font></td></tr>
|
||||
<tr><td><font size="2">64-bit aligned big endian</font></td>
|
||||
<td align="right"><font size="2">1.33 s</font></td>
|
||||
<td align="right"><font size="2">0.33 s</font></td></tr>
|
||||
<tr><td><font size="2">64-bit aligned little endian</font></td>
|
||||
<td align="right"><font size="2">0.34 s</font></td>
|
||||
<td align="right"><font size="2">0.27 s</font></td></tr>
|
||||
<tr><td><font size="2">64-bit unaligned big endian</font></td>
|
||||
<td align="right"><font size="2">7.05 s</font></td>
|
||||
<td align="right"><font size="2">0.33 s</font></td></tr>
|
||||
<tr><td><font size="2">64-bit unaligned little endian</font></td>
|
||||
<td align="right"><font size="2">7.11 s</font></td>
|
||||
<td align="right"><font size="2">0.31 s</font></td></tr>
|
||||
|
||||
<tr><td colspan="6" align="center"><b> <font size="2">Iterations: 1000000000, Intrinsics: no byte swap intrinsics</font></b></td></tr>
|
||||
<tr><td><b><font size="2">Test Case</font></b></td>
|
||||
<td align="center"><b><font size="2">Endian<br>type</font></b></td>
|
||||
<td align="center"><b><font size="2">Endian<br>conversion<br>function</font></b></td>
|
||||
</tr>
|
||||
<tr><td><font size="2">16-bit aligned big endian</font></td>
|
||||
<td align="right"><font size="2">0.83 s</font></td>
|
||||
<td align="right"><font size="2">0.51 s</font></td></tr>
|
||||
<tr><td><font size="2">16-bit aligned little endian</font></td>
|
||||
<td align="right"><font size="2">0.51 s</font></td>
|
||||
<td align="right"><font size="2">0.51 s</font></td></tr>
|
||||
<tr><td><font size="2">16-bit unaligned big endian</font></td>
|
||||
<td align="right"><font size="2">1.36 s</font></td>
|
||||
<td align="right"><font size="2">0.51 s</font></td></tr>
|
||||
<tr><td><font size="2">16-bit unaligned little endian</font></td>
|
||||
<td align="right"><font size="2">1.37 s</font></td>
|
||||
<td align="right"><font size="2">0.51 s</font></td></tr>
|
||||
<tr><td><b><font size="2">32-bit aligned big endian</font></b></td>
|
||||
<td align="right"><b><font size="2">3.42 s</font></b></td>
|
||||
<td align="right"><b><font size="2">0.50 s</font></b></td></tr>
|
||||
<tr><td><font size="2">32-bit aligned little endian</font></td>
|
||||
<td align="right"><font size="2">0.51 s</font></td>
|
||||
<td align="right"><font size="2">0.51 s</font></td></tr>
|
||||
<tr><td><font size="2">32-bit unaligned big endian</font></td>
|
||||
<td align="right"><font size="2">2.93 s</font></td>
|
||||
<td align="right"><font size="2">0.50 s</font></td></tr>
|
||||
<tr><td><font size="2">32-bit unaligned little endian</font></td>
|
||||
<td align="right"><font size="2">2.95 s</font></td>
|
||||
<td align="right"><font size="2">0.50 s</font></td></tr>
|
||||
<tr><td><font size="2">64-bit aligned big endian</font></td>
|
||||
<td align="right"><font size="2">5.99 s</font></td>
|
||||
<td align="right"><font size="2">0.33 s</font></td></tr>
|
||||
<tr><td><font size="2">64-bit aligned little endian</font></td>
|
||||
<td align="right"><font size="2">0.33 s</font></td>
|
||||
<td align="right"><font size="2">0.33 s</font></td></tr>
|
||||
<tr><td><font size="2">64-bit unaligned big endian</font></td>
|
||||
<td align="right"><font size="2">7.02 s</font></td>
|
||||
<td align="right"><font size="2">0.27 s</font></td></tr>
|
||||
<tr><td><font size="2">64-bit unaligned little endian</font></td>
|
||||
<td align="right"><font size="2">7.02 s</font></td>
|
||||
<td align="right"><font size="2">0.27 s</font></td></tr>
|
||||
|
||||
<tr><td>16-bit aligned big endian</td><td align="right">8.27 s</td><td align="right">5.26 s</td></tr>
|
||||
<tr><td>16-bit aligned little endian</td><td align="right">5.29 s</td><td align="right">5.32 s</td></tr>
|
||||
<tr><td>32-bit aligned big endian</td><td align="right">8.36 s</td><td align="right">5.24 s</td></tr>
|
||||
<tr><td>32-bit aligned little endian</td><td align="right">5.24 s</td><td align="right">5.24 s</td></tr>
|
||||
<tr><td>64-bit aligned big endian</td><td align="right">13.65 s</td><td align="right">3.34 s</td></tr>
|
||||
<tr><td>64-bit aligned little endian</td><td align="right">3.35 s</td><td align="right">2.73 s</td></tr>
|
||||
</table>
|
||||
|
||||
|
||||
<h3><a name="Conclusions">Conclusions</a></h3>
|
||||
|
||||
<p>When program logic dictates many more conversions for the Endian arithmetic
|
||||
approach than the Endian conversion function approach (<a href="#Example-2">example
|
||||
2</a>):</p>
|
||||
|
||||
<blockquote>
|
||||
|
||||
<p><b>There may be a considerable performance difference. </b>If machine endianness differs from the
|
||||
desired endianness, the Endian arithmetic approach must do the byte reversal many
|
||||
times while the Endian conversion approach only does the reversal once. But if
|
||||
the endianness is the same, there is no conversion with either approach and no
|
||||
conversion code is generated for typical release builds.</p>
|
||||
|
||||
<p><b>Whether or not compiler byte swap intrinsics are explicitly available has little
|
||||
impact on GCC but a lot of impact on Visual C++, for the tested compiler
|
||||
versions.</b> Yet another example of why actual timing tests are needed to
|
||||
determine if some coding technique has significant impact on performance.</p>
|
||||
|
||||
<p><b>Unaligned types are much slower that aligned types, regardless of
|
||||
endianness considerations.</b> Instead of single instruction register loads and
|
||||
stores, multiple instructions are required on common platforms.</p>
|
||||
|
||||
</blockquote>
|
||||
</center></div>
|
||||
|
||||
|
||||
<h2>Overall <a name="FAQ">FAQ</a></h2>
|
||||
@@ -692,6 +359,14 @@ stores, multiple instructions are required on common platforms.</p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<p><b>Are C++03 compilers supported?</b></p>
|
||||
|
||||
<blockquote>
|
||||
|
||||
<p>Yes.</p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<p><b>Does the implementation use compiler intrinsic built-in byte swapping?</b></p>
|
||||
|
||||
<blockquote>
|
||||
@@ -708,7 +383,7 @@ stores, multiple instructions are required on common platforms.</p>
|
||||
I/O formats?</b> </p>
|
||||
<blockquote>
|
||||
<p>Using the unaligned integer types to save internal or external
|
||||
memory space is a minor secondary use case.</p>
|
||||
memory space is a minor secondary use.</p>
|
||||
</blockquote>
|
||||
<p><b>Why bother with binary I/O? Why not just use C++ Standard Library stream
|
||||
inserters and extractors?</b></p>
|
||||
@@ -764,68 +439,71 @@ and 16, 32, and 64-bit aligned integers.</p>
|
||||
</blockquote>
|
||||
|
||||
<h2><a name="Release-history">Release history</a></h2>
|
||||
<h3><a name="Changes-since-formal-review">Changes since formal review</a></h3>
|
||||
<h3><a name="Changes-requested-by-formal-review">Changes requested by formal review</a></h3>
|
||||
<p>The library was reworked from top to bottom to accommodate changes requested
|
||||
during the formal review. See <a href="mini_review_topics.html">Mini-Review</a>
|
||||
page for details.</p>
|
||||
<h3><a name="Other-changes-since-formal-review">Other changes since formal
|
||||
review</a></h3>
|
||||
<ul>
|
||||
<li>
|
||||
<p>The endian types have been decomposed into endian buffer types
|
||||
and endian arithmetic types, as requested. The arithmetic types derive from
|
||||
the buffer types.</li>
|
||||
<li>
|
||||
<p>Headers have been renamed to <code>endian/arithmetic.hpp</code> and
|
||||
<code>endian/conversion.hpp</code>. <code>endian/buffers.hpp</code> has been
|
||||
<li>Header <code>boost/endian/endian.hpp</code> has been renamed to <code>
|
||||
boost/endian/arithmetic.hpp</code>. Headers
|
||||
<code>boost/endian/conversion.hpp</code> and <code>boost/endian/buffers.hpp</code> have been
|
||||
added.
|
||||
Infrastructure file names were changed accordingly.</li>
|
||||
<li>
|
||||
<p>The endian buffer and arithmetic types and endian conversion functions now support 32-bit (<code>float)</code> and
|
||||
64-bit <code>(double)</code> floating point, as requested.</li>
|
||||
<li>The endian types now have stream inserter and extractor templates, as
|
||||
requested.</li>
|
||||
<li>Both the endian types and endian conversion functions now support UDTs, as requested.</li>
|
||||
<li>The endian type aliases have been renamed,
|
||||
using a naming pattern that is consistent for both integer and floating point, .</li>
|
||||
<li>The conversion functions have been much revised,
|
||||
refactored, and otherwise improved based on review comments.<ul>
|
||||
<li>Functions have been renamed to clarify their functionality.</li>
|
||||
<li>Both return-by-value and modify-in-place interfaces are provided, as
|
||||
requested.</li>
|
||||
<li>In addition to the named-endianness functions, functions that perform
|
||||
compile-time (via template) and run-time (via function argument) dispatch
|
||||
are now provided, as requested.</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Compiler (Clang, GCC, VisualC++, etc.) intrinsics and built-in functions
|
||||
are used in the implementation where appropriate, as requested.</li>
|
||||
<li>For the endian types, the implementation uses the endian conversion functions,
|
||||
and thus the intrinsics,
|
||||
as requested.</li>
|
||||
<li><code>order::native</code> is now a synonym for <code>order::big</code>
|
||||
or <code>order::little</code> according to the endianness of the platform, as
|
||||
requested. This reduces the number of template specializations required.</li>
|
||||
<li>The endian arithmetic type aliases have been renamed,
|
||||
using a naming pattern that is consistent for both integer and floating point,
|
||||
and a consistent set of aliases supplied for the endian buffer types.</li>
|
||||
<li>The aligned-type alias names now have the <code>_t</code> suffix, for
|
||||
consistency with the standard library integer type aliases and because use of
|
||||
aligned types is much more common than unaligned types.</li>
|
||||
<li>The unaligned-type alias names now have the <code>_ut</code> suffix. This
|
||||
is short, yet stands out enough to alert the reader than unusual types are
|
||||
involved.</li>
|
||||
<li><code>endian_reverse()</code> overloads for <code>int8_t</code> and <code>
|
||||
uint8_t</code> have been added for improved generality. (Pierre Talbot)</li>
|
||||
<li>Overloads of <code>endian_reverse_inplace()</code> have been replaced with a single <code>
|
||||
endian_reverse_inplace()</code> template. (Pierre Talbot)</li>
|
||||
<li>C++11 features such as <code>noexcept</code> are now used, while still
|
||||
supporting C++03 compilers.</li>
|
||||
<li>Headers have been reorganized to make them easier to read,
|
||||
with a synopsis at the front and implementation following, as requested.</li>
|
||||
<li>Documentation has been revised to address most, but not all, concerns
|
||||
raised during formal review.</li>
|
||||
<li>For X86 and X64 architectures, which permit unaligned loads and stores,
|
||||
unaligned little endian buffer and arithmetic types use regular loads and
|
||||
stores when the size is exact. This makes unaligned little endian buffer and
|
||||
arithmetic types significantly more efficient on these architectures. (Jeremy
|
||||
Maitin-Shepard)</li>
|
||||
<li>C++11 features affecting interfaces, such as <code>noexcept</code>, are now used.
|
||||
C++03 compilers are still
|
||||
supported.</li>
|
||||
<li>Acknowledgements have been updated.</li>
|
||||
</ul>
|
||||
|
||||
<h2><a name="Compatibility">Compatibility</a> with interim releases</h2>
|
||||
|
||||
<p dir="ltr">Prior to the official Boost release, class template <code>
|
||||
endian_arithmetic</code> has been used for a decade or more with the same
|
||||
functionality but under the name <code>endian</code>. Other names also changed
|
||||
in the official release. If the macro <code>BOOST_ENDIAN_DEPRECATED_NAMES</code>
|
||||
is defined, those old now deprecated names are still supported. However, the
|
||||
class template <code>endian</code> name is only provided for compilers
|
||||
supporting C++11 template aliases. For C++03 compilers, the name will have to be
|
||||
changed to <code>endian_arithmetic</code>.</p>
|
||||
|
||||
<p>To support backward header compatibility, deprecated header <code>boost/endian/endian.hpp</code>
|
||||
forwards to <code>boost/endian/arithmetic.hpp</code>. It requires <code>
|
||||
BOOST_ENDIAN_DEPRECATED_NAMES</code> be defined. It should only be used while
|
||||
transitioning to the official Boost release of the library as it will be removed
|
||||
in some future release.</p>
|
||||
|
||||
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
|
||||
<p>Comments and suggestions were received from Adder, Benaka Moorthi,
|
||||
Christopher Kohlhoff, Cliff Green, Daniel James, Gennaro Proto, Giovanni Piero
|
||||
Deretta, Gordon Woodhull, dizzy, Hartmut Kaiser, Jeff Flinn, John Filo, John
|
||||
Deretta, Gordon Woodhull, dizzy, Hartmut Kaiser, Jeff Flinn, Jeremy Maitin-Shepard, John Filo, John
|
||||
Maddock, Kim Barrett, Marsh Ray, Martin Bonner, Mathias Gaunard, Matias
|
||||
Capeletto, Neil Mayhew, Paul Bristow, Pierre Talbot, Phil Endecott, Pyry Jahkola,
|
||||
Rene Rivera, Robert Stewart, Roland Schwarz, Scott McMurray, Sebastian Redl, Tim
|
||||
Blechmann, Tim Moore, tymofey, Tomas Puverle, Vincente Botet, Yuval Ronen and
|
||||
Vitaly Budovski,.</p>
|
||||
Vitaly Budovsk. Apologies if anyone has been missed.</p>
|
||||
<hr>
|
||||
<p>Last revised:
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->17 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38647" --></p>
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->19 January, 2015<!--webbot bot="Timestamp" endspan i-checksum="38903" --></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>
|
||||
|
||||
@@ -9,34 +9,60 @@
|
||||
<link href="styles.css" rel="stylesheet">
|
||||
<body>
|
||||
|
||||
<p>Here is what needs to be done to get the library ready for a mini-review:
|
||||
<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
|
||||
<tr>
|
||||
<td width="339">
|
||||
<a href="../../../index.html">
|
||||
<img src="../../../boost.png" alt="Boost logo" align="middle" border="0" width="277" height="86"></a></td>
|
||||
<td align="middle" width="1253">
|
||||
<b>
|
||||
<font size="6">Endian </font></b><font size="6"><b>Mini-Review</b></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.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>
|
||||
|
||||
<p>The results of the Boost.Endian formal review included a list of issues to be
|
||||
resolved before a mini-review.</p>
|
||||
|
||||
</p>
|
||||
<p>The issues are shown in <b>bold</b> below, with the resolution indicated.</p>
|
||||
|
||||
<p><b>Common use case scenarios should be developed.</b></p>
|
||||
<p><b>1. Common use case scenarios should be developed.</b></p>
|
||||
<blockquote>
|
||||
|
||||
<p>Done. See <a href="index.html#Use-cases">Use cases</a>.</p>
|
||||
<p>Done. The documentation have been refactored. A page is now devoted to
|
||||
<a href="choosing_approach.html">Choosing the Approach</a> to endianness. See
|
||||
<a href="choosing_approach.html#Use-cases">Use cases</a> for use case
|
||||
scenarios.</p>
|
||||
</blockquote>
|
||||
<p><b>Example programs should be developed for the common use case scenarios.</b></p>
|
||||
<p><b>2. Example programs should be developed for the common use case scenarios.</b></p>
|
||||
<blockquote>
|
||||
<p> </p>
|
||||
<p>Done. See <a href="choosing_approach.html">Choosing the Approach</a>.
|
||||
Example code has been added throughout.</p>
|
||||
</blockquote>
|
||||
<p><b>Documentation should illuminate the differences between endian
|
||||
<p><b>3. Documentation should illuminate the differences between endian
|
||||
integer/float type and endian conversion approaches to the common use
|
||||
case scenarios, and provide guidelines for choosing the most appropriate
|
||||
approach in user's applications.</b></p>
|
||||
<blockquote>
|
||||
<p>Done. See <a href="index.html#Choosing">Choosing between endian conversion
|
||||
functions, endian buffer types, and endian arithmetic types</a>.</p>
|
||||
<p>Done. See <a href="choosing_approach.html">Choosing the Approach</a>.</p>
|
||||
</blockquote>
|
||||
<p><b>Conversion functions supplying results via return should be provided.</b></p>
|
||||
<p><b>4 .Conversion functions supplying results via return should be provided.</b></p>
|
||||
<blockquote>
|
||||
<p>Done. See <a href="conversion.html">conversion docs</a>.</p>
|
||||
<p>Done. See <a href="conversion.html">ConversionFunctions</a>.</p>
|
||||
</blockquote>
|
||||
<p><b>Platform specific performance enhancements such as use of compiler intrinsics or relaxed alignment requirements should be supported.</b></p>
|
||||
<p><b>5. Platform specific performance enhancements such as use of compiler intrinsics or relaxed alignment requirements should be supported.</b></p>
|
||||
<blockquote>
|
||||
<p>Done. Compiler (Clang, GCC, VisualC++, etc.) intrinsics and built-in
|
||||
functions are used in the implementation where appropriate, as requested. See
|
||||
@@ -44,7 +70,7 @@ approach in user's applications.</b></p>
|
||||
<a href="index.html#Timings">Timings for Example 2</a> to gauge the impact of
|
||||
intrinsics.</p>
|
||||
</blockquote>
|
||||
<p><b>Endian integer (and floating) types should be implemented via the
|
||||
<p><b>6. Endian integer (and floating) types should be implemented via the
|
||||
conversion functions. If that can't be done efficiently, consideration
|
||||
should be given to expanding the conversion function signatures to
|
||||
resolve the inefficiencies.</b></p>
|
||||
@@ -52,7 +78,7 @@ resolve the inefficiencies.</b></p>
|
||||
<p>Done. For the endian types, the implementation uses the endian conversion
|
||||
functions, and thus the intrinsics, as requested.</p>
|
||||
</blockquote>
|
||||
<p><b>Benchmarks that measure performance should be provided. It should be
|
||||
<p><b>7. Benchmarks that measure performance should be provided. It should be
|
||||
possible to compare platform specific performance enhancements against
|
||||
portable base implementations, and to compare endian integer approaches
|
||||
against endian conversion approaches for the common use case scenarios.</b></p>
|
||||
@@ -60,7 +86,7 @@ against endian conversion approaches for the common use case scenarios.</b></p>
|
||||
<p>Done. See <a href="index.html#Timings">Timings for Example 2</a>. The <code>endian/test</code> directory
|
||||
also contains several additional benchmark and speed test programs.</p>
|
||||
</blockquote>
|
||||
<p><b>Float (32-bits) and double (64-bits) should be supported. IEEE 754 is
|
||||
<p><b>8. Float (32-bits) and double (64-bits) should be supported. IEEE 754 is
|
||||
the primary use case.</b></p>
|
||||
<blockquote>
|
||||
<p>Done. The <a href="buffers.html">endian buffer types</a>,
|
||||
@@ -68,12 +94,13 @@ the primary use case.</b></p>
|
||||
<a href="conversion.html">endian conversion functions</a> now support 32-bit (<code>float)</code>
|
||||
and 64-bit <code>(double)</code> floating point, as requested.</p>
|
||||
</blockquote>
|
||||
<p><b>Support for user defined types (UDTs) is desirable, and should be
|
||||
<p><b>9. Support for user defined types (UDTs) is desirable, and should be
|
||||
provided where there would be no conflict with the other concerns.</b></p>
|
||||
<blockquote>
|
||||
<p>Done. See <a href="conversion.html#Requirements">conversion requirements</a>.</p>
|
||||
<p>Done. See <a href="conversion.html#Customization-points">Customization
|
||||
points for user-defined types (UDTs)</a>.</p>
|
||||
</blockquote>
|
||||
<p><b>There is some concern that endian integer/float arithmetic operations
|
||||
<p><b>10. There is some concern that endian integer/float arithmetic operations
|
||||
might used inadvertently or inappropriately. The impact of adding an endian_buffer
|
||||
class without arithmetic operations should be investigated.</b></p>
|
||||
<blockquote>
|
||||
@@ -83,23 +110,37 @@ might used inadvertently or inappropriately. The impact of adding an endian_buff
|
||||
<code>endian_buffer</code> is a public base class for <code>endian_arithmetic</code>,
|
||||
and can also be used by users as a stand-alone class.</p>
|
||||
</blockquote>
|
||||
<p><b>Stream insertion and extraction of the endian integer/float types should
|
||||
<p><b>11. Stream insertion and extraction of the endian integer/float types should
|
||||
be documented and included in the test coverage.</b></p>
|
||||
<blockquote>
|
||||
<p>Done. See <a href="types.html#Stream-inserter">Stream inserter</a> and
|
||||
<a href="types.html#Stream-extractor">Stream extractor</a>.</p>
|
||||
<p>Done. See <a href="buffers.html#Stream-inserter">Stream inserter</a> and
|
||||
<a href="buffers.html#Stream-extractor">Stream extractor</a>.</p>
|
||||
</blockquote>
|
||||
<p><b>Binary I/O support that was investigated during development of the Endian
|
||||
<p><b>12. Binary I/O support that was investigated during development of the Endian
|
||||
library should be put up for mini-review for inclusion in the Boost I/O
|
||||
library.</b></p>
|
||||
|
||||
<blockquote>
|
||||
<p> </p>
|
||||
<p>Not done yet. Will be handled as a separate min-review soon after the
|
||||
Endian mini-review.</p>
|
||||
|
||||
</blockquote>
|
||||
<p><b>13. Other requested changes.</b></p>
|
||||
|
||||
<blockquote>
|
||||
<ul>
|
||||
<li>In addition to the named-endianness conversion functions, functions that perform
|
||||
compile-time (via template) and run-time (via function argument) dispatch
|
||||
are now provided.</li>
|
||||
<li><code>order::native</code> is now a synonym for <code>order::big</code>
|
||||
or <code>order::little</code> according to the endianness of the platform. This reduces the number of template specializations required.</li>
|
||||
<li>Headers have been reorganized to make them easier to read,
|
||||
with a synopsis at the front and implementation following.</li>
|
||||
</ul>
|
||||
</blockquote>
|
||||
<hr>
|
||||
<p>Last revised:
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->17 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38647" --></p>
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->19 January, 2015<!--webbot bot="Timestamp" endspan i-checksum="38903" --></p>
|
||||
<p>© Copyright Beman Dawes, 2014</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>
|
||||
|
||||
@@ -3,6 +3,7 @@ body
|
||||
{
|
||||
font-family: sans-serif;
|
||||
max-width: 6.5in;
|
||||
margin: 0px auto;
|
||||
font-size: 85%;
|
||||
}
|
||||
ins {background-color: #CCFFCC;}
|
||||
@@ -12,7 +13,7 @@ body
|
||||
table{font-size: 100%;}
|
||||
|
||||
/*
|
||||
© Copyright Beman Dawes, 2014
|
||||
<EFBFBD> Copyright Beman Dawes, 2014
|
||||
Distributed under the Boost Software License, Version 1.0.
|
||||
See www.boost.org/LICENSE_1_0.txt
|
||||
*/
|
||||
|
||||
134
todo_list.html
134
todo_list.html
@@ -12,23 +12,9 @@
|
||||
|
||||
<h1>Endian Library TODO List</h1>
|
||||
|
||||
<p>Last revised:
|
||||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->17 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38647" --></p>
|
||||
|
||||
<p><b>August 12, 2014: The many items that have been completed should be
|
||||
removed, after verifying that they are in fact taken care of.</b></p>
|
||||
<h2>To Do</h2>
|
||||
<ul>
|
||||
<li>Develop the use-cases example programs, using plain integers and UDT's.</li>
|
||||
<li>Review UDT examples.</li>
|
||||
<li>Review buffer stream extractors and inserters, and how they work for
|
||||
arithmetic types. TEST. Make sure nothing got dropped on the floor during
|
||||
buffer decomposition.</li>
|
||||
<li><span style="background-color: #FFFF00">Run inspect.</span>
|
||||
</li>
|
||||
</ul>
|
||||
<h2>Format Review Comments</h2>
|
||||
<h3 dir="ltr">Votes</h3>
|
||||
<h3 dir="ltr">Interesting</h3>
|
||||
<ul>
|
||||
<li dir="ltr">
|
||||
<p dir="ltr">John Filo - "Absolutely. I'd like to see support for float and
|
||||
@@ -52,26 +38,6 @@ removed, after verifying that they are in fact taken care of.</b></p>
|
||||
Spirit with the reviewed version. All of Spirits regression tests still <br>
|
||||
pass. "<br>
|
||||
</li>
|
||||
<li dir="ltr">
|
||||
<p dir="ltr">Robert Stewart - "There are issues that keep me from saying yes
|
||||
at this time. There are too many suggested variations and ideas under
|
||||
consideration to accept the library in its present state. However, a
|
||||
mini-review should be sufficient to evaluate the final form, once Beman
|
||||
determines a course of action, and determine whether to accept it or not."<br>
|
||||
</li>
|
||||
<li dir="ltr">
|
||||
<p dir="ltr">Tim Blechmann - "the library should be accepted, if<br>
|
||||
<br>
|
||||
(a) the interface of the conversion functions is changed<br>
|
||||
(b) the performance can be improved<br>
|
||||
(c) the documentation integrates better with the rest of the boost<br>
|
||||
documentation."<br>
|
||||
</li>
|
||||
<li dir="ltr">
|
||||
<p dir="ltr">Vicente J. Botet Escriba - "No in its current state.<br>
|
||||
Once the library takes in account the requested modification (that Beman has
|
||||
already accepted) a mini-review will be necessary to improve the library
|
||||
before release."</li>
|
||||
</ul>
|
||||
<h3>Executive summary</h3>
|
||||
<ul>
|
||||
@@ -109,37 +75,6 @@ removed, after verifying that they are in fact taken care of.</b></p>
|
||||
</ul>
|
||||
<h3>Docs</h3>
|
||||
<ul>
|
||||
<li>Document use of endian integers with stream inserters and extractors.</li>
|
||||
<li>Conversion in note mention similarity to htonl() , etc.</li>
|
||||
<li>Conversion: add discussion of alignment, packing, etc. Bottom line; use at
|
||||
your own risk. Use Phil's example:<br>
|
||||
struct S {<br>
|
||||
uint16_t a;<br>
|
||||
uint32_t b;<br>
|
||||
} __attribute__ ((packed));</li>
|
||||
<li>Requirements for template parameters. </li>
|
||||
<li>UDTs<ul>
|
||||
<li>Integers</li>
|
||||
<li>Conversion</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Distinguish use cases and recommendations for which approach (integers vs
|
||||
conversion) is appropriate.<ul>
|
||||
<li><a href="http://lists.boost.org/Archives/boost/2011/09/185698.php">
|
||||
http://lists.boost.org/Archives/boost/2011/09/185698.php</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>> section `experience': this section gives no insights for people who use
|
||||
or<br>
|
||||
> read the code. it mainly tells: "we are not the first and the domain of the<br>
|
||||
> library is important.". imo this section can be removed (maybe the part that<br>
|
||||
> it is not related to any c library can go to the `design considerations'<br>
|
||||
><br>
|
||||
> section "motivating use cases": this is more a marketing blurb/testimonial.<br>
|
||||
> maybe this could be changed to a section about possible use cases, listing<br>
|
||||
> `communicating between different devices' and `reading/writing of binary
|
||||
file<br>
|
||||
> formats'.</li>
|
||||
<li>one other point ... the help file seems to directly link to the c++
|
||||
headers.<br>
|
||||
this should be changed:<br>
|
||||
@@ -157,75 +92,10 @@ removed, after verifying that they are in fact taken care of.</b></p>
|
||||
<br>
|
||||
so i'd suggest to completely remove the links to the c++ headers.<br>
|
||||
</li>
|
||||
<li>
|
||||
<div class="im">
|
||||
> explaining the other builting types are not considered. Why only
|
||||
big/little<br>
|
||||
> endianness has been taken in account?</div>
|
||||
<p>I'll add FAQ and/or add more entries to the final docs.<br>
|
||||
<br>
|
||||
Only big/little endianness is taken into account because these are the<br>
|
||||
only endian schemes that have any practical value. All the others are<br>
|
||||
just historical curiosities.</li>
|
||||
</ul>
|
||||
<h3>Code</h3>
|
||||
<p>Also change docs if applicable.</p>
|
||||
<ul>
|
||||
<li><span style="background-color: #FFCCFF">Beman: TODO</span><span style="background-color: #FFCCFF">:
|
||||
</span><span style="background-color: #FFCCFF">Google</span><span style="background-color: #FFCCFF">
|
||||
"unaligned integer", look at various entries. For example, http://</span><span style="background-color: #FFCCFF">infocenter.arm.com</span><span style="background-color: #FFCCFF">/help/</span><span style="background-color: #FFCCFF">index.jsp?topic</span><span style="background-color: #FFCCFF">=/</span><span style="background-color: #FFCCFF">com.arm.doc.faqs</span><span style="background-color: #FFCCFF">/ka3544.html</span></li>
|
||||
<li>Beman: Some platforms (compiler/processor taken together) don't require
|
||||
alignment for the conversion functions if code is inlined, although speed may
|
||||
suffer. (test to verify this assertion). On those platforms, conversion
|
||||
functions (perhaps in-place) can be used to implement unaligned integers.<ul>
|
||||
<li>Microsoft <a href="http://msdn.microsoft.com/en-us/library/ms253978.aspx">
|
||||
UNALIGNED / __unaligned</a> keywords for pointers. Also
|
||||
<a href="http://msdn.microsoft.com/en-us/library/ms253935.aspx">Packing
|
||||
Structures</a>.</li>
|
||||
<li>GCC
|
||||
<a href="http://www.mailinglistarchive.com/gcc@gcc.gnu.org/msg21079.html">
|
||||
http://www.mailinglistarchive.com/gcc@gcc.gnu.org/msg21079.html</a></li>
|
||||
<li>Intel performs well on simple unaligned test. See
|
||||
<a href="../test/unaligned_test.cpp">../test/unaligned_test.cpp</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Beman: Does the use of the unrolling templates get in the way of processor
|
||||
specific optimization code?</li>
|
||||
<li>Test use of endian integers with stream inserters and extractors.</li>
|
||||
<li>Continue work on benchmarks and timings. Consider using use-case example
|
||||
programs as benchmarks.</li>
|
||||
<li dir="ltr">
|
||||
<div class="im">
|
||||
> The library should provide in addition endian conversion functions that
|
||||
have<br>
|
||||
> the endiannes as template parameters to make possible generic functions.</div>
|
||||
<p dir="ltr">Compile time dispatch on an endianness enum was also requested in<br>
|
||||
another review. That's fine with me, but I haven't had a chance to<br>
|
||||
figure out the interface details.</li>
|
||||
</ul>
|
||||
<h3>Infrastructure</h3>
|
||||
<ul>
|
||||
<li>
|
||||
<div class="im">
|
||||
> endian_operations_test.cpp and endian_in_union_test.cpp ... maybe rename
|
||||
from<br>
|
||||
> _test.cpp to _compile_test.cpp? they don't seem to do any run-time tests.
|
||||
they<br>
|
||||
> also should not include <cassert> since no assertion statement is needed,
|
||||
this<br>
|
||||
> might speed up the compilation time of the testsuite by something like
|
||||
50ms ;)</div>
|
||||
<p>Will do.</li>
|
||||
<li>Make the bin() functionality available</li>
|
||||
</ul>
|
||||
|
||||
<p>* I'm only willing to provide conversion.hpp FP support. Providing<br>
|
||||
types that mimic FP types is far beyond my knowledge of how to deal<br>
|
||||
with floating point's notorious arithmetic issues.</p>
|
||||
<p>Support IEEE754 format (32 bit, 64 bit) only.</p>
|
||||
<hr>
|
||||
<p>Last revised:
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->17 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38647" --></p>
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->17 January, 2015<!--webbot bot="Timestamp" endspan i-checksum="38899" --></p>
|
||||
<p>© Copyright Beman Dawes, 2012</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