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>
<meta http-equiv="Content-Language" content="en-us">
@@ -17,7 +17,7 @@
<tr>
<td>
<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">
<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
--------------------------------------------------
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>
<td>
<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">
<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>
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
@@ -15,7 +15,7 @@
<tr>
<td>
<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">
<b>
<font size="6">Endian Conversion Functions</font></b></td>

105
index.html
View File

@@ -15,7 +15,7 @@
<tr>
<td width="339">
<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">
<b>
<font size="6">Endian Library</font></b></td>
@@ -39,17 +39,31 @@
</tr>
<tr>
<td width="100%" bgcolor="#E8F5FF">
<a href="#Abstract">Abstract</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="#Choosing">Choosing approaches</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>
<a href="#FAQ">FAQ</a><br>
<a href="#Release-history">Release history</a><br>
<a href="#Acknowledgements">Acknowledgements</a></td>
<a href="#Abstract">Abstract</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="#Choosing">Choosing between conversion, buffer types,</a><br>
&nbsp;<a href="#Choosing">and arithmetic types</a><br>
&nbsp;&nbsp;&nbsp;<a href="#Characteristics">Characteristics</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Endianness-invariants">Endianness invariants</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Conversion-explicitness">Conversion explicitness</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Arithmetic-operations">Arithmetic operations</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Sizes">Sizes</a><br>
&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>
<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
Windows-based operating systems traditionally supply libraries with
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>
&nbsp;</li>
</ul>
</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>
<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
preferred over the other approaches.</li>
</ul>
<p>&nbsp;</p>
<p>&nbsp;</p>
<h2><a name="Introduction-to-endianness">Introduction to endianness</a></h2>
<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>
<h2><a name="Choosing">Choosing</a> between endian conversion functions, endian buffer types,
and endian arithmetic types</h2>
<h2><a name="Choosing">Choosing</a> between conversion functions, buffer types,
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 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
alignment requirements.</p>
<h4>Endianness invariants</h4>
<h4><a name="Endianness-invariants">Endianness invariants</a></h4>
<blockquote>
@@ -193,11 +215,11 @@ find bugs.</p>
<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.
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>
<h4>Conversion explicitness</h4>
<h4><a name="Conversion-explicitness">Conversion explicitness</a></h4>
<blockquote>
@@ -211,7 +233,7 @@ to hoist conversions out of inner loops can bring a performance penalty.</p>
</blockquote>
<h4>Arithmetic operations</h4>
<h4><a name="Arithmetic-operations">Arithmetic operations</a></h4>
<blockquote>
@@ -228,7 +250,7 @@ are very easy to use if lots of arithmetic is involved. </p>
</blockquote>
<h4>Sizes available</h4>
<h4><a name="Sizes">Sizes</a></h4>
<blockquote>
@@ -241,7 +263,7 @@ factor, using sizes tailored to application needs can be useful.</p>
</blockquote>
<h4>Alignments available</h4>
<h4><a name="Alignments">Alignments</a></h4>
<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>
<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
<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
@@ -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
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>,
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>
<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
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
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
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
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>
@@ -727,7 +764,7 @@ and 16, 32, and 64-bit aligned integers.</p>
</blockquote>
<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>
<li>
<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>
<hr>
<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>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>

20
mini_review_topics.html
View File

@@ -3,7 +3,7 @@
<head>
<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">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Endian Mini-Review</title>
</head>
<link href="styles.css" rel="stylesheet">
@@ -18,7 +18,7 @@
<p><b>Common use case scenarios should be developed.</b></p>
<blockquote>
<p>&nbsp;</p>
<p>Done. See <a href="index.html#Use-cases">Use cases</a>.</p>
</blockquote>
<p><b>Example programs should be developed for the common use case scenarios.</b></p>
<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
approach in user's applications.</b></p>
<blockquote>
<p>Done. See <a href="index.html#Choosing">Choosing between
<span style="background-color: #FFFF00">endian types</span> and
endian conversion functions</a>.</p>
<p>Done. See <a href="index.html#Choosing">Choosing between endian conversion
functions, endian buffer types, and endian arithmetic types</a>.</p>
</blockquote>
<p><b>Conversion functions supplying results via return should be provided.</b></p>
<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>
<blockquote>
<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>
<p><b>Float (32-bits) and double (64-bits) should be supported. IEEE 754 is
the primary use case.</b></p>
<blockquote>
<p>Done. The <a href="types.html">endian types</a> and
<a href="conversion.html">endian conversion</a> functions now support 32-bit (<code>float)</code>
<p>Done. The <a href="buffers.html">endian buffer types</a>,&nbsp;
<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>
</blockquote>
<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>
<hr>
<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>
<p><EFBFBD> Copyright Beman Dawes, 2014</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, 2014</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>

6
styles.css
View File

@@ -10,4 +10,10 @@ body
pre {background-color: #D7EEFF; font-size: 100%;}
code {font-size: 110%;}
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 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">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Endian Library Do List</title>
</head>
@@ -13,7 +13,7 @@
<h1>Endian Library TODO List</h1>
<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
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>
<p>Support IEEE754 format (32 bit, 64 bit) only.</p>
<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>
</body>