feedc0de/boost_endian
1
0
Fork 0
forked from boostorg/endian
Code Pull Requests Activity

Add docs for BOOST_ENDIAN_DEPRECATED_NAMES compatibility. Fix inspect issues.

Browse Source
This commit is contained in:
Beman
2015-01-19 07:41:28 -05:00
parent adee2fe513
commit 3d814f4f52
6 changed files with 79 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
doc/arithmetic.html
View File

@ -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>
@ -109,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
{
@ -136,11 +137,13 @@ int main(int, char* [])
h.version = 1;
h.shape_type = 0x01020304;
// Low-level I/O such as POSIX read/write or &lt;cstdio&gt; 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, &lt;cstdio&gt; fopen/fwrite is used for I/O in this example.
// Low-level I/O such as POSIX read/write or &lt;cstdio&gt;
// 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, &lt;cstdio&gt;
// fopen/fwrite is used for I/O in this example.
std::FILE* fi = std::fopen(filename, &quot;wb&quot;); // MUST BE BINARY
@ -205,8 +208,9 @@ enum class align {no, yes}; </pre>
</blockquote>
<p>One class template is provided:</p>
<blockquote>
<pre>template &lt;order Order, typename T, std::size_t n_bits, align A = align::no&gt;
class endian_arithmetic;
<pre>template &lt;order Order, typename T, std::size_t n_bits,
align Align = align::no&gt;
class endian_arithmetic;
</pre>
</blockquote>
<p>Typedefs, such as <code>big_int32_t</code>, provide convenient naming
@ -366,9 +370,10 @@ usual operations on integers are supplied.</p>
enum class <a name="alignment">align</a> {no, yes};
template &lt;order Order, class T, std::size_t n_bits, align A = align::no&gt;
template &lt;order Order, class T, std::size_t n_bits,
align Align = align::no&gt;
class endian_arithmetic
: public endian_buffer&lt;Order, T, n_bits, A&gt;
: public endian_buffer&lt;Order, T, n_bits, Align&gt;
{
public:
typedef T value_type;
@ -380,8 +385,8 @@ usual operations on integers are supplied.</p>
endian_arithmetic&amp; <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
@ -417,35 +422,35 @@ usual operations on integers are supplied.</p>
// typedefs
// aligned big endian floating point types
typedef endian&lt;order::big, float, 32, align::yes&gt; big_float32_t;
typedef endian&lt;order::big, double, 64, align::yes&gt; big_float64_t;
typedef endian&lt;order::big, float, 32, align::yes&gt; big_float32_t;
typedef endian&lt;order::big, double, 64, align::yes&gt; big_float64_t;
// aligned little endian floating point types
typedef endian&lt;order::little, float, 32, align::yes&gt; little_float32_t;
typedef endian&lt;order::little, double, 64, align::yes&gt; little_float64_t;
typedef endian&lt;order::little, float, 32, align::yes&gt; little_float32_t;
typedef endian&lt;order::little, double, 64, align::yes&gt; little_float64_t;
// unaligned big endian floating point types
typedef endian&lt;order::big, float, 32, align::no&gt; big_float32un_t;
typedef endian&lt;order::big, double, 64, align::no&gt; big_float64un_t;
typedef endian&lt;order::big, float, 32, align::no&gt; big_float32_ut;
typedef endian&lt;order::big, double, 64, align::no&gt; big_float64_ut;
// unaligned little endian floating point types
typedef endian&lt;order::little, float, 32, align::no&gt; little_float32un_t;
typedef endian&lt;order::little, double, 64, align::no&gt; little_float64un_t;
typedef endian&lt;order::little, float, 32, align::no&gt; little_float32_ut;
typedef endian&lt;order::little, double, 64, align::no&gt; little_float64_ut;
// aligned big endian signed integer types
typedef endian&lt;order::big, int16_t, 16, align::yes&gt; big_int16_t;
typedef endian&lt;order::big, int32_t, 32, align::yes&gt; big_int32_t;
typedef endian&lt;order::big, int64_t, 64, align::yes&gt; big_int64_t;
typedef endian&lt;order::big, int16_t, 16, align::yes&gt; big_int16_t;
typedef endian&lt;order::big, int32_t, 32, align::yes&gt; big_int32_t;
typedef endian&lt;order::big, int64_t, 64, align::yes&gt; big_int64_t;
// aligned big endian unsigned integer types
typedef endian&lt;order::big, uint16_t, 16, align::yes&gt; big_uint16_t;
typedef endian&lt;order::big, uint32_t, 32, align::yes&gt; big_uint32_t;
typedef endian&lt;order::big, uint64_t, 64, align::yes&gt; big_uint64_t;
typedef endian&lt;order::big, uint16_t, 16, align::yes&gt; big_uint16_t;
typedef endian&lt;order::big, uint32_t, 32, align::yes&gt; big_uint32_t;
typedef endian&lt;order::big, uint64_t, 64, align::yes&gt; big_uint64_t;
// aligned little endian signed integer types
typedef endian&lt;order::little, int16_t, 16, align::yes&gt; little_int16_t;
typedef endian&lt;order::little, int32_t, 32, align::yes&gt; little_int32_t;
typedef endian&lt;order::little, int64_t, 64, align::yes&gt; little_int64_t;
typedef endian&lt;order::little, int16_t, 16, align::yes&gt; little_int16_t;
typedef endian&lt;order::little, int32_t, 32, align::yes&gt; little_int32_t;
typedef endian&lt;order::little, int64_t, 64, align::yes&gt; little_int64_t;
// aligned little endian unsigned integer types
typedef endian&lt;order::little, uint16_t, 16, align::yes&gt; little_uint16_t;
@ -672,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 -->17 January, 2015<!--webbot bot="Timestamp" endspan i-checksum="38899" --></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>

12
doc/buffers.html
View File

@ -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>
@ -195,8 +195,9 @@ enum class align {no, yes}; </pre>
</blockquote>
<p>One class template is provided:</p>
<blockquote>
<pre>template &lt;order Order, typename T, std::size_t Nbits, align A = align::no&gt;
class endian_buffer;
<pre>template &lt;order Order, typename T, std::size_t Nbits,
align Align = align::no&gt;
class endian_buffer;
</pre>
</blockquote>
<p>Typedefs, such as <code>big_int32_buf_t</code>, provide convenient naming
@ -356,7 +357,8 @@ usual operations on integers are supplied.</p>
enum class <a name="alignment">align</a> {no, yes};
template &lt;order Order, class T, std::size_t Nbits, align Align = align::no&gt;
template &lt;order Order, class T, std::size_t Nbits,
align Align = align::no&gt;
class endian_buffer
{
public:
@ -648,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 -->17 January, 2015<!--webbot bot="Timestamp" endspan i-checksum="38899" --></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>

4
doc/choosing_approach.html
View File

@ -14,7 +14,7 @@
<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">
<font size="6"><b>Choosing the Approach</b></font></td>
</tr>
@ -400,7 +400,7 @@ arithmetic approach</a>.</p>
<hr>
<p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->17 January, 2015<!--webbot bot="Timestamp" endspan i-checksum="38899" --></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, 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>

6
doc/conversion.html
View File

@ -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>
@ -367,7 +367,7 @@ 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 -->17 January, 2015<!--webbot bot="Timestamp" endspan i-checksum="38899" --></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>

27
doc/index.html
View File

@ -15,7 +15,7 @@
<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>
@ -56,6 +56,7 @@
requested by formal review</a><br>
&nbsp;&nbsp; <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>
@ -445,8 +446,9 @@ page for details.</p>
<h3><a name="Other-changes-since-formal-review">Other changes since formal
review</a></h3>
<ul>
<li>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>The endian arithmetic type aliases have been renamed,
@ -473,6 +475,23 @@ review</a></h3>
<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
@ -484,7 +503,7 @@ Blechmann, Tim Moore, tymofey, Tomas Puverle, Vincente Botet, Yuval Ronen and
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 -->15 January, 2015<!--webbot bot="Timestamp" endspan i-checksum="38895" --></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>

8
doc/mini_review_topics.html
View File

@ -13,7 +13,7 @@
<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 </font></b><font size="6"><b>Mini-Review</b></font></td>
@ -113,8 +113,8 @@ might used inadvertently or inappropriately. The impact of adding an endian_buff
<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>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
@ -140,7 +140,7 @@ might used inadvertently or inappropriately. The impact of adding an endian_buff
</blockquote>
<hr>
<p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04 January, 2015<!--webbot bot="Timestamp" endspan i-checksum="38892" --></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>