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> <head>
<meta http-equiv="Content-Language" content="en-us"> <meta http-equiv="Content-Language" content="en-us">
@ -17,7 +17,7 @@
<tr> <tr>
<td> <td>
<a href="../../../index.html"> <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"> <td align="middle">
<b> <b>
<font size="6">Endian Arithmetic Types</font> </b> <font size="6">Endian Arithmetic Types</font> </b>
@ -109,10 +109,11 @@ using namespace boost::endian;
namespace namespace
{ {
// This is an extract from a very widely used GIS file format. It seems odd // This is an extract from a very widely used GIS file format.
// to mix big and little endians in the same file - but this is a real-world // Why the designer decided to mix big and little endians in
// format and users wishing to write low level code manipulating these files // the same file is not known. But this is a real-world format
// must deal with the mixed endianness. // and users wishing to write low level code manipulating these
// files have to deal with the mixed endianness.
struct header struct header
{ {
@ -136,11 +137,13 @@ int main(int, char* [])
h.version = 1; h.version = 1;
h.shape_type = 0x01020304; h.shape_type = 0x01020304;
// Low-level I/O such as POSIX read/write or &lt;cstdio&gt; fread/fwrite is sometimes // Low-level I/O such as POSIX read/write or &lt;cstdio&gt;
// used for binary file operations when ultimate efficiency is important. Such // fread/fwrite is sometimes used for binary file operations
// I/O is often performed in some C++ wrapper class, but to drive home the // when ultimate efficiency is important. Such I/O is often
// point that endian integers are often used in fairly low-level code that does // performed in some C++ wrapper class, but to drive home the
// bulk I/O operations, &lt;cstdio&gt; fopen/fwrite is used for I/O in this example. // 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 std::FILE* fi = std::fopen(filename, &quot;wb&quot;); // MUST BE BINARY
@ -205,8 +208,9 @@ enum class align {no, yes}; </pre>
</blockquote> </blockquote>
<p>One class template is provided:</p> <p>One class template is provided:</p>
<blockquote> <blockquote>
<pre>template &lt;order Order, typename T, std::size_t n_bits, align A = align::no&gt; <pre>template &lt;order Order, typename T, std::size_t n_bits,
class endian_arithmetic; align Align = align::no&gt;
class endian_arithmetic;
</pre> </pre>
</blockquote> </blockquote>
<p>Typedefs, such as <code>big_int32_t</code>, provide convenient naming <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}; 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 class endian_arithmetic
: public endian_buffer&lt;Order, T, n_bits, A&gt; : public endian_buffer&lt;Order, T, n_bits, Align&gt;
{ {
public: public:
typedef T value_type; 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; endian_arithmetic&amp; <a href="#operator-eq">operator=</a>(T v) noexcept;
<a href="#operator-T">operator value_type</a>() const noexcept; <a href="#operator-T">operator value_type</a>() const noexcept;
value_type value() 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; // exposition only; see endian_buffer const char* <a href="#data">data</a>() const noexcept; // for exposition; see endian_buffer
// arithmetic operations // arithmetic operations
// note that additional operations are provided by the value_type // note that additional operations are provided by the value_type
@ -417,35 +422,35 @@ usual operations on integers are supplied.</p>
// typedefs // typedefs
// aligned big endian floating point types // aligned big endian floating point types
typedef endian&lt;order::big, float, 32, align::yes&gt; big_float32_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; typedef endian&lt;order::big, double, 64, align::yes&gt; big_float64_t;
// aligned little endian floating point types // aligned little endian floating point types
typedef endian&lt;order::little, float, 32, align::yes&gt; little_float32_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; typedef endian&lt;order::little, double, 64, align::yes&gt; little_float64_t;
// unaligned big endian floating point types // unaligned big endian floating point types
typedef endian&lt;order::big, float, 32, align::no&gt; big_float32un_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_float64un_t; typedef endian&lt;order::big, double, 64, align::no&gt; big_float64_ut;
// unaligned little endian floating point types // unaligned little endian floating point types
typedef endian&lt;order::little, float, 32, align::no&gt; little_float32un_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_float64un_t; typedef endian&lt;order::little, double, 64, align::no&gt; little_float64_ut;
// aligned big endian signed integer types // 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, 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, 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, int64_t, 64, align::yes&gt; big_int64_t;
// aligned big endian unsigned integer types // 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, 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, 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, uint64_t, 64, align::yes&gt; big_uint64_t;
// aligned little endian signed integer types // 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, 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, 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, int64_t, 64, align::yes&gt; little_int64_t;
// aligned little endian unsigned integer types // aligned little endian unsigned integer types
typedef endian&lt;order::little, uint16_t, 16, align::yes&gt; little_uint16_t; 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> suggested supporting floating point types.</p>
<hr> <hr>
<p>Last revised: <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>© Copyright Beman Dawes, 2006-2009, 2013</p>
<p>Distributed under the Boost Software License, Version 1.0. See <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> <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> <tr>
<td> <td>
<a href="../../../index.html"> <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"> <td align="middle">
<b> <b>
<font size="6">Endian Buffer Types</font> </b> <font size="6">Endian Buffer Types</font> </b>
@ -195,8 +195,9 @@ enum class align {no, yes}; </pre>
</blockquote> </blockquote>
<p>One class template is provided:</p> <p>One class template is provided:</p>
<blockquote> <blockquote>
<pre>template &lt;order Order, typename T, std::size_t Nbits, align A = align::no&gt; <pre>template &lt;order Order, typename T, std::size_t Nbits,
class endian_buffer; align Align = align::no&gt;
class endian_buffer;
</pre> </pre>
</blockquote> </blockquote>
<p>Typedefs, such as <code>big_int32_buf_t</code>, provide convenient naming <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}; 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 class endian_buffer
{ {
public: public:
@ -648,7 +650,7 @@ any Boost object libraries.</p>
</ul> </ul>
<hr> <hr>
<p>Last revised: <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>© Copyright Beman Dawes, 2006-2009, 2013</p>
<p>Distributed under the Boost Software License, Version 1.0. See <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> <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> <tr>
<td width="339"> <td width="339">
<a href="../../../index.html"> <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"> <td align="middle" width="1253">
<font size="6"><b>Choosing the Approach</b></font></td> <font size="6"><b>Choosing the Approach</b></font></td>
</tr> </tr>
@ -400,7 +400,7 @@ arithmetic approach</a>.</p>
<hr> <hr>
<p>Last revised: <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>© Copyright Beman Dawes, 2011, 2013, 2014</p>
<p>Distributed under the Boost Software License, Version 1.0. See <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> <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> <head>
<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> <meta name="GENERATOR" content="Microsoft FrontPage 5.0">
@ -15,7 +15,7 @@
<tr> <tr>
<td> <td>
<a href="../../../index.html"> <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"> <td align="middle">
<b> <b>
<font size="6">Endian Conversion Functions</font></b></td> <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> <code>endian_reverse_inplace()</code> implementations.</p>
<hr> <hr>
<p>Last revised: <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>© 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> <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> <tr>
<td width="339"> <td width="339">
<a href="../../../index.html"> <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"> <td align="middle" width="1253">
<b> <b>
<font size="6">Endian Library</font></b></td> <font size="6">Endian Library</font></b></td>
@ -56,6 +56,7 @@
requested by formal review</a><br> requested by formal review</a><br>
&nbsp;&nbsp; <a href="#Other-changes-since-formal-review">Other changes since &nbsp;&nbsp; <a href="#Other-changes-since-formal-review">Other changes since
formal review</a><br> formal review</a><br>
<a href="#Compatibility">Compatibility with interim releases</a><br>
<a href="#Acknowledgements">Acknowledgements</a><br> <a href="#Acknowledgements">Acknowledgements</a><br>
</td> </td>
</tr> </tr>
@ -445,8 +446,9 @@ page for details.</p>
<h3><a name="Other-changes-since-formal-review">Other changes since formal <h3><a name="Other-changes-since-formal-review">Other changes since formal
review</a></h3> review</a></h3>
<ul> <ul>
<li>Headers have been renamed to <code>endian/arithmetic.hpp</code> and <li>Header <code>boost/endian/endian.hpp</code> has been renamed to <code>
<code>endian/conversion.hpp</code>. <code>endian/buffers.hpp</code> has been boost/endian/arithmetic.hpp</code>. Headers
<code>boost/endian/conversion.hpp</code> and <code>boost/endian/buffers.hpp</code> have been
added. added.
Infrastructure file names were changed accordingly.</li> Infrastructure file names were changed accordingly.</li>
<li>The endian arithmetic type aliases have been renamed, <li>The endian arithmetic type aliases have been renamed,
@ -473,6 +475,23 @@ review</a></h3>
<li>Acknowledgements have been updated.</li> <li>Acknowledgements have been updated.</li>
</ul> </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> <h2><a name="Acknowledgements">Acknowledgements</a></h2>
<p>Comments and suggestions were received from Adder, Benaka Moorthi, <p>Comments and suggestions were received from Adder, Benaka Moorthi,
Christopher Kohlhoff, Cliff Green, Daniel James, Gennaro Proto, Giovanni Piero 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> Vitaly Budovsk. Apologies if anyone has been missed.</p>
<hr> <hr>
<p>Last revised: <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>© Copyright Beman Dawes, 2011, 2013</p>
<p>Distributed under the Boost Software License, Version 1.0. See <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> <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> <tr>
<td width="339"> <td width="339">
<a href="../../../index.html"> <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"> <td align="middle" width="1253">
<b> <b>
<font size="6">Endian </font></b><font size="6"><b>Mini-Review</b></font></td> <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 <p><b>11. Stream insertion and extraction of the endian integer/float types should
be documented and included in the test coverage.</b></p> be documented and included in the test coverage.</b></p>
<blockquote> <blockquote>
<p>Done. See <a href="types.html#Stream-inserter">Stream inserter</a> and <p>Done. See <a href="buffers.html#Stream-inserter">Stream inserter</a> and
<a href="types.html#Stream-extractor">Stream extractor</a>.</p> <a href="buffers.html#Stream-extractor">Stream extractor</a>.</p>
</blockquote> </blockquote>
<p><b>12. 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 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> </blockquote>
<hr> <hr>
<p>Last revised: <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>© Copyright Beman Dawes, 2014</p>
<p>Distributed under the Boost Software License, Version 1.0. See <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> <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/ LICENSE_1_0.txt</a></p>