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

Apply mini-review editorial fixes from Rob Stewart, mostly just accepting his suggested wording.

Browse Source
This commit is contained in:
Beman
2015-02-17 11:21:21 -05:00
parent 8b7a140f0e
commit c62aa232e1
3 changed files with 52 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
doc/arithmetic.html
View File

@ -384,7 +384,7 @@ usual operations on integers are supplied.</p>
public:
typedef T value_type;
// if BOOST_ENDIAN_FORCE_PODNESS is defined &amp;&amp; C++11 POD's are not
// if BOOST_ENDIAN_FORCE_PODNESS is defined &amp;&amp; C++11 PODs are not
// available then these two constructors will not be present
<a href="#endian">endian_arithmetic</a>() noexcept = default;
<a href="#explicit-endian">endian_arithmetic</a>(T v) noexcept;
@ -599,9 +599,9 @@ FAQ.</p>
conversion for every object involved in I/O. Endian integers require no
conversion or copying. They are already in the desired format for binary I/O.
Thus they can be read or written in bulk.</p>
<p><b>Are endian types POD's?</b> Yes for C++11. No for C++03, although several
<p><b>Are endian types PODs?</b> Yes for C++11. No for C++03, although several
<a href="#Compilation">macros</a> are available to force PODness in all cases.</p>
<p><b>What are the implications of endian integer types not being POD's with C++03
<p><b>What are the implications of endian integer types not being PODs with C++03
compilers?</b> They
can't be used in unions. Also, compilers aren't required to align or lay
out storage in portable ways, although this potential problem hasn't prevented
@ -657,14 +657,14 @@ places. Using Boost.Endian simplifies and cleans the code wonderfully.&quot;</p>
<p>The availability of the C++11
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">
Defaulted Functions</a> feature is detected automatically, and will be used if
present to ensure that objects of <code>class endian</code> are trivial, and
thus POD's.</p>
present to ensure that objects of <code>class endian_arithmetic</code> are trivial, and
thus PODs.</p>
<h2><a name="Compilation">Compilation</a></h2>
<p>Boost.Endian is implemented entirely within headers, with no need to link to
any Boost object libraries.</p>
<p>Several macros allow user control over features:</p>
<ul>
<li>BOOST_ENDIAN_NO_CTORS causes <code>class endian</code> to have no
<li>BOOST_ENDIAN_NO_CTORS causes <code>class endian_arithmetic</code> to have no
constructors. The intended use is for compiling user code that must be
portable between compilers regardless of C++11
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">
@ -673,13 +673,14 @@ any Boost object libraries.</p>
<li>BOOST_ENDIAN_FORCE_PODNESS causes BOOST_ENDIAN_NO_CTORS to be defined if
the compiler does not support C++11
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">
Defaulted Functions</a>. This is ensures that , and so can be used in unions.
In C++11, <code>class endian</code> objects are POD's even though they have
constructors.</li>
Defaulted Functions</a>. This is ensures that objects of <code>class endian_arithmetic</code>
are PODs, and so can be used in C++03 unions.
In C++11, <code>class endian_arithmetic</code> objects are PODs, even though they have
constructors, so can always be used in unions.</li>
</ul>
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
<p>Original design developed by Darin Adler based on classes developed by Mark
Borgerding. Four original class templates combined into a single <code>endian</code>
Borgerding. Four original class templates combined into a single <code>endian_arithmetic</code>
class template by Beman Dawes, who put the library together, provided
documentation, added the typedefs, and also added the <code>unrolled_byte_loops</code>
sign partial specialization to correctly extend the sign when cover integer size
@ -687,7 +688,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 -->12 February, 2015<!--webbot bot="Timestamp" endspan i-checksum="40531" --></p>
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->17 February, 2015<!--webbot bot="Timestamp" endspan i-checksum="40541" --></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>

51
doc/buffers.html
View File

@ -62,7 +62,8 @@
</tr>
</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
<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
@ -85,7 +86,7 @@ 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 <b><code>example/endian_example.cpp</code></b> program writes a
binary file containing four byte big-endian and little-endian integers:</p>
binary file containing four-byte, big-endian and little-endian integers:</p>
<blockquote>
<pre>#include &lt;iostream&gt;
#include &lt;cstdio&gt;
@ -115,10 +116,10 @@ namespace
int main(int, char* [])
{
BOOST_STATIC_ASSERT(sizeof(header) == 16U); // reality check
header h;
BOOST_STATIC_ASSERT(sizeof(h) == 16U); // reality check
h.file_code = 0x01020304;
h.file_length = sizeof(header);
h.version = 1;
@ -172,10 +173,10 @@ been no real-world use cases presented for other sizes.</p>
because it has constructors, private data members, and a base class. This means
that common use cases are relying on unspecified behavior in that the C++
Standard does not guarantee memory layout for non-POD types. This has not been a
problem in practice since all known C++ compilers do layout memory as if <code>
problem in practice since all known C++ compilers lay out memory as if <code>
endian</code> were a POD type. In C++11, it is possible to specify the
default constructor as trivial, and private data members and base classes will
no longer disqualify a type from being a POD. Thus under C++11, <code>endian_buffer</code>
default constructor as trivial, and private data members and base classes no longer disqualify a type from being a POD
type. Thus under C++11, <code>endian_buffer</code>
will no longer be relying on unspecified behavior.</p>
<h2><a name="Feature-set">Feature set</a></h2>
<ul>
@ -332,7 +333,8 @@ memory, files, and network transmissions. </p>
Code that uses a</span>ligned types is possibly non-portable because alignment
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
integer may be to a 32-bit boundary on a 32-bit machine and to a 64-bit boundary
on a 64-bit machine. Furthermore, aligned types
are only available on architectures with 8, 16, 32, and 64-bit integer types. </p>
<p><i><b>Recommendation:</b></i> Prefer unaligned endian types.</p>
<p><i><b>Recommendation:</b></i> Protect yourself against alignment ills. For
@ -341,7 +343,7 @@ example:</p>
<pre>static_assert(sizeof(containing_struct) == 12, &quot;sizeof(containing_struct) is wrong&quot;); </pre>
</blockquote>
<p><b><i>Note:</i></b> One-byte big and little buffer types
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>
<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">
@ -518,7 +520,7 @@ greater or equal to <span style="font-size: 85%"> <code>Nbits</code>.</span></p>
<h3><a name="Members">Members</a></h3>
<pre><code><a name="endian">endian</a>_buffer() noexcept = default;</code></pre>
<blockquote>
<p><i>Effects:</i> Constructs an object of type <code>endian_buffer&lt;Order, T,
<p><i>Effects:</i> Constructs an uninitialized object of type <code>endian_buffer&lt;Order, T,
Nbits, Align&gt;</code>.</p>
</blockquote>
<pre><code>explicit <a name="explicit-endian">endian</a>_buffer(T v) noexcept;</code></pre>
@ -529,25 +531,25 @@ Nbits, Align&gt;</code>.</p>
is a constant of type <code>value_type</code> with <code>Nbits</code> low-order
bits set to one.</p>
<p><i>Remarks:</i> If <code>Align</code> is <code>align::yes</code> then
endianness conversion if required is performed by <code>
endianness conversion, if required, is performed by <code>
boost::endian::endian_reverse</code>.</p>
</blockquote>
<pre><code>endian_buffer&amp; <a name="operator-eq">operator=</a>(T v) noexcept;</code></pre>
<blockquote>
<p><i>Postcondition:</i> <code>value() == v &amp; mask</code>, where <code>mask</code>
is a constant of type <code>value_type</code> with <code>Nbits</code>
low-order bits set to one..</p>
low-order bits set to one.</p>
<p><i>Returns:</i> <code>*this</code>.</p>
<p><i>Remarks:</i> If <code>Align</code> is <code>align::yes</code> then
endianness conversion if required is performed by <code>
endianness conversion, if required, is performed by <code>
boost::endian::endian_reverse</code>.</p>
</blockquote>
<pre>value_type <a name="value">value</a>()<code> const noexcept;</code></pre>
<blockquote>
<p><i>Returns:</i> <code>endian_value</code>, converted to <code>value_type</code>
if necessary and having the endianness of the native platform.</p>
if required, and having the endianness of the native platform.</p>
<p><i>Remarks:</i> If <code>Align</code> is <code>align::yes</code> then
endianness conversion if required is performed by <code>
endianness conversion, if required, is performed by <code>
boost::endian::endian_reverse</code>.</p>
</blockquote>
<pre><code>const char* <a name="data">data</a>() const noexcept;</code></pre>
@ -587,9 +589,9 @@ FAQ.</p>
conversion for every object involved in I/O. Endian integers require no
conversion or copying. They are already in the desired format for binary I/O.
Thus they can be read or written in bulk.</p>
<p><b>Are endian types POD's?</b> Yes for C++11. No for C++03, although several
<p><b>Are endian types PODs?</b> Yes for C++11. No for C++03, although several
<a href="#Compilation">macros</a> are available to force PODness in all cases.</p>
<p><b>What are the implications of endian integer types not being POD's with C++03
<p><b>What are the implications of endian integer types not being PODs with C++03
compilers?</b> They
can't be used in unions. Also, compilers aren't required to align or lay
out storage in portable ways, although this potential problem hasn't prevented
@ -634,14 +636,14 @@ incrementing a variable in a record. It is very convenient to write:</p>
<p>The availability of the C++11
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">
Defaulted Functions</a> feature is detected automatically, and will be used if
present to ensure that objects of <code>class endian</code> are trivial, and
thus POD's.</p>
present to ensure that objects of <code>class endian_buffer</code> are trivial, and
thus PODs.</p>
<h2><a name="Compilation">Compilation</a></h2>
<p>Boost.Endian is implemented entirely within headers, with no need to link to
any Boost object libraries.</p>
<p>Several macros allow user control over features:</p>
<ul>
<li>BOOST_ENDIAN_NO_CTORS causes <code>class endian</code> to have no
<li>BOOST_ENDIAN_NO_CTORS causes <code>class endian_buffer</code> to have no
constructors. The intended use is for compiling user code that must be
portable between compilers regardless of C++11
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">
@ -650,13 +652,14 @@ any Boost object libraries.</p>
<li>BOOST_ENDIAN_FORCE_PODNESS causes BOOST_ENDIAN_NO_CTORS to be defined if
the compiler does not support C++11
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">
Defaulted Functions</a>. This is ensures that , and so can be used in unions.
In C++11, <code>class endian</code> objects are POD's even though they have
constructors.</li>
Defaulted Functions</a>. This is ensures that objects of <code>class endian_buffer</code>
are PODs, and so can be used in C++03 unions.
In C++11, <code>class endian_buffer</code> objects are PODs, even though they have
constructors, so can always be used in unions.</li>
</ul>
<hr>
<p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->12 February, 2015<!--webbot bot="Timestamp" endspan i-checksum="40531" --></p>
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->17 February, 2015<!--webbot bot="Timestamp" endspan i-checksum="40541" --></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>

26
doc/index.html
View File

@ -125,7 +125,7 @@ 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.</p>
<p>See the Wikipedia's
<p>See Wikipedia's
<a href="http://en.wikipedia.org/wiki/Endianness">Endianness</a> article for an
extensive discussion of endianness.</p>
<p>Programmers can usually ignore endianness, except when reading a core
@ -248,7 +248,7 @@ native_to_big_inplace(x);
</div>
<p><b>There will be no performance difference between the two approaches in
release builds,
optimized builds,
regardless of the native endianness of the machine.</b> That&#39;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>
@ -404,18 +404,18 @@ inserters and extractors?</b></p>
<p>Data interchange formats often specify binary arithmetic data.</p>
<p>Binary arithmetic data is smaller and therefore I/O is faster and file sizes
are smaller. Transfer between systems is less expensive.</p>
<p>Furthermore, binary arithmetic data is of fixed size, and so fixed-size disk
records are possible without padding, easing sorting and allowing direct access.
Disadvantages, such as the inability to use text utilities on the resulting
files, limit usefulness to applications where the binary I/O advantages are
paramount.</p>
<p dir="ltr">Furthermore, binary arithmetic data is of fixed size, and so fixed-size disk
records are possible without padding, easing sorting and allowing random access.</p>
<p dir="ltr">Disadvantages, such as the inability to use text utilities on the
resulting files, limit usefulness to applications where the binary I/O
advantages are paramount.</p>
</blockquote>
<p><b>Which is better, big-endian or little-endian?</b></p>
<blockquote>
<p>Big-endian tends to be preferred in a networking environment and is a bit
more of an industry standard, but little-endian may be preferred for
applications that run primarily on x86, x64, and other little-endian
applications that run primarily on x86, x86-64, and other little-endian
CPU's. The <a href="http://en.wikipedia.org/wiki/Endian">Wikipedia</a> article
gives more pros and cons.</p>
</blockquote>
@ -456,7 +456,7 @@ the same code being generated for either types.</p>
<p>The only supported types are four-byte <code>float</code> and eight-byte
<code>double</code>. Even after endianness has been accounted for, floating
point values will not be portable between systems that use different floating
point formats. Systems where integer endianness differs from floating point
point formats. Systems on which integer endianness differs from floating point
endianness are not supported.</p>
</blockquote>
@ -467,9 +467,9 @@ endianness are not supported.</p>
<p>Tests have only been
performed on machines that use two's complement arithmetic. The Endian
conversion functions support 16, 32, and 64-bit aligned integers only. The
Endian types support 8, 16, 24, 32, 40, 48, 56, and 64-bit unaligned integers
and 16, 32, and 64-bit aligned integers.</p>
conversion functions only support 16, 32, and 64-bit aligned integers. The
endian types only support 8, 16, 24, 32, 40, 48, 56, and 64-bit unaligned integers,
and 8, 16, 32, and 64-bit aligned integers.</p>
</blockquote>
@ -593,7 +593,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 -->12 February, 2015<!--webbot bot="Timestamp" endspan i-checksum="40531" --></p>
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->17 February, 2015<!--webbot bot="Timestamp" endspan i-checksum="40541" --></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>