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

Change the specification for native ordering to allow implementations to support orderings in addition to big and little. Thanks to Howard Hinnant for suggesting this change and providing draft wording. Also update headers to reflect actual inclusion hierarchy.

Browse Source
This commit is contained in:
Beman
2015-10-16 10:30:34 -04:00
parent 5c26514ded
commit f14f080359
5 changed files with 59 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
doc/arithmetic.html
View File

@ -320,23 +320,19 @@ example:</p>
have identical layout on all platforms, so they never actually reverse endianness. They are provided to enable generic code, and have identical layout on all platforms, so they never actually reverse endianness. They are provided to enable generic code, and
to improve code readability and searchability.</p> to improve code readability and searchability.</p>
<h2><a name="Class_template_endian">Class template <code>endian</code></a><code>_arithmetic</code></h2> <h2><a name="Class_template_endian">Class template <code>endian</code></a><code>_arithmetic</code></h2>
<p>An endian is an integer byte-holder with user-specified <a href="#endianness"> <p>An <code>endian_integer</code> is an integer byte-holder with user-specified <a href="#endianness">
endianness</a>, value type, size, and <a href="#alignment">alignment</a>. The endianness</a>, value type, size, and <a href="#alignment">alignment</a>. The
usual operations on integers are supplied.</p> usual operations on arithmetic types are supplied.</p>
<h3><a name="Synopsis">Synopsis</a></h3> <h3><a name="Synopsis">Synopsis</a></h3>
<pre>namespace boost <pre>#include &lt;boost/endian/conversion.hpp&gt;
#include &lt;boost/endian/buffers.hpp&gt;
namespace boost
{ {
namespace endian namespace endian
{ {
// C++11 features emulated if not available // C++11 features emulated if not available
enum class <a name="order">order</a>
{
big, // big-endian
little, // little-endian
native = <b><i>implementation-defined</i></b> // same as order::big or order::little<b><i>
</i></b>};
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, template &lt;order Order, class T, std::size_t n_bits,
@ -633,7 +629,7 @@ sign partial specialization to correctly extend the sign when cover integer size
differs from endian representation size.</p> differs from endian representation size.</p>
<hr> <hr>
<p>Last revised: <p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->25 March, 2015<!--webbot bot="Timestamp" endspan i-checksum="28920" --></p> <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->14 October, 2015<!--webbot bot="Timestamp" endspan i-checksum="38874" --></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>

26
doc/buffers.html
View File

@ -303,23 +303,17 @@ example:</p>
have identical layout on all platforms, so they never actually reverse endianness. They are provided to enable generic code, and have identical layout on all platforms, so they never actually reverse endianness. They are provided to enable generic code, and
to improve code readability and searchability.</p> to improve code readability and searchability.</p>
<h2><a name="Class_template_endian">Class template <code>endian</code></a><code>_buffer</code></h2> <h2><a name="Class_template_endian">Class template <code>endian</code></a><code>_buffer</code></h2>
<p>An <code>endian_buffer</code> is an integer byte-holder with user-specified <a href="#endianness"> <p>An <code>endian_buffer</code> is a byte-holder for arithmetic types with user-specified <a href="#endianness">
endianness</a>, value type, size, and <a href="#alignment">alignment</a>. The endianness</a>, value type, size, and <a href="#alignment">alignment</a>.</p>
usual operations on integers are supplied.</p>
<h3><a name="Synopsis">Synopsis</a></h3> <h3><a name="Synopsis">Synopsis</a></h3>
<pre>namespace boost <pre>#include &lt;boost/endian/conversion.hpp
namespace boost
{ {
namespace endian namespace endian
{ {
// C++11 features emulated if not available // C++11 features emulated if not available
enum class <a name="order">order</a>
{
big, // big-endian
little, // little-endian
native = <b><i>implementation-defined</i></b> // same as order::big or order::little<b><i>
</i></b>};
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, template &lt;order Order, class T, std::size_t Nbits,
@ -550,14 +544,6 @@ may be faster (as much as 10 to 20 times faster) if the endianness and alignment
the type matches the endianness and alignment requirements of the machine. The code, the type matches the endianness and alignment requirements of the machine. The code,
however, is however, is
likely to be somewhat less portable than with the unaligned types.</p> likely to be somewhat less portable than with the unaligned types.</p>
<p><b>Why provide the arithmetic operations?</b> Providing a full set of operations reduces program
clutter and makes code both easier to write and to read. Consider
incrementing a variable in a record. It is very convenient to write:</p>
<pre wrap> ++record.foo;</pre>
<p wrap>Rather than:</p>
<pre wrap> int temp(record.foo);
++temp;
record.foo = temp;</pre>
<h2><a name="Design">Design</a> considerations for Boost.Endian buffers</h2> <h2><a name="Design">Design</a> considerations for Boost.Endian buffers</h2>
<ul> <ul>
<li>Must be suitable for I/O - in other words, must be memcpyable.</li> <li>Must be suitable for I/O - in other words, must be memcpyable.</li>
@ -604,7 +590,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 -->25 March, 2015<!--webbot bot="Timestamp" endspan i-checksum="28920" --></p> <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->14 October, 2015<!--webbot bot="Timestamp" endspan i-checksum="38874" --></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>

55
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">
@ -68,9 +68,27 @@ ordering. User defined types are also supported.</p>
<p>Functions are implemented <code>inline</code> if appropriate.<code> </code> <p>Functions are implemented <code>inline</code> if appropriate.<code> </code>
For C++03 compilers, <code> noexcept</code> is For C++03 compilers, <code> noexcept</code> is
elided . elided.
Boost scoped enum emulation is used so that the library still works for compilers that do not support scoped enums.</p> Boost scoped enum emulation is used so that the library still works for compilers that do not support scoped enums.</p>
<h3><a name="Definitions">Definitions</a></h3>
<p><b><i>Endianness</i></b> refers to the ordering of bytes within internal or
external integers and other arithmetic data. Most-significant byte first is
called <b><i>big endian</i></b> ordering. Least-significant byte first is called
<b><i>little endian</i></b> ordering. Other orderings are possible and some CPU
architectures support both big and little ordering.</p>
<blockquote>
<p>[<i>Note:</i> The names are derived from
<a href="http://en.wikipedia.org/wiki/Jonathan_Swift" title="Jonathan Swift">
Jonathan Swift</a>'s satirical novel <i>
<a href="http://en.wikipedia.org/wiki/Gulliver's_Travels" title="Gulliver's Travels">
Gulliver’s Travels</a></i>, where rival kingdoms opened their soft-boiled eggs
at different ends. Wikipedia has an extensive description of
<a href="https://en.wikipedia.org/wiki/Endianness">Endianness</a>. <i>—end note</i>]</p>
</blockquote>
<p>The standard integral types (C++std 3.9.1) except <code>bool</code>
are collectively called the <b> <i>endian types</i></b>.</p>
<h3> <h3>
Header <code>&lt;boost/endian/conversion.hpp&gt;</code> Header <code>&lt;boost/endian/conversion.hpp&gt;</code>
<a name="Synopsis">Synopsis</a></h3> <a name="Synopsis">Synopsis</a></h3>
@ -84,10 +102,10 @@ namespace endian
{ {
enum class <a name="order">order</a> enum class <a name="order">order</a>
{ {
big, // big endian native = <b><i>see below,
little, // little endian </i></b> big = <b><i>see below</i></b>,
native = <b><i>implementation-defined-as-big-or-little little = <b><i>see below</i></b>,
</i></b>}; <b><i> </i></b>};
int8_t <a href="#endian_reverse">endian_reverse</a>(int8_t x) noexcept; int8_t <a href="#endian_reverse">endian_reverse</a>(int8_t x) noexcept;
int16_t <a href="#endian_reverse">endian_reverse</a>(int16_t x) noexcept; int16_t <a href="#endian_reverse">endian_reverse</a>(int16_t x) noexcept;
@ -131,16 +149,20 @@ namespace endian
} // namespace endian } // namespace endian
} // namespace boost</pre> } // namespace boost</pre>
<p dir="ltr">The implementation is required to define the <code>enum class order</code> <p>The values of <code>order::little</code> and <code>order::big</code> shall
constant <code>native</code> as not be equal to one another. </p>
<code>big</code> on big endian platforms and <code>little</code> on little <p><a name="native-order-specification"></a>The value of <code>order::native</code>
endian platforms.</p> shall be:</p>
<h3 dir="ltr"><a name="Definitions">Definitions</a></h3> <ul>
<p dir="ltr">The standard integral types (C++std 3.9.1) except <code>bool</code>, <li>equal to <code>order::big</code> if the execution environment is big
are collectively called the <i>endian types</i>.</p> endian, otherwise</li>
<li>equal to <code>order::little</code> if the execution environment is little
endian, otherwise</li>
<li>unequal to both <code>order::little</code> and <code>order::big</code>.</li>
</ul>
<h3><a name="Requirements">Requirements</a></h3> <h3><a name="Requirements">Requirements</a></h3>
<h4><a name="Template-argument-requirements">Template argument requirements</a></h4> <h4><a name="Template-argument-requirements">Template argument requirements</a></h4>
<p dir="ltr">The template definitions in the <code>boost/endian/conversion.hpp</code> <p>The template definitions in the <code>boost/endian/conversion.hpp</code>
header refer to various named requirements whose details are set out in the header refer to various named requirements whose details are set out in the
tables in this subsection. In these tables, <code>T</code> is an object or tables in this subsection. In these tables, <code>T</code> is an object or
reference type to be supplied by a C++ program instantiating a template; <code>x</code> reference type to be supplied by a C++ program instantiating a template; <code>x</code>
@ -232,7 +254,7 @@ uint16_t endian_reverse(uint16_t x) noexcept;
uint32_t endian_reverse(uint32_t x) noexcept; uint32_t endian_reverse(uint32_t x) noexcept;
uint64_t endian_reverse(uint64_t x) noexcept;</pre> uint64_t endian_reverse(uint64_t x) noexcept;</pre>
<blockquote> <blockquote>
<p dir="ltr"><i>Returns:</i> <i><code>x</code></i>, with the order of its <p><i>Returns:</i> <i><code>x</code></i>, with the order of its
constituent bytes reversed.</p> constituent bytes reversed.</p>
<p><i>Remarks:</i> The type of <i><code>x</code></i> meets the <code>EndianReversible</code> requirements.</p> <p><i>Remarks:</i> The type of <i><code>x</code></i> meets the <code>EndianReversible</code> requirements.</p>
<p>[<i>Note:</i> The Boost.Endian library does not provide overloads for the C++ standard library <p>[<i>Note:</i> The Boost.Endian library does not provide overloads for the C++ standard library
@ -373,7 +395,8 @@ that became the starting point for <b><code>boost/endian/detail/intrinsic.hpp</c
Pierre Talbot provided the <code>int8_t endian_reverse()</code> and templated 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: <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->21 July, 2015<!--webbot bot="Timestamp" endspan i-checksum="21136" --></p> <p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->14 October, 2015<!--webbot bot="Timestamp" endspan i-checksum="38874" --></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>

11
doc/index.html
View File

@ -433,11 +433,14 @@ CPU's. The <a href="http://en.wikipedia.org/wiki/Endian">Wikipedia</a> article
gives more pros and cons.</p> gives more pros and cons.</p>
</blockquote> </blockquote>
<p><b>Why are only big, little, and native endianness supported?</b></p> <p><b>Why are only big and little native endianness supported?</b></p>
<blockquote> <blockquote>
<p>These are the only endian schemes that have any practical value today. PDP-11 <p>These are the only endian schemes that have any practical value today. PDP-11
and the other middle endian approaches are interesting historical curiosities and the other middle endian approaches are interesting historical curiosities
but have no relevance to today&#39;s C++ developers.</p> but have no relevance to today&#39;s C++ developers. The
<a href="conversion.html#native-order-specification">specification for native
ordering</a> is carefully crafted to allow implementations to support other
orderings, thanks to Howard Hinnant. </p>
</blockquote> </blockquote>
<p><b>Why do both the buffer and arithmetic types exist?</b></p> <p><b>Why do both the buffer and arithmetic types exist?</b></p>
@ -596,7 +599,7 @@ and subsequent replies.</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, Dave Handley, Gennaro Proto, Giovanni Piero Christopher Kohlhoff, Cliff Green, Daniel James, Dave Handley, Gennaro Proto, Giovanni Piero
Deretta, Gordon Woodhull, dizzy, Hartmut Kaiser, Jason Newton, Jeff Flinn, Jeremy Maitin-Shepard, John Filo, John Deretta, Gordon Woodhull, dizzy, Hartmut Kaiser, Howard Hinnant, Jason Newton, Jeff Flinn, Jeremy Maitin-Shepard, John Filo, John
Maddock, Kim Barrett, Marsh Ray, Martin Bonner, Mathias Gaunard, Matias Maddock, Kim Barrett, Marsh Ray, Martin Bonner, Mathias Gaunard, Matias
Capeletto, Neil Mayhew, Nevin Liber, Capeletto, Neil Mayhew, Nevin Liber,
Olaf van der Spek, Paul Bristow, Peter Dimov, Pierre Talbot, Phil Endecott, Olaf van der Spek, Paul Bristow, Peter Dimov, Pierre Talbot, Phil Endecott,
@ -606,7 +609,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 -->10 April, 2015<!--webbot bot="Timestamp" endspan i-checksum="29949" --></p> <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->14 October, 2015<!--webbot bot="Timestamp" endspan i-checksum="38874" --></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>

3
include/boost/endian/conversion.hpp
View File

@ -23,7 +23,6 @@ namespace boost
{ {
namespace endian namespace endian
{ {
#ifndef BOOST_ENDIAN_ORDER_ENUM_DEFINED
BOOST_SCOPED_ENUM_START(order) BOOST_SCOPED_ENUM_START(order)
{ {
big, little, big, little,
@ -33,8 +32,6 @@ namespace endian
native = little native = little
# endif # endif
}; BOOST_SCOPED_ENUM_END }; BOOST_SCOPED_ENUM_END
# define BOOST_ENDIAN_ORDER_ENUM_DEFINED
#endif
//--------------------------------------------------------------------------------------// //--------------------------------------------------------------------------------------//
// // // //