boostorg/endian
1
0
Fork 1
mirror of https://github.com/boostorg/endian.git synced 2025-08-01 05:24:39 +02:00
Code Issues Packages Projects Releases Wiki Activity

Continue doc refinement.

Browse Source
This commit is contained in:
Beman
2013-05-20 15:04:33 -04:00
parent ecaabbeba4
commit c1dff8958c
3 changed files with 57 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
doc/conversion.html
View File

@@ -129,7 +129,8 @@ provided.</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.</p>
point formats. Systems where the integer endianness and floating point
endianness are not supported.</p>
</blockquote>
@@ -137,8 +138,8 @@ point formats.</p>
<blockquote>
<p>Only 16-bit, 32-bit, and 64-bit integers are supported. No tests have been
performed on machines that do not use two's complement arithmetic.</p>
<p>Only 16-bit, 32-bit, and 64-bit integers are supported. Tests have been
performed on machines that use two's complement arithmetic.</p>
</blockquote>
@@ -367,7 +368,7 @@ convert(x, some_order, order::native); // convert to native byte order if neede
<p>Recent compilers, including GCC, Clang, and Microsoft, supply intrinsic built-in support for byte swapping. Such support is automatically detected and used since it results in smaller and much faster generated code for release builds.</p><p>Defining BOOST_ENDIAN_NO_INTRINSICS will suppress use of the intrinsics. Please try defining it if you get compiler errors, such as header byteswap.h not being found.</p><p>The macro BOOST_ENDIAN_INTRINSIC_MSG is defined as either <code>&quot;no byte swap intrinsics&quot;</code> or a string describing the particular set of intrinsics being used.</p><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>.</p>
<hr>
<p>Last revised: <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->19 May, 2013<!--webbot bot="Timestamp" endspan i-checksum="13993" --></p>
<p>Last revised: <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->20 May, 2013<!--webbot bot="Timestamp" endspan i-checksum="13976" --></p>
<p><EFBFBD> Copyright Beman Dawes, 2011</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>

71
doc/index.html
View File

@@ -26,7 +26,7 @@
<td><b><a href="../../../index.htm">Boost Home</a>&nbsp;&nbsp;&nbsp;&nbsp;
<a href="index.html">Endian Home</a>&nbsp;&nbsp;&nbsp;&nbsp;
<a href="conversion.html">Conversion Functions</a>&nbsp;&nbsp;&nbsp;&nbsp;
<a href="types.html">Integer Types</a>&nbsp;&nbsp;&nbsp;&nbsp; Tutorial</b></td>
<a href="types.html">Endian Types</a>&nbsp;&nbsp;&nbsp;&nbsp; Tutorial</b></td>
</tr>
</table>
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" align="right">
@@ -53,7 +53,7 @@
</table>
<h2><a name="Abstract">Abstract</a></h2>
<p>Boost.Endian provides facilities to manipulate the byte ordering of integers.</p>
<p>Boost.Endian provides two facilities to manipulate the byte ordering of integers.</p>
<ul>
<li>The primary use case is binary I/O of integers for portable exchange with
other systems, via either file or network transmission.<br>
@@ -64,16 +64,7 @@
&nbsp;</li>
<li>Two distinct approaches to byte ordering are provided. Each approach has a
long history of successful use, and each approach has use cases where it is
superior to the other approach.<br>
&nbsp;<ul>
<li>The explicit approach provides <a href="conversion.html">conversion
functions</a> to reorder bytes. All four combinations of non-modifying or
modifying, and unconditional or conditional, functions are provided.<br>
&nbsp;</li>
<li>The implicit approach provides <a href="types.html">integer types</a>
that mimic the built-in integers, implicitly handling all byte reordering.</li>
</ul>
</li>
superior to the other approach.</li>
</ul>
<h2><a name="Introduction-to-endianness">Introduction to endianness</a></h2>
@@ -82,16 +73,16 @@
<blockquote>
<pre>int16_t i = 0x0102;
FILE * file = fopen(&quot;test&quot;, &quot;wb&quot;); // MUST BE BINARY
FILE * file = fopen(&quot;test.bin&quot;, &quot;wb&quot;); // MUST BE BINARY
fwrite(&amp;i, sizeof(int16_t), 1, file);
fclose(file);</pre>
</blockquote>
<p>On an Apple, Linux, or Windows computer with an Intel CPU, a hex dump
of the &quot;test&quot; output file produces:</p>
<p>On OS X, Linux, or Windows systems with an Intel CPU, a hex dump
of the &quot;test.bin&quot; output file produces:</p>
<blockquote>
<p><code>0201</code></p>
</blockquote>
<p>On an Apple or other computer with a PowerPC CPU, or an Oracle/Sun Solaris computer with a SPARC CPU, a hex dump of the &quot;test&quot;
<p>On OS X systems with a PowerPC CPU, or Solaris systems with a SPARC CPU, a hex dump of the &quot;test.bin&quot;
output file produces:</p>
<blockquote>
<p><code>0102</code></p>
@@ -111,9 +102,10 @@ at different ends.</p>
<p>See the Wikipedia's
<a href="http://en.wikipedia.org/wiki/Endianness">Endianness</a> article for an
extensive discussion of endianness.</p>
<p>Except for reading an occasional core dump, most programmers can ignore
endianness. But when exchanging binary integers with other computer systems, whether by
file transfers or over a network, programmers have to deal with endianness. </p>
<p>Except for reading a core dump on little-endian systems, most programmers can
ignore endianness. But when exchanging binary integers and binary floating point
values between computer systems with differing endianness, whether by physical file transfer or over a network, programmers have to deal with endianness
in their code. </p>
<h2><a name="Introduction">Introduction</a> to the Boost.Endian library</h2>
<p>The Boost.Endian library provides two facilities for dealing with endianness.</p>
@@ -185,28 +177,47 @@ application.</p>
</tr>
</table>
<h2>Overall <a name="FAQ">FAQ</a></h2>
<p><b>Why bother with endianness? Does endianness have any uses outside of
portable binary file or network I/O formats?</b> </p>
<blockquote>
<p>Binary data portability is the primary use case, and that implies I/O.</p>
<p>Using the 3, 5, 6, and 7 byte integer types to save internal or external
memory space is a minor secondary use case.</p>
</blockquote>
<p><b>Why bother with binary I/O? Why not just use C++ Standard Library stream
inserters and extractors?</b></p>
<blockquote>
<p>Binary arithmetic data is smaller and therefore I/O is faster and file sizes
are smaller. Transfer between systems is less expensive. Standard interchange
formats often specify binary arithmetic data.</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>
</blockquote>
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
<p>Comments and suggestions were
received from
Benaka Moorthi,
Adder, Benaka Moorthi,
Christopher Kohlhoff,
Cliff Green,
Gennaro Proto,
Giovanni Piero Deretta, dizzy, Jeff Flinn,
John Maddock,
Cliff Green,Daniel James, Gennaro Proto,
Giovanni Piero Deretta, Gordon Woodhull, dizzy, Hartmut Kaiser, Jeff Flinn,
John Filo, John Maddock,
Kim Barrett,
Marsh Ray,
Martin Bonner,
Matias Capeletto,
Neil Mayhew, Phil Endecott, Rene Rivera,
Martin Bonner, Mathias Gaunard, Matias Capeletto,
Neil Mayhew, Paul Bristow, Phil Endecott, Pyry Jahkola, Rene Rivera,
Robert Stewart, Roland Schwarz, Scott McMurray,
Sebastian Redl,
Tomas Puverle, Vincente Botet, and
Yuval Ronen.</p>
Tim Blechmann, Tim Moore, tymofey, Tomas Puverle, Vincente Botet, Yuval Ronen
and Vitaly Budovski,.</p>
<hr>
<p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->20 May, 2013<!--webbot bot="Timestamp" endspan i-checksum="13976" --></p>
<p><EFBFBD> Copyright Beman Dawes, 2011</p>
<p><EFBFBD> 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>

22
doc/types.html
View File

@@ -53,7 +53,7 @@
<a href="#Design">Design</a><br>
<a href="#Experience">Experience</a><br>
<a href="#Motivating-use-cases">Motivating use cases</a><br>
<a href="#C++0x">C++0x</a><br>
<a href="#C++0x">C++11</a><br>
<a href="#Compilation">Compilation</a><br>
<a href="#Acknowledgements">Acknowledgements</a>
</td>
@@ -178,9 +178,9 @@ 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>
endian</code> were a POD type. In C++0x, it will be possible to specify the
endian</code> were a POD type. In C++11, it will be 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++0x, <code>endian</code>
no longer disqualify a type from being a POD. Thus under C++11, <code>endian</code>
will no longer be relying on unspecified behavior.</p>
<h2><a name="Feature-set">Feature set</a></h2>
<ul>
@@ -325,7 +325,7 @@ usual operations on integers are supplied.</p>
public:
typedef T value_type;
// if BOOST_ENDIAN_FORCE_PODNESS is defined &amp;&amp; C++0x POD's are not
// if BOOST_ENDIAN_FORCE_PODNESS is defined &amp;&amp; C++11 POD's are not
// available then these two constructors will not be present
<a href="#endian">endian</a>() = default; // = default replaced by {} on C++03
explicit <a href="#explicit-endian">endian</a>(T v);
@@ -477,7 +477,7 @@ alignment, so may be used to save memory in applications not related to I/O.</p>
compared to arithmetic operations on native integer types. However, these types
are usually be faster, and sometimes much faster, for I/O compared to stream
inserters and extractors, or to serialization.</p>
<p><b>Are endian types POD's?</b> Yes for C++0x. No for C++03, although several
<p><b>Are endian types POD's?</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 endian integer types not being POD's with C++03
compilers?</b> They
@@ -544,8 +544,8 @@ range of computer architectures and applications.</p>
library: reading TrueType font files from disk and processing the contents. The
data format has fixed endianness (big) and has unaligned values in various
places. Using Boost.Endian simplifies and cleans the code wonderfully.&quot;</p>
<h2><a name="C++0x">C++0x</a></h2>
<p>The availability of the C++0x
<h2><a name="C++0x">C++11</a></h2>
<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
@@ -557,15 +557,15 @@ any Boost object libraries.</p>
<ul>
<li>BOOST_ENDIAN_NO_CTORS causes <code>class endian</code> to have no
constructors. The intended use is for compiling user code that must be
portable between compilers regardless of C++0x
portable between compilers regardless of C++11
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">
Defaulted Functions</a> support. Use of constructors will always fail, <br>
&nbsp;</li>
<li>BOOST_ENDIAN_FORCE_PODNESS causes BOOST_ENDIAN_NO_CTORS to be defined if
the compiler does not support C++0x
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++0x, <code>class endian</code> objects are POD's even though they have
In C++11, <code>class endian</code> objects are POD's even though they have
constructors.</li>
</ul>
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
@@ -577,7 +577,7 @@ sign partial specialization to correctly extend the sign when cover integer size
differs from endian representation size.</p>
<hr>
<p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05 September, 2011<!--webbot bot="Timestamp" endspan i-checksum="39338" --></p>
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->20 May, 2013<!--webbot bot="Timestamp" endspan i-checksum="13976" --></p>
<p><EFBFBD> Copyright Beman Dawes, 2006-2009</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>