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

Do a pass through docs, bringing up to date where needed.

Browse Source
This commit is contained in:
Beman
2014-08-12 10:34:37 -04:00
parent 071099b656
commit 62943e150e
6 changed files with 271 additions and 260 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
doc/conversion.html
View File

@@ -88,7 +88,12 @@ namespace boost
{
namespace endian
{
enum class <a name="order">order</a> {big, little, native};
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>};
// reverse byte order (i.e. endianness)
int8_t <a href="#reverse_value">reverse_value</a>(int8_t x) noexcept;
@@ -151,6 +156,9 @@ namespace endian
} // namespace endian
} // namespace boost</pre>
<p>The <i><b><code>implementation-defined</code></b></i> text above is either
<code>big</code> or <code>little</code> according to the endianness of the
platform.</p>
<h3><a name="Requirements">Requirements</a></h3>
<p>The template definitions in this header refer to named
requirements whose details are set out in this section. User defined types may
@@ -330,7 +338,7 @@ Pierre Talbot provided the <code>int8_t reverse_value()</code> and templated
<code>reverse()</code> implementations.</p>
<hr>
<p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->16 April, 2014<!--webbot bot="Timestamp" endspan i-checksum="29929" --></p>
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->12 August, 2014<!--webbot bot="Timestamp" endspan i-checksum="34569" --></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>

54
doc/do_list.html
View File

@@ -11,6 +11,9 @@
<body>
<h1>Endian Library Do List</h1>
<p><b>August 12, 2014: The many items that have been completed should be
removed, after verifying that they are in fact taken care of.</b></p>
<h2>To Do</h2>
<ul>
<li>Re-read all messages, and extract Acknowledgements and revise TODO list.</li>
@@ -24,13 +27,6 @@
<li>Apply mockups of the buffers to the example programs, to get a<br>
firmer idea if the buffer idea actually seems to do be worthwhile in<br>
practice.</li>
<li>Post work-in-progress for feedback.</li>
<li>boost-root/boost/detail/endian.hpp: Boost.Endian should provide identical
functionality in a Boost license only header. That implies rewriting the
portions covered by the original SGI copyright. The boost-root/boost/detail/endian.hpp
header should be changed to forward to the Boost.Endian header to preserve
existing code, and the SGI copyright thus eliminated.</li>
<li>Finalize and hold mini-review.</li>
</ul>
<h2>Format Review Comments</h2>
<h3 dir="ltr">Votes</h3>
@@ -115,7 +111,6 @@
<h3>Docs</h3>
<ul>
<li>Document use of endian integers with stream inserters and extractors.</li>
<li>Either add tutorial or remove from menu bar.</li>
<li>Conversion in note mention similarity to htonl() , etc.</li>
<li>Conversion: add discussion of alignment, packing, etc. Bottom line; use at
your own risk. Use Phil's example:<br>
@@ -180,9 +175,6 @@
<li><span style="background-color: #FFCCFF">Beman: TODO</span><span style="background-color: #FFCCFF">:
</span><span style="background-color: #FFCCFF">Google</span><span style="background-color: #FFCCFF">
&quot;unaligned integer&quot;, look at various entries. For example, http://</span><span style="background-color: #FFCCFF">infocenter.arm.com</span><span style="background-color: #FFCCFF">/help/</span><span style="background-color: #FFCCFF">index.jsp?topic</span><span style="background-color: #FFCCFF">=/</span><span style="background-color: #FFCCFF">com.arm.doc.faqs</span><span style="background-color: #FFCCFF">/ka3544.html</span></li>
<li>Merge conversion2 into conversion.hpp</li>
<li>Use builtins where applicable (GCC, possibly others)</li>
<li>Endian integer types should use the conversion functions where applicable.</li>
<li>Beman: Some platforms (compiler/processor taken together) don't require
alignment for the conversion functions if code is inlined, although speed may
suffer. (test to verify this assertion). On those platforms, conversion
@@ -203,25 +195,6 @@
<li>Test use of endian integers with stream inserters and extractors.</li>
<li>Continue work on benchmarks and timings. Consider using use-case example
programs as benchmarks.</li>
<li>
<div class="im">
&gt; The reorder fuction should provide both reorder in place and returned.</div>
<p>Interesting, but providing two ways of doing something is often<br>
considered the not best design practice. And the tests I've run so far<br>
don't indicate any efficiency concern. Once all other aspects of the<br>
interface and implementation are settled, let's revisit that question.<br>
&nbsp;</li>
<li>&gt; The endianness scoped enum native should be replaced so it is defined<br>
&gt; depending on the endianess of the platform.<br>
&gt;<br>
&gt; &nbsp;BOOST_SCOPED_ENUM_START(<wbr />endianness) { big, little, native=(big or
little)<br>
&gt; }; BOOST_SCOPED_ENUM_END<br>
&gt;<br>
&gt; This will have the advantage to reduce of 1/3 the number of specializations.<br>
<br>
Does this work?<br>
&nbsp;</li>
<li dir="ltr">
<div class="im">
&gt; The library should provide in addition endian conversion functions that
@@ -233,9 +206,6 @@
</ul>
<h3>Infrastructure</h3>
<ul>
<li>Remove scoped_enum_emulation_test stuff.</li>
<li>Remove timer stuff.</li>
<li>Use Boost.Timer.</li>
<li>
<div class="im">
&gt; endian_operations_test.cpp and endian_in_union_test.cpp ... maybe rename
@@ -249,24 +219,8 @@
<p>Will do.</li>
<li>Make the bin() functionality available</li>
</ul>
<h3>Performance</h3>
<p>&nbsp;</p>
<h3>Acknowledge</h3>
<p>Gordon Woodhull, Hartmut Kaiser, Phil Endecott, tymofey, Giovanni Piero Deretta, Pyry Jahkola,
John Filo, Vitaly Budovski, Tomas Puverle, Vicente J. Botet Escriba, Tim
Blechmann, Daniel James, Mathias Gaunard, Adder, Tim Moore</p>
<p>Paul Bristow docs help </p>
<h2>Floating Point Support</h2>
<p>* Because FP formats vary, just dealing with endianness doesn't ensure<br>
portability.<br>
* The endianness of FP and integer values differs on some platforms,<br>
so we will have to build up a config file with separate entries for<br>
each platform, and that will take time to mature.<br>
* Ditto FP sizes.<br>
* I'm only willing to provide conversion.hpp FP support. Providing<br>
<p>* I'm only willing to provide conversion.hpp FP support. Providing<br>
types that mimic FP types is far beyond my knowledge of how to deal<br>
with floating point's notorious arithmetic issues.</p>
<p>Support IEEE754 format (32 bit, 64 bit) only.</p>

53
doc/done_list.html
View File

@@ -1,53 +0,0 @@
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<title>Endian since formal review</title>
</head>
<body>
<h1>Endian changes since formal review</h1>
<ul>
<li>Both the endian types and endian conversion functions now support 32-bit (<code>float)</code> and
64-bit <code>(double)</code> floating point, as requested.</li>
<li>Both the endian types and endian conversion functions now support UDTs, as requested.</li>
<li>The conversion functions have been much revised,
refactored, and otherwise improved based on review comments.<ul>
<li>Both return-by-value and modify-in-place interfaces are provided, as
requested.</li>
<li>Synonyms for the BSD byte swapping function names popularized by OS X
and Linux are provided, so that that developers already used to these names
can continue to use them if they wish.</li>
<li>In addition to the named-endianness functions, functions that perform
compile-time (via template) and run-time (via function argument) dispatch
are now provided, as requested.</li>
</ul>
</li>
<li>Compiler (Clang, GCC, VisualC++, etc.) intrinsics and built-in functions
are used in the implementation where appropriate, as requested.</li>
<li>For the endian types, the implementation uses the endian conversion functions,
and thus the intrinsics,
as requested.</li>
<li>Headers have been renamed to endian/types.hpp and endian/conversion.hpp.
Infrastructure file names changed accordingly.</li>
<li>C++11 features such as <code>noexcept</code> are now used, while still
supporting C++03 compilers.</li>
<li>Documentation revised and expanded, as requested.</li>
<li>Acknowledgements have been updated.</li>
<li>Headers have been reorganized to make them easier to read,
with a synopsis at the front and implementation following, as requested.</li>
<li><code>reverse_value()</code> overloads for <code>int8_t</code> and <code>
uint8_t</code> have been added for improved generality. (Pierre Talbot)</li>
<li>Overloads of <code>reverse()</code> have been replaced with a single <code>
reverse()</code> template. (Pierre Talbot)</li>
</ul>
<p>&nbsp;</p>
</body>
</html>

327
doc/index.html
View File

@@ -46,7 +46,7 @@
<a href="#Introduction-to-endianness">Introduction to endianness</a><br>
<a href="#Introduction">Introduction to the Boost.Endian library</a><br>
<a href="#Choosing">Choosing approaches</a><br>
<a href="#Intrinsic">Intrinsic built-in support</a><br>
<a href="#Intrinsic">Built-in support for Intrinsics</a><br>
<a href="#Performance">Performance</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Timings">Timings</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Conclusions">Conclusions</a><br>
@@ -65,23 +65,15 @@
</tr>
</table>
<table border="1" cellpadding="0" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
<tr>
<td>Heads up: As development has continues, there have been breaking
changes. Most recently, the <a href="types.html">endian types</a> were
renamed.</td>
</tr>
</table>
<h2><a name="Abstract">Abstract</a></h2>
<p>Boost.Endian provides facilities to manipulate the endianness of integers,
floating point, and user defined data.</p>
<ul>
<li>The primary use case is binary I/O for portable data exchange with
other systems, via either file or network transmission.<br>
other systems, via either external media or network transmission.<br>
&nbsp;</li>
<li>A secondary use case is minimizing storage size via sizes and/or
<li>A second use case is minimizing storage size via sizes and/or
alignments not supported by the built-in types.<br>
&nbsp;</li>
<li>Two distinct approaches to dealing with endianness are provided. Each approach has a
@@ -167,59 +159,60 @@ application needs.</p>
<th colspan="2">Needs that favor one approach over the other</th>
</tr>
<tr>
<th width="50%"><b><a href="types.html">Endian types</a> are better with
<th width="50%"><b><a href="types.html">Endian types</a> may be better for
these needs</b></th>
<th><b><a href="conversion.html">Endian conversion functions</a> may be
better for
these needs</b></th>
<th><b><a href="conversion.html">Endian conversion functions</a> are better
with these needs</b></th>
</tr>
<tr>
<td valign="top">
<ul>
<li>A need to simplify program logic and eliminate logic
<li><p>A need to simplify program logic and eliminate logic
errors. Since the endian types mimic the built-in types, there is no need to reason about the current endianness of variables
and that can simplify program logic and eliminate logic errors.<br>
&nbsp;</li>
<li>A need to use unusual integer sizes (i.e. 3, 5,
and that can simplify program logic and eliminate logic errors.</p></li>
<li><p>A need to use unusual integer sizes (i.e. 3, 5,
6, or 7 bytes) to reduce internal and external space usage and
save I/O time.<br>
&nbsp;</li>
<li>A need to use unaligned variables. Endian types can eliminate padding bytes in
save I/O time.</li>
<li><p>A need to use unaligned variables. Endian types can eliminate padding bytes in
structures, reducing internal and external space usage and saving I/O
time. They can deals with structures defined like this:</li>
</ul>
time. They can deals with structures defined like this:
<blockquote>
<p><code>struct S {<br>
&nbsp; uint16_t a;<br>
&nbsp; uint32_t b;<br>
} __attribute__ ((packed));</code></p>
</blockquote>
} __attribute__ ((packed));</code>
</blockquote></p></li>
<li>
<p>Programmer preference.</p></li>
</ul>
</td>
<td valign="top">
<ul>
<li>A need to leverage knowledge of developers who have been using C byte
<li><p>A need to leverage knowledge of developers who have been using C byte
swapping
functions for years.<br>
&nbsp;</li>
functions for years.</p></li>
<li>A need to save CPU time when a variable is used many times
relative to its I/O.<br>
&nbsp;</li>
<li>A need to pass structures to third-party libraries expecting a
specific structure format.<br>
&nbsp;</li>
relative to its I/O.</li>
<li>
<p>A need to pass structures to third-party libraries expecting a
specific structure format.</li>
<li>
<p>Programmer preference.</li>
</ul>
</td>
</tr>
</table>
<h2><a name="Intrinsic">Intrinsic</a> built-in support</h2>
<p>Recent compilers, including GCC, Clang, and Microsoft, supply intrinsic
built-in support for byte swapping. Such support is automatically detected and
<h2>Built-in support for <a name="Intrinsic">Intrinsic</a>s</h2>
<p>Recent compilers, including GCC, Clang, and Microsoft, supply built-in support for byte swapping
intrinsics. Such support is automatically detected and
used since it may in smaller and faster generated code, particularly for release
builds.</p>
<p dir="ltr">Defining <code>BOOST_ENDIAN_NO_INTRINSICS</code> will suppress use
<p>Defining <code>BOOST_ENDIAN_NO_INTRINSICS</code> 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 dir="ltr">The macro <code>BOOST_ENDIAN_INTRINSIC_MSG</code> is defined as
<p>The macro <code>BOOST_ENDIAN_INTRINSIC_MSG</code> is defined as
either <code>&quot;no byte swap intrinsics&quot;</code> or a string describing the
particular set of intrinsics being used.</p>
@@ -267,9 +260,10 @@ big_endian(x);
</tr>
</table>
<p><b>There will be no performance difference between the two approaches,
regardless of the native endianness of the machine.</b> Optimizing compilers will likely
generate exactly the same code for both. That conclusion was confirmed by
<p><b>There will be no performance difference between the two approaches in
release builds,
regardless of the native endianness of the machine.</b> That&#39;s because optimizing compilers will likely
generate exactly the same code for each. That conclusion was confirmed by
studying the generated assembly code for GCC and Visual C++.</p>
<p>Now consider a slightly different problem:&nbsp; </p>
@@ -337,84 +331,180 @@ setup.
32-bit intrinsics.)</p>
<table border="1" cellpadding="5" cellspacing="0"style="border-collapse: collapse" bordercolor="#111111">
<tr><td colspan="6" align="center"><b>GNU C++ version 4.7.0</b></td></tr>
<tr><td colspan="6" align="center"><b> Iterations: 1000000000, Intrinsics: __builtin_bswap16, etc.</b></td></tr>
<tr><td><b>Test Case</b></td>
<td align="center"><b>Endian<br>type</b></td>
<td align="center"><b>Endian<br>conversion<br>function</b></td>
<tr><td colspan="6" align="center" dir="ltr"><b><font size="2">GNU C++ version 4.7.0</font></b></td></tr>
<tr><td colspan="6" align="center" dir="ltr"><b> <font size="2">Iterations: 1000000000, Intrinsics: __builtin_bswap16, etc.</font></b></td></tr>
<tr><td dir="ltr"><b><font size="2">Test Case</font></b></td>
<td align="center" dir="ltr"><b><font size="2">Endian<br>type</font></b></td>
<td align="center" dir="ltr"><b><font size="2">Endian<br>conversion<br>function</font></b></td>
</tr>
<tr><td>16-bit aligned big endian</td><td align="right">1.37 s</td><td align="right">0.81 s</td></tr>
<tr><td>16-bit aligned little endian</td><td align="right">0.83 s</td><td align="right">0.81 s</td></tr>
<tr><td>16-bit unaligned big endian</td><td align="right">1.09 s</td><td align="right">0.83 s</td></tr>
<tr><td>16-bit unaligned little endian</td><td align="right">1.09 s</td><td align="right">0.81 s</td></tr>
<tr><td>32-bit aligned big endian</td><td align="right">0.98 s</td><td align="right">0.27 s</td></tr>
<tr><td>32-bit aligned little endian</td><td align="right">0.28 s</td><td align="right">0.27 s</td></tr>
<tr><td>32-bit unaligned big endian</td><td align="right">3.82 s</td><td align="right">0.27 s</td></tr>
<tr><td>32-bit unaligned little endian</td><td align="right">3.82 s</td><td align="right">0.27 s</td></tr>
<tr><td>64-bit aligned big endian</td><td align="right">1.65 s</td><td align="right">0.41 s</td></tr>
<tr><td>64-bit aligned little endian</td><td align="right">0.41 s</td><td align="right">0.41 s</td></tr>
<tr><td>64-bit unaligned big endian</td><td align="right">17.53 s</td><td align="right">0.41 s</td></tr>
<tr><td>64-bit unaligned little endian</td><td align="right">17.52 s</td><td align="right">0.41 s</td></tr>
<tr><td dir="ltr"><font size="2">16-bit aligned big endian</font></td>
<td align="right" dir="ltr"><font size="2">1.37 s</font></td>
<td align="right" dir="ltr"><font size="2">0.81 s</font></td></tr>
<tr><td dir="ltr"><font size="2">16-bit aligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">0.83 s</font></td>
<td align="right" dir="ltr"><font size="2">0.81 s</font></td></tr>
<tr><td dir="ltr"><font size="2">16-bit unaligned big endian</font></td>
<td align="right" dir="ltr"><font size="2">1.09 s</font></td>
<td align="right" dir="ltr"><font size="2">0.83 s</font></td></tr>
<tr><td dir="ltr"><font size="2">16-bit unaligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">1.09 s</font></td>
<td align="right" dir="ltr"><font size="2">0.81 s</font></td></tr>
<tr><td dir="ltr"><font size="2">32-bit aligned big endian</font></td>
<td align="right" dir="ltr"><font size="2">0.98 s</font></td>
<td align="right" dir="ltr"><font size="2">0.27 s</font></td></tr>
<tr><td dir="ltr"><font size="2">32-bit aligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">0.28 s</font></td>
<td align="right" dir="ltr"><font size="2">0.27 s</font></td></tr>
<tr><td dir="ltr"><font size="2">32-bit unaligned big endian</font></td>
<td align="right" dir="ltr"><font size="2">3.82 s</font></td>
<td align="right" dir="ltr"><font size="2">0.27 s</font></td></tr>
<tr><td dir="ltr"><font size="2">32-bit unaligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">3.82 s</font></td>
<td align="right" dir="ltr"><font size="2">0.27 s</font></td></tr>
<tr><td dir="ltr"><font size="2">64-bit aligned big endian</font></td>
<td align="right" dir="ltr"><font size="2">1.65 s</font></td>
<td align="right" dir="ltr"><font size="2">0.41 s</font></td></tr>
<tr><td dir="ltr"><font size="2">64-bit aligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">0.41 s</font></td>
<td align="right" dir="ltr"><font size="2">0.41 s</font></td></tr>
<tr><td dir="ltr"><font size="2">64-bit unaligned big endian</font></td>
<td align="right" dir="ltr"><font size="2">17.53 s</font></td>
<td align="right" dir="ltr"><font size="2">0.41 s</font></td></tr>
<tr><td dir="ltr"><font size="2">64-bit unaligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">17.52 s</font></td>
<td align="right" dir="ltr"><font size="2">0.41 s</font></td></tr>
<tr><td colspan="6" align="center"><b> Iterations: 1000000000, Intrinsics: no byte swap intrinsics</b></td></tr>
<tr><td><b>Test Case</b></td>
<td align="center"><b>Endian<br>type</b></td>
<td align="center"><b>Endian<br>conversion<br>function</b></td>
<tr><td colspan="6" align="center" dir="ltr"><b> <font size="2">Iterations: 1000000000, Intrinsics: no byte swap intrinsics</font></b></td></tr>
<tr><td dir="ltr"><b><font size="2">Test Case</font></b></td>
<td align="center" dir="ltr"><b><font size="2">Endian<br>type</font></b></td>
<td align="center" dir="ltr"><b><font size="2">Endian<br>conversion<br>function</font></b></td>
</tr>
<tr><td>16-bit aligned big endian</td><td align="right">1.95 s</td><td align="right">0.81 s</td></tr>
<tr><td>16-bit aligned little endian</td><td align="right">0.83 s</td><td align="right">0.81 s</td></tr>
<tr><td>16-bit unaligned big endian</td><td align="right">1.19 s</td><td align="right">0.81 s</td></tr>
<tr><td>16-bit unaligned little endian</td><td align="right">1.20 s</td><td align="right">0.81 s</td></tr>
<tr><td>32-bit aligned big endian</td><td align="right">0.97 s</td><td align="right">0.28 s</td></tr>
<tr><td>32-bit aligned little endian</td><td align="right">0.27 s</td><td align="right">0.28 s</td></tr>
<tr><td>32-bit unaligned big endian</td><td align="right">4.10 s</td><td align="right">0.27 s</td></tr>
<tr><td>32-bit unaligned little endian</td><td align="right">4.10 s</td><td align="right">0.27 s</td></tr>
<tr><td>64-bit aligned big endian</td><td align="right">1.64 s</td><td align="right">0.42 s</td></tr>
<tr><td>64-bit aligned little endian</td><td align="right">0.41 s</td><td align="right">0.41 s</td></tr>
<tr><td>64-bit unaligned big endian</td><td align="right">17.52 s</td><td align="right">0.42 s</td></tr>
<tr><td>64-bit unaligned little endian</td><td align="right">17.52 s</td><td align="right">0.41 s</td></tr>
<tr><td dir="ltr"><font size="2">16-bit aligned big endian</font></td>
<td align="right" dir="ltr"><font size="2">1.95 s</font></td>
<td align="right" dir="ltr"><font size="2">0.81 s</font></td></tr>
<tr><td dir="ltr"><font size="2">16-bit aligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">0.83 s</font></td>
<td align="right" dir="ltr"><font size="2">0.81 s</font></td></tr>
<tr><td dir="ltr"><font size="2">16-bit unaligned big endian</font></td>
<td align="right" dir="ltr"><font size="2">1.19 s</font></td>
<td align="right" dir="ltr"><font size="2">0.81 s</font></td></tr>
<tr><td dir="ltr"><font size="2">16-bit unaligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">1.20 s</font></td>
<td align="right" dir="ltr"><font size="2">0.81 s</font></td></tr>
<tr><td dir="ltr"><font size="2">32-bit aligned big endian</font></td>
<td align="right" dir="ltr"><font size="2">0.97 s</font></td>
<td align="right" dir="ltr"><font size="2">0.28 s</font></td></tr>
<tr><td dir="ltr"><font size="2">32-bit aligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">0.27 s</font></td>
<td align="right" dir="ltr"><font size="2">0.28 s</font></td></tr>
<tr><td dir="ltr"><font size="2">32-bit unaligned big endian</font></td>
<td align="right" dir="ltr"><font size="2">4.10 s</font></td>
<td align="right" dir="ltr"><font size="2">0.27 s</font></td></tr>
<tr><td dir="ltr"><font size="2">32-bit unaligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">4.10 s</font></td>
<td align="right" dir="ltr"><font size="2">0.27 s</font></td></tr>
<tr><td dir="ltr"><font size="2">64-bit aligned big endian</font></td>
<td align="right" dir="ltr"><font size="2">1.64 s</font></td>
<td align="right" dir="ltr"><font size="2">0.42 s</font></td></tr>
<tr><td dir="ltr"><font size="2">64-bit aligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">0.41 s</font></td>
<td align="right" dir="ltr"><font size="2">0.41 s</font></td></tr>
<tr><td dir="ltr"><font size="2">64-bit unaligned big endian</font></td>
<td align="right" dir="ltr"><font size="2">17.52 s</font></td>
<td align="right" dir="ltr"><font size="2">0.42 s</font></td></tr>
<tr><td dir="ltr"><font size="2">64-bit unaligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">17.52 s</font></td>
<td align="right" dir="ltr"><font size="2">0.41 s</font></td></tr>
</table>
<p></p>
<table border="1" cellpadding="5" cellspacing="0"style="border-collapse: collapse" bordercolor="#111111">
<tr><td colspan="6" align="center"><b>Microsoft Visual C++ version 11.0</b></td></tr>
<tr><td colspan="6" align="center"><b> Iterations: 1000000000, Intrinsics: cstdlib _byteswap_ushort, etc.</b></td></tr>
<tr><td><b>Test Case</b></td>
<td align="center"><b>Endian<br>type</b></td>
<td align="center"><b>Endian<br>conversion<br>function</b></td>
<table border="1" cellpadding="5" cellspacing="0"style="border-collapse: collapse" bordercolor="#111111" dir="ltr">
<tr><td colspan="6" align="center" dir="ltr"><b><font size="2">Microsoft Visual C++ version 11.0</font></b></td></tr>
<tr><td colspan="6" align="center" dir="ltr"><b> <font size="2">Iterations: 1000000000, Intrinsics: cstdlib _byteswap_ushort, etc.</font></b></td></tr>
<tr><td dir="ltr"><b><font size="2">Test Case</font></b></td>
<td align="center" dir="ltr"><b><font size="2">Endian<br>type</font></b></td>
<td align="center" dir="ltr"><b><font size="2">Endian<br>conversion<br>function</font></b></td>
</tr>
<tr><td>16-bit aligned big endian</td><td align="right">0.83 s</td><td align="right">0.51 s</td></tr>
<tr><td>16-bit aligned little endian</td><td align="right">0.51 s</td><td align="right">0.50 s</td></tr>
<tr><td>16-bit unaligned big endian</td><td align="right">1.37 s</td><td align="right">0.51 s</td></tr>
<tr><td>16-bit unaligned little endian</td><td align="right">1.37 s</td><td align="right">0.50 s</td></tr>
<tr><td>32-bit aligned big endian</td><td align="right" bgcolor="#CCFFCC">0.81 s</td><td align="right">0.50 s</td></tr>
<tr><td>32-bit aligned little endian</td><td align="right">0.51 s</td><td align="right">0.51 s</td></tr>
<tr><td>32-bit unaligned big endian</td><td align="right">2.98 s</td><td align="right">0.53 s</td></tr>
<tr><td>32-bit unaligned little endian</td><td align="right">3.00 s</td><td align="right">0.51 s</td></tr>
<tr><td>64-bit aligned big endian</td><td align="right" bgcolor="#CCFFCC">1.33 s</td><td align="right">0.33 s</td></tr>
<tr><td>64-bit aligned little endian</td><td align="right">0.34 s</td><td align="right">0.27 s</td></tr>
<tr><td>64-bit unaligned big endian</td><td align="right">7.05 s</td><td align="right">0.33 s</td></tr>
<tr><td>64-bit unaligned little endian</td><td align="right">7.11 s</td><td align="right">0.31 s</td></tr>
<tr><td dir="ltr"><font size="2">16-bit aligned big endian</font></td>
<td align="right" dir="ltr"><font size="2">0.83 s</font></td>
<td align="right" dir="ltr"><font size="2">0.51 s</font></td></tr>
<tr><td dir="ltr"><font size="2">16-bit aligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">0.51 s</font></td>
<td align="right" dir="ltr"><font size="2">0.50 s</font></td></tr>
<tr><td dir="ltr"><font size="2">16-bit unaligned big endian</font></td>
<td align="right" dir="ltr"><font size="2">1.37 s</font></td>
<td align="right" dir="ltr"><font size="2">0.51 s</font></td></tr>
<tr><td dir="ltr"><font size="2">16-bit unaligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">1.37 s</font></td>
<td align="right" dir="ltr"><font size="2">0.50 s</font></td></tr>
<tr><td dir="ltr"><font size="2">32-bit aligned big endian</font></td>
<td align="right" bgcolor="#CCFFCC" dir="ltr"><font size="2">0.81 s</font></td>
<td align="right" dir="ltr"><font size="2">0.50 s</font></td></tr>
<tr><td dir="ltr"><font size="2">32-bit aligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">0.51 s</font></td>
<td align="right" dir="ltr"><font size="2">0.51 s</font></td></tr>
<tr><td dir="ltr"><font size="2">32-bit unaligned big endian</font></td>
<td align="right" dir="ltr"><font size="2">2.98 s</font></td>
<td align="right" dir="ltr"><font size="2">0.53 s</font></td></tr>
<tr><td dir="ltr"><font size="2">32-bit unaligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">3.00 s</font></td>
<td align="right" dir="ltr"><font size="2">0.51 s</font></td></tr>
<tr><td dir="ltr"><font size="2">64-bit aligned big endian</font></td>
<td align="right" bgcolor="#CCFFCC" dir="ltr"><font size="2">1.33 s</font></td>
<td align="right" dir="ltr"><font size="2">0.33 s</font></td></tr>
<tr><td dir="ltr"><font size="2">64-bit aligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">0.34 s</font></td>
<td align="right" dir="ltr"><font size="2">0.27 s</font></td></tr>
<tr><td dir="ltr"><font size="2">64-bit unaligned big endian</font></td>
<td align="right" dir="ltr"><font size="2">7.05 s</font></td>
<td align="right" dir="ltr"><font size="2">0.33 s</font></td></tr>
<tr><td dir="ltr"><font size="2">64-bit unaligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">7.11 s</font></td>
<td align="right" dir="ltr"><font size="2">0.31 s</font></td></tr>
<tr><td colspan="6" align="center"><b> Iterations: 1000000000, Intrinsics: no byte swap intrinsics</b></td></tr>
<tr><td><b>Test Case</b></td>
<td align="center"><b>Endian<br>type</b></td>
<td align="center"><b>Endian<br>conversion<br>function</b></td>
<tr><td colspan="6" align="center" dir="ltr"><b> <font size="2">Iterations: 1000000000, Intrinsics: no byte swap intrinsics</font></b></td></tr>
<tr><td dir="ltr"><b><font size="2">Test Case</font></b></td>
<td align="center" dir="ltr"><b><font size="2">Endian<br>type</font></b></td>
<td align="center" dir="ltr"><b><font size="2">Endian<br>conversion<br>function</font></b></td>
</tr>
<tr><td>16-bit aligned big endian</td><td align="right">0.83 s</td><td align="right">0.51 s</td></tr>
<tr><td>16-bit aligned little endian</td><td align="right">0.51 s</td><td align="right">0.51 s</td></tr>
<tr><td>16-bit unaligned big endian</td><td align="right">1.36 s</td><td align="right">0.51 s</td></tr>
<tr><td>16-bit unaligned little endian</td><td align="right">1.37 s</td><td align="right">0.51 s</td></tr>
<tr><td>32-bit aligned big endian</td><td align="right" bgcolor="#FFCACA">3.42 s</td><td align="right">0.50 s</td></tr>
<tr><td>32-bit aligned little endian</td><td align="right">0.51 s</td><td align="right">0.51 s</td></tr>
<tr><td>32-bit unaligned big endian</td><td align="right">2.93 s</td><td align="right">0.50 s</td></tr>
<tr><td>32-bit unaligned little endian</td><td align="right">2.95 s</td><td align="right">0.50 s</td></tr>
<tr><td>64-bit aligned big endian</td><td align="right" bgcolor="#FFCACA">5.99 s</td><td align="right">0.33 s</td></tr>
<tr><td>64-bit aligned little endian</td><td align="right">0.33 s</td><td align="right">0.33 s</td></tr>
<tr><td>64-bit unaligned big endian</td><td align="right">7.02 s</td><td align="right">0.27 s</td></tr>
<tr><td>64-bit unaligned little endian</td><td align="right">7.02 s</td><td align="right">0.27 s</td></tr>
<tr><td dir="ltr"><font size="2">16-bit aligned big endian</font></td>
<td align="right" dir="ltr"><font size="2">0.83 s</font></td>
<td align="right" dir="ltr"><font size="2">0.51 s</font></td></tr>
<tr><td dir="ltr"><font size="2">16-bit aligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">0.51 s</font></td>
<td align="right" dir="ltr"><font size="2">0.51 s</font></td></tr>
<tr><td dir="ltr"><font size="2">16-bit unaligned big endian</font></td>
<td align="right" dir="ltr"><font size="2">1.36 s</font></td>
<td align="right" dir="ltr"><font size="2">0.51 s</font></td></tr>
<tr><td dir="ltr"><font size="2">16-bit unaligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">1.37 s</font></td>
<td align="right" dir="ltr"><font size="2">0.51 s</font></td></tr>
<tr><td dir="ltr"><font size="2">32-bit aligned big endian</font></td>
<td align="right" bgcolor="#FFCACA" dir="ltr"><font size="2">3.42 s</font></td>
<td align="right" dir="ltr"><font size="2">0.50 s</font></td></tr>
<tr><td dir="ltr"><font size="2">32-bit aligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">0.51 s</font></td>
<td align="right" dir="ltr"><font size="2">0.51 s</font></td></tr>
<tr><td dir="ltr"><font size="2">32-bit unaligned big endian</font></td>
<td align="right" dir="ltr"><font size="2">2.93 s</font></td>
<td align="right" dir="ltr"><font size="2">0.50 s</font></td></tr>
<tr><td dir="ltr"><font size="2">32-bit unaligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">2.95 s</font></td>
<td align="right" dir="ltr"><font size="2">0.50 s</font></td></tr>
<tr><td dir="ltr"><font size="2">64-bit aligned big endian</font></td>
<td align="right" bgcolor="#FFCACA" dir="ltr"><font size="2">5.99 s</font></td>
<td align="right" dir="ltr"><font size="2">0.33 s</font></td></tr>
<tr><td dir="ltr"><font size="2">64-bit aligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">0.33 s</font></td>
<td align="right" dir="ltr"><font size="2">0.33 s</font></td></tr>
<tr><td dir="ltr"><font size="2">64-bit unaligned big endian</font></td>
<td align="right" dir="ltr"><font size="2">7.02 s</font></td>
<td align="right" dir="ltr"><font size="2">0.27 s</font></td></tr>
<tr><td dir="ltr"><font size="2">64-bit unaligned little endian</font></td>
<td align="right" dir="ltr"><font size="2">7.02 s</font></td>
<td align="right" dir="ltr"><font size="2">0.27 s</font></td></tr>
</table>
@@ -487,9 +577,9 @@ paramount.</p>
<p><b>Which is better, big-endian or little-endian?</b></p>
<blockquote>
<p>Big-endian tends to be a
bit more of an industry standard, but little-endian may be preferred for
applications that run primarily Intel/AMD on x86, x64, and other little-endian
<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
CPU's. The <a href="http://en.wikipedia.org/wiki/Endian">Wikipedia</a> article
gives more pros and cons.</p>
</blockquote>
@@ -498,7 +588,7 @@ gives more pros and cons.</p>
<blockquote>
<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
but have no relevance to C++ developers.</p>
but have no relevance to today&#39;s C++ developers.</p>
</blockquote>
<p><b>What are the limitations of floating point support?</b></p>
@@ -541,7 +631,7 @@ and 16, 32, and 64-bit aligned integers.</p>
<li>Both return-by-value and modify-in-place interfaces are provided, as
requested.</li>
<li>Synonyms for the BSD byte swapping function names popularized by OS X
and Linux are provided, so that that developers already used to these name
and Linux are provided, so that that developers already used to these names
can continue to use them if they wish.</li>
<li>In addition to the named-endianness functions, functions that perform
compile-time (via template) and run-time (via function argument) dispatch
@@ -553,13 +643,20 @@ and 16, 32, and 64-bit aligned integers.</p>
<li>For the endian types, the implementation uses the endian conversion functions,
and thus the intrinsics,
as requested.</li>
<li><code>order::native</code> is now a synonym for <code>order::big</code>
or <code>order::little</code> according to the endianness of the platform, as
requested. This reduces the number of template specializations required.</li>
<li><code>reverse_value()</code> overloads for <code>int8_t</code> and <code>
uint8_t</code> have been added for improved generality. (Pierre Talbot)</li>
<li>Overloads of <code>reverse()</code> have been replaced with a single <code>
reverse()</code> template. (Pierre Talbot)</li>
<li>C++11 features such as <code>noexcept</code> are now used, while still
supporting C++03 compilers.</li>
<li>Acknowledgements have been updated.</li>
<li>Headers have been reorganized to make them easier to read,
with a synopsis at the front and implementation following, as requested.</li>
<li>Documentation has been revised to address most, but not all, concerns
raised during formal review.</li>
<li>Acknowledgements have been updated.</li>
</ul>
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
@@ -573,7 +670,7 @@ 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 -->16 April, 2014<!--webbot bot="Timestamp" endspan i-checksum="29929" --></p>
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->12 August, 2014<!--webbot bot="Timestamp" endspan i-checksum="34569" --></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>

57
doc/types.html
View File

@@ -207,6 +207,7 @@ will no longer be relying on unspecified behavior.</p>
<p>Two scoped enums are provided:</p>
<blockquote>
<pre>enum class order {big, little, native};
enum class align {no, yes}; </pre>
</blockquote>
<p>One class template is provided:</p>
@@ -349,7 +350,13 @@ usual operations on integers are supplied.</p>
{
// C++11 features emulated if not available
enum class <a name="endianness">order</a> {big, little, native};
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};
template &lt;order Order, typename T, std::size_t n_bits, align A = align::no&gt;
@@ -467,28 +474,31 @@ usual operations on integers are supplied.</p>
typedef endian&lt;order::little, uint_least64_t, 56&gt; little_uint56_t;
typedef endian&lt;order::little, uint_least64_t, 64&gt; little_uint64_t;
// unaligned native endian signed integer types
typedef endian&lt;order::native, int_least8_t, 8&gt; native_int8_t;
typedef endian&lt;order::native, int_least16_t, 16&gt; native_int16_t;
typedef endian&lt;order::native, int_least32_t, 24&gt; native_int24_t;
typedef endian&lt;order::native, int_least32_t, 32&gt; native_int32_t;
typedef endian&lt;order::native, int_least64_t, 40&gt; native_int40_t;
typedef endian&lt;order::native, int_least64_t, 48&gt; native_int48_t;
typedef endian&lt;order::native, int_least64_t, 56&gt; native_int56_t;
typedef endian&lt;order::native, int_least64_t, 64&gt; native_int64_t;
// unaligned native endian unsigned integer types
typedef endian&lt;order::native, uint_least8_t, 8&gt; native_uint8_t;
typedef endian&lt;order::native, uint_least16_t, 16&gt; native_uint16_t;
typedef endian&lt;order::native, uint_least32_t, 24&gt; native_uint24_t;
typedef endian&lt;order::native, uint_least32_t, 32&gt; native_uint32_t;
typedef endian&lt;order::native, uint_least64_t, 40&gt; native_uint40_t;
typedef endian&lt;order::native, uint_least64_t, 48&gt; native_uint48_t;
typedef endian&lt;order::native, uint_least64_t, 56&gt; native_uint56_t;
typedef endian&lt;order::native, uint_least64_t, 64&gt; native_uint64_t;
// unaligned native endian signed integer types
typedef <b><i>implementation-defined</i></b>_int8_t native_int8_t;
typedef <b><i>implementation-defined</i></b>_int16_t native_int16_t;
typedef <b><i>implementation-defined</i></b>_int24_t native_int24_t;
typedef <b><i>implementation-defined</i></b>_int32_t native_int32_t;
typedef <b><i>implementation-defined</i></b>_int40_t native_int40_t;
typedef <b><i>implementation-defined</i></b>_int48_t native_int48_t;
typedef <b><i>implementation-defined</i></b>_int56_t native_int56_t;
typedef <b><i>implementation-defined</i></b>_int64_t native_int64_t;
// unaligned native endian unsigned integer types
typedef <b><i>implementation-defined</i></b>_uint8_t native_uint8_t;
typedef <b><i>implementation-defined</i></b>_uint16_t native_uint16_t;
typedef <b><i>implementation-defined</i></b>_uint24_t native_uint24_t;
typedef <b><i>implementation-defined</i></b>_uint32_t native_uint32_t;
typedef <b><i>implementation-defined</i></b>_uint40_t native_uint40_t;
typedef <b><i>implementation-defined</i></b>_uint48_t native_uint48_t;
typedef <b><i>implementation-defined</i></b>_uint56_t native_uint56_t;
typedef <b><i>implementation-defined</i></b>_uint64_t native_uint64_t;
} // namespace endian
} // namespace boost</pre>
<p>The <i><b><code>implementation-defined</code></b></i> text above is either
<code>big</code> or <code>little</code> according to the endianness of the
platform.</p>
<h3><a name="Members">Members</a></h3>
<div dir="ltr">
<pre><code><a name="endian">endian</a>() = default; // C++03: endian(){}</code></pre>
@@ -568,13 +578,10 @@ incrementing a variable in a record. It is very convenient to write:</p>
representation) regardless of whether a compiler treats char as signed or
unsigned.</li>
<li>Unaligned types must not cause compilers to insert padding bytes.</li>
<li>The implementation should supply optimizations only in very limited
circumstances. Experience has shown that optimizations of endian
<li>The implementation should supply optimizations with great care. Experience has shown that optimizations of endian
integers often become pessimizations when changing
machines or compilers. Pessimizations can also happen when changing compiler switches,
compiler versions, or CPU models of the same architecture.</li>
<li>It is better software engineering if the same implementation works regardless
of the CPU endianness. In other words, #ifdefs should be avoided in user code.</li>
</ul>
<h2><a name="Experience">Experience</a></h2>
<p>Classes with similar functionality have been independently developed by
@@ -621,7 +628,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 -->06 September, 2013<!--webbot bot="Timestamp" endspan i-checksum="39344" --></p>
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->12 August, 2014<!--webbot bot="Timestamp" endspan i-checksum="34569" --></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>

28
doc/vc++readme.txt
View File

@@ -3,30 +3,28 @@ Windows
Prerequisites
BOOST_TRUNK environmental variable set to the path to a current Boost trunk checkout.
Example:
setx BOOST_TRUNK=c:\boost\trunk
Boost libraries available in %BOOST_TRUNK%\stage\lib. Example:
Boost libraries available in boost-root\stage\lib. Example:
cd %BOOST_TRUNK%
cd boost-root
.\bootstrap
.\b2 --with-system --with-chrono --with-timer link=shared stage
path environmental variable set to include %BOOST_TRUNK%\stage\lib. Example:
The provided Visual Studio solution (endian/test/msvc/endian.sln) has a property page
(endian/test/msvc/common.prop) with these Common Properties set (do not include the
double quotes):
VC++ Directores|Executable Directories: prefix default value with "..\..\..\..\..\stage\lib;"
(Click "Inherit from parent or project defaults" if not checked)
C/C++|General|Additional Include Directories: prefix default value with "..\..\..\..\..\stage\lib;"
path %path%;%BOOST_TRUNK%\stage\lib
Linker|General|Additional Library Directories: prefix default value with "..\..\..\..\..\stage\lib;"
The provided Visual Studio solution (endian/test/msvc2012/endian.sln) has these Property
setups:
C/C++|General|Additional Include Directories: prefix ..\..\..\..\endian\include;$(BOOST_TRUNK);
C/C++|Preprocessor: prefix BOOST_ALL_DYN_LINK;
Linker|General|Additional Library Directories: $(BOOST_TRUNK)\stage\lib
C/C++|Preprocessor: prefix default value with "BOOST_ALL_DYN_LINK;"
IMPORTANT: If Preprocessor macros are supplied via a common property page,
<inherit from parent or project defaults> must be set for each project!
------------------------------------------------------------------------------------------
Copyright Beman Dawes, 2013
Distributed under the Boost Software License, Version 1.0.