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

copy from develop

Browse Source
This commit is contained in:
Beman
2014-12-17 17:49:56 -05:00
parent 3fafd83028
commit d92aa4550a
8 changed files with 103 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
arithmetic.html
View File

@@ -1,4 +1,4 @@
<html> <html>
<head> <head>
<meta http-equiv="Content-Language" content="en-us"> <meta http-equiv="Content-Language" content="en-us">
@@ -17,7 +17,7 @@
<tr> <tr>
<td> <td>
<a href="../../../index.html"> <a href="../../../index.html">
<img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" border="0" width="277" height="86"></a></td> <img src="http://www.boost.org/boost.png" alt="Boost logo" align="middle" border="0" width="277" height="86"></a></td>
<td align="middle"> <td align="middle">
<b> <b>
<font size="6">Endian Arithmetic Types</font> </b> <font size="6">Endian Arithmetic Types</font> </b>

4
bikeshed.txt
View File

@@ -70,6 +70,10 @@ flip (verb)
: to move (something) with a quick light movement : to move (something) with a quick light movement
--------------------------------------------------
Copyright Beman Dawes, 2014
Distributed under the Boost Software License, Version 1.0.
See www.boost.org/LICENSE_1_0.txt

2
buffers.html
View File

@@ -17,7 +17,7 @@
<tr> <tr>
<td> <td>
<a href="../../../index.html"> <a href="../../../index.html">
<img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" border="0" width="277" height="86"></a></td> <img src="http://www.boost.org/boost.png" alt="Boost logo" align="middle" border="0" width="277" height="86"></a></td>
<td align="middle"> <td align="middle">
<b> <b>
<font size="6">Endian Buffer Types</font> </b> <font size="6">Endian Buffer Types</font> </b>

4
conversion.html
View File

@@ -1,4 +1,4 @@
<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns="http://www.w3.org/TR/REC-html40"> <html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns="http://www.w3.org/TR/REC-html40">
<head> <head>
<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> <meta name="GENERATOR" content="Microsoft FrontPage 5.0">
@@ -15,7 +15,7 @@
<tr> <tr>
<td> <td>
<a href="../../../index.html"> <a href="../../../index.html">
<img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" border="0" width="277" height="86" ></a></td> <img src="http://www.boost.org/boost.png" alt="Boost logo" align="middle" border="0" width="277" height="86" ></a></td>
<td align="middle"> <td align="middle">
<b> <b>
<font size="6">Endian Conversion Functions</font></b></td> <font size="6">Endian Conversion Functions</font></b></td>

105
index.html
View File

@@ -15,7 +15,7 @@
<tr> <tr>
<td width="339"> <td width="339">
<a href="../../../index.html"> <a href="../../../index.html">
<img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" border="0" width="277" height="86"></a></td> <img src="http://www.boost.org/boost.png" alt="Boost logo" align="middle" border="0" width="277" height="86"></a></td>
<td align="middle" width="1253"> <td align="middle" width="1253">
<b> <b>
<font size="6">Endian Library</font></b></td> <font size="6">Endian Library</font></b></td>
@@ -39,17 +39,31 @@
</tr> </tr>
<tr> <tr>
<td width="100%" bgcolor="#E8F5FF"> <td width="100%" bgcolor="#E8F5FF">
<a href="#Abstract">Abstract</a><br> <a href="#Abstract">Abstract</a><br>
<a href="#Introduction-to-endianness">Introduction to endianness</a><br> <a href="#Introduction-to-endianness">Introduction to endianness</a><br>
<a href="#Introduction">Introduction to the Boost.Endian library</a><br> <a href="#Introduction">Introduction to the Boost.Endian library</a><br>
<a href="#Choosing">Choosing approaches</a><br> <a href="#Choosing">Choosing between conversion, buffer types,</a><br>
<a href="#Intrinsic">Built-in support for Intrinsics</a><br> &nbsp;<a href="#Choosing">and arithmetic types</a><br>
<a href="#Performance">Performance</a><br> &nbsp;&nbsp;&nbsp;<a href="#Characteristics">Characteristics</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Timings">Timings</a><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Endianness-invariants">Endianness invariants</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Conclusions">Conclusions</a><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Conversion-explicitness">Conversion explicitness</a><br>
<a href="#FAQ">FAQ</a><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Arithmetic-operations">Arithmetic operations</a><br>
<a href="#Release-history">Release history</a><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Sizes">Sizes</a><br>
<a href="#Acknowledgements">Acknowledgements</a></td> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Alignments">Alignments</a><br>
&nbsp;&nbsp;&nbsp;<a href="#Use-cases">Use cases</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Porting-endian-unaware-codebase">Porting endian unaware codebase</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Porting-endian-aware-codebase">Porting endian aware codebase</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Reliability-arithmetic-speed">Reliability and arithmetic-speed</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Reliability-ease-of-use">Reliability and ease-of-use</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 for Example 2</a><br>
&nbsp;&nbsp;&nbsp;<a href="#Conclusions">Conclusions</a><br>
<a href="#FAQ">Overall FAQ</a><br>
<a href="#Release-history">Release history</a><br>
&nbsp;&nbsp;&nbsp;<a href="#Changes-since-formal-review">Changes since formal review</a><br>
<a href="#Acknowledgements">Acknowledgements</a><br>
</td>
</tr> </tr>
<tr> <tr>
<td width="100%" bgcolor="#D7EEFF" align="center"> <td width="100%" bgcolor="#D7EEFF" align="center">
@@ -77,20 +91,23 @@ floating point numbers, and user-defined types.</p>
<li>Program portability. POSIX-based and <li>Program portability. POSIX-based and
Windows-based operating systems traditionally supply libraries with Windows-based operating systems traditionally supply libraries with
non-portable functions to perform endian conversion. There are at least four non-portable functions to perform endian conversion. There are at least four
non-compatible sets of functions in common use. The Endian library is incompatible sets of functions in common use. The Endian library is
portable across all C++ platforms.<br> portable across all C++ platforms.<br>
&nbsp;</li> &nbsp;</li>
</ul> </ul>
</li> </li>
<li>Secondary use case: Minimizing storage size via sizes and/or alignments not supported by the <li>Secondary use case: Minimizing data size via sizes and/or alignments not supported by the
standard C++ arithmetic types.<br> standard C++ arithmetic types.<br>
<br></li> <br></li>
<li>Three approaches to dealing with endianness are provided. Each approach has a <li>Three approaches to dealing with endianness are supported. Each has a
long history of successful use, and each approach has use cases where it is long history of successful use, and each approach has use cases where it is
preferred over the other approaches.</li> preferred over the other approaches.</li>
</ul> </ul>
<p>&nbsp;</p>
<p>&nbsp;</p>
<h2><a name="Introduction-to-endianness">Introduction to endianness</a></h2> <h2><a name="Introduction-to-endianness">Introduction to endianness</a></h2>
<p>Consider the following code:</p> <p>Consider the following code:</p>
@@ -166,20 +183,25 @@ integers. The types may be aligned.</p>
<p>Boost Endian is a header-only library.</p> <p>Boost Endian is a header-only library.</p>
<h2><a name="Choosing">Choosing</a> between endian conversion functions, endian buffer types, <h2><a name="Choosing">Choosing</a> between conversion functions, buffer types,
and endian arithmetic types</h2> and arithmetic types</h2>
<p>The best approach to endianness depends on interaction between <p>The best approach to endianness for a particular use case depends on interactions between
the approach characteristics and the approach characteristics and
the application needs.</p> the application needs.</p>
<h3><a name="Approach-characteristics">Approach characteristics</a></h3> <p><b>Recommendation:</b> If you are uncertain, new to endianness, concerned
about security, concerned about reliability, or don&#39;t want to invest time making
engineering trade-offs, use the <a href="arithmetic.html">endian arithmetic types</a>. They are safer, easier
to use, and your code will be easier to maintain.</p>
<p>The characteristics that differentiate the approaches are the endianness <h3><a name="Characteristics">Characteristics</a></h3>
<p>The characteristics that differentiate the three approaches to endianness are the endianness
invariants, conversion explicitness, arithmetic operations, sizes available, and invariants, conversion explicitness, arithmetic operations, sizes available, and
alignment requirements.</p> alignment requirements.</p>
<h4>Endianness invariants</h4> <h4><a name="Endianness-invariants">Endianness invariants</a></h4>
<blockquote> <blockquote>
@@ -193,11 +215,11 @@ find bugs.</p>
<p><b>Endian buffer and arithmetic types</b> hold values internally as arrays of <p><b>Endian buffer and arithmetic types</b> hold values internally as arrays of
characters with an invariant that the endianness of the array never changes. characters with an invariant that the endianness of the array never changes.
That makes these types easy to use and programs easy to maintain.</p> That makes these types easier to use and programs easier to maintain.</p>
</blockquote> </blockquote>
<h4>Conversion explicitness</h4> <h4><a name="Conversion-explicitness">Conversion explicitness</a></h4>
<blockquote> <blockquote>
@@ -211,7 +233,7 @@ to hoist conversions out of inner loops can bring a performance penalty.</p>
</blockquote> </blockquote>
<h4>Arithmetic operations</h4> <h4><a name="Arithmetic-operations">Arithmetic operations</a></h4>
<blockquote> <blockquote>
@@ -228,7 +250,7 @@ are very easy to use if lots of arithmetic is involved. </p>
</blockquote> </blockquote>
<h4>Sizes available</h4> <h4><a name="Sizes">Sizes</a></h4>
<blockquote> <blockquote>
@@ -241,7 +263,7 @@ factor, using sizes tailored to application needs can be useful.</p>
</blockquote> </blockquote>
<h4>Alignments available</h4> <h4><a name="Alignments">Alignments</a></h4>
<blockquote> <blockquote>
@@ -272,9 +294,24 @@ needed they are often very useful and workarounds are painful. For example,</p>
<h3><a name="Use-cases">Use cases</a></h3> <h3><a name="Use-cases">Use cases</a></h3>
<h4>Program portability use case</h4> <h4><a name="Porting-endian-unaware-codebase">Porting endian unaware codebase</a></h4>
<p>An existing large codebase runs on little-endian Linux systems. It already <p>An existing codebase runs on big endian systems. It does not
currently deal with endianness. The codebase needs to be modified so it can run
on&nbsp; little endian systems under various operating systems. To ease
transition and protect value of existing files, external data will continue to
be maintained as big endian.</p>
<p dir="ltr">The <a href="arithmetic.html">endian
arithmetic approach</a> is recommended to meet these needs. A relatively small
number of header files dealing with binary I/O layouts need to change types like
<code>short</code> or <code>int16_t</code> to <code>big_int16_t</code>, and
<code>int</code> or <code>int32_t</code> to <code>bif_int32_t</code>. No
changes are required for <code>.cpp</code> files.</p>
<h4><a name="Porting-endian-aware-codebase">Porting endian aware codebase</a></h4>
<p>An existing codebase runs on little-endian Linux systems. It already
deals with endianness via deals with endianness via
<a href="http://man7.org/linux/man-pages/man3/endian.3.html">Linux provided <a href="http://man7.org/linux/man-pages/man3/endian.3.html">Linux provided
functions</a>. Because of a business merger, the codebase has to be quickly functions</a>. Because of a business merger, the codebase has to be quickly
@@ -282,12 +319,12 @@ modified for Windows and possibly other operating systems, while still
supporting Linux. The codebase is reliable and the programmers are all supporting Linux. The codebase is reliable and the programmers are all
well-aware of endian issues. </p> well-aware of endian issues. </p>
<p>These factors all argue for an <a href="conversion.html">endian conversion <p dir="ltr">These factors all argue for an <a href="conversion.html">endian conversion
approach</a> that just mechanically changes the calls to <code>htobe32</code>, approach</a> that just mechanically changes the calls to <code>htobe32</code>,
etc. to <code>boost::endian::native_to_big</code>, etc. and replaces <code>&lt;endian.h&gt;</code> etc. to <code>boost::endian::native_to_big</code>, etc. and replaces <code>&lt;endian.h&gt;</code>
with <code>&lt;boost/endian/conversion.hpp&gt;</code>.</p> with <code>&lt;boost/endian/conversion.hpp&gt;</code>.</p>
<h4>Reliability and arithmetic-speed use case</h4> <h4><a name="Reliability-arithmetic-speed">Reliability and arithmetic-speed</a></h4>
<p>A new, complex, multi-threaded application is to be developed that must run <p>A new, complex, multi-threaded application is to be developed that must run
on little endian machines, but do big endian network I/O. The developers believe on little endian machines, but do big endian network I/O. The developers believe
@@ -299,7 +336,7 @@ slow conversions if full-blown endian arithmetic types are used.</p>
<p>The <a href="buffers.html">endian buffers</a> approach is made-to-order for <p>The <a href="buffers.html">endian buffers</a> approach is made-to-order for
this use case.</p> this use case.</p>
<h4>Reliability and ease-of-use use case</h4> <h4><a name="Reliability-ease-of-use">Reliability and ease-of-use</a></h4>
<p>A new, complex, multi-threaded application is to be developed that must run <p>A new, complex, multi-threaded application is to be developed that must run
on little endian machines, but do big endian network I/O. The developers believe on little endian machines, but do big endian network I/O. The developers believe
@@ -640,7 +677,7 @@ determine if some coding technique has significant impact on performance.</p>
<p><b>Unaligned types are much slower that aligned types, regardless of <p><b>Unaligned types are much slower that aligned types, regardless of
endianness considerations.</b> Instead of single instruction register loads and endianness considerations.</b> Instead of single instruction register loads and
stores, multiple instructions are required.</p> stores, multiple instructions are required on common platforms.</p>
</blockquote> </blockquote>
@@ -727,7 +764,7 @@ and 16, 32, and 64-bit aligned integers.</p>
</blockquote> </blockquote>
<h2><a name="Release-history">Release history</a></h2> <h2><a name="Release-history">Release history</a></h2>
<h3>Changes since formal review</h3> <h3><a name="Changes-since-formal-review">Changes since formal review</a></h3>
<ul> <ul>
<li> <li>
<p>The endian types have been decomposed into endian buffer types <p>The endian types have been decomposed into endian buffer types
@@ -788,7 +825,7 @@ Blechmann, Tim Moore, tymofey, Tomas Puverle, Vincente Botet, Yuval Ronen and
Vitaly Budovski,.</p> Vitaly Budovski,.</p>
<hr> <hr>
<p>Last revised: <p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->16 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38645" --></p> <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->17 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38647" --></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>

20
mini_review_topics.html
View File

@@ -3,7 +3,7 @@
<head> <head>
<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> <meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document"> <meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Endian Mini-Review</title> <title>Endian Mini-Review</title>
</head> </head>
<link href="styles.css" rel="stylesheet"> <link href="styles.css" rel="stylesheet">
@@ -18,7 +18,7 @@
<p><b>Common use case scenarios should be developed.</b></p> <p><b>Common use case scenarios should be developed.</b></p>
<blockquote> <blockquote>
<p>&nbsp;</p> <p>Done. See <a href="index.html#Use-cases">Use cases</a>.</p>
</blockquote> </blockquote>
<p><b>Example programs should be developed for the common use case scenarios.</b></p> <p><b>Example programs should be developed for the common use case scenarios.</b></p>
<blockquote> <blockquote>
@@ -29,9 +29,8 @@ integer/float type and endian conversion approaches to the common use
case scenarios, and provide guidelines for choosing the most appropriate case scenarios, and provide guidelines for choosing the most appropriate
approach in user's applications.</b></p> approach in user's applications.</b></p>
<blockquote> <blockquote>
<p>Done. See <a href="index.html#Choosing">Choosing between <p>Done. See <a href="index.html#Choosing">Choosing between endian conversion
<span style="background-color: #FFFF00">endian types</span> and functions, endian buffer types, and endian arithmetic types</a>.</p>
endian conversion functions</a>.</p>
</blockquote> </blockquote>
<p><b>Conversion functions supplying results via return should be provided.</b></p> <p><b>Conversion functions supplying results via return should be provided.</b></p>
<blockquote> <blockquote>
@@ -59,13 +58,14 @@ portable base implementations, and to compare endian integer approaches
against endian conversion approaches for the common use case scenarios.</b></p> against endian conversion approaches for the common use case scenarios.</b></p>
<blockquote> <blockquote>
<p>Done. See <a href="index.html#Timings">Timings for Example 2</a>. The <code>endian/test</code> directory <p>Done. See <a href="index.html#Timings">Timings for Example 2</a>. The <code>endian/test</code> directory
also contains several addional benchmark and speed test programs.</p> also contains several additional benchmark and speed test programs.</p>
</blockquote> </blockquote>
<p><b>Float (32-bits) and double (64-bits) should be supported. IEEE 754 is <p><b>Float (32-bits) and double (64-bits) should be supported. IEEE 754 is
the primary use case.</b></p> the primary use case.</b></p>
<blockquote> <blockquote>
<p>Done. The <a href="types.html">endian types</a> and <p>Done. The <a href="buffers.html">endian buffer types</a>,&nbsp;
<a href="conversion.html">endian conversion</a> functions now support 32-bit (<code>float)</code> <a href="arithmetic.html">endian arithmetic types</a> and
<a href="conversion.html">endian conversion functions</a> now support 32-bit (<code>float)</code>
and 64-bit <code>(double)</code> floating point, as requested.</p> and 64-bit <code>(double)</code> floating point, as requested.</p>
</blockquote> </blockquote>
<p><b>Support for user defined types (UDTs) is desirable, and should be <p><b>Support for user defined types (UDTs) is desirable, and should be
@@ -99,8 +99,8 @@ might used inadvertently or inappropriately. The impact of adding an endian_buff
</blockquote> </blockquote>
<hr> <hr>
<p>Last revised: <p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38642" --></p> <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->17 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38647" --></p>
<p><EFBFBD> Copyright Beman Dawes, 2014</p> <p>© Copyright Beman Dawes, 2014</p>
<p>Distributed under the Boost Software License, Version 1.0. See <p>Distributed under the Boost Software License, Version 1.0. See
<a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/ LICENSE_1_0.txt</a></p> <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/ LICENSE_1_0.txt</a></p>

6
styles.css
View File

@@ -10,4 +10,10 @@ body
pre {background-color: #D7EEFF; font-size: 100%;} pre {background-color: #D7EEFF; font-size: 100%;}
code {font-size: 110%;} code {font-size: 110%;}
table{font-size: 100%;} table{font-size: 100%;}
/*
© Copyright Beman Dawes, 2014
Distributed under the Boost Software License, Version 1.0.
See www.boost.org/LICENSE_1_0.txt
*/

10
todo_list.html
View File

@@ -4,7 +4,7 @@
<meta http-equiv="Content-Language" content="en-us"> <meta http-equiv="Content-Language" content="en-us">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> <meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document"> <meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Endian Library Do List</title> <title>Endian Library Do List</title>
</head> </head>
@@ -13,7 +13,7 @@
<h1>Endian Library TODO List</h1> <h1>Endian Library TODO List</h1>
<p>Last revised: <p>Last revised:
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->15 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38643" --></p> <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->17 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38647" --></p>
<p><b>August 12, 2014: The many items that have been completed should be <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> removed, after verifying that they are in fact taken care of.</b></p>
@@ -224,7 +224,11 @@ types that mimic FP types is far beyond my knowledge of how to deal<br>
with floating point's notorious arithmetic issues.</p> with floating point's notorious arithmetic issues.</p>
<p>Support IEEE754 format (32 bit, 64 bit) only.</p> <p>Support IEEE754 format (32 bit, 64 bit) only.</p>
<hr> <hr>
<p>&nbsp;</p> <p>Last revised:
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->17 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38647" --></p>
<p>© Copyright Beman Dawes, 2012</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>&nbsp;</p> <p>&nbsp;</p>
</body> </body>