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

Add additional use case

Browse Source
This commit is contained in:
Beman
2014-12-17 11:57:35 -05:00
parent 25a00586a2
commit 79709fe054
1 changed files with 27 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
doc/index.html
View File

@@ -83,7 +83,7 @@ floating point numbers, and user-defined types.</p>
</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 provided. Each approach has a
@@ -169,13 +169,18 @@ integers. The types may be aligned.</p>
<h2><a name="Choosing">Choosing</a> between endian conversion functions, endian buffer types, <h2><a name="Choosing">Choosing</a> between endian conversion functions, endian buffer types,
and endian arithmetic types</h2> and endian 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>
<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 endian arithmetic types. They are safer, easier
to use, and your code will be easier to maintain.</p>
<h3><a name="Approach-characteristics">Approach characteristics</a></h3> <h3><a name="Approach-characteristics">Approach characteristics</a></h3>
<p>The characteristics that differentiate the approaches are the endianness <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>
@@ -193,7 +198,7 @@ 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>
@@ -272,9 +277,9 @@ 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>Porting endian aware codebase</h4>
<p>An existing large codebase runs on little-endian Linux systems. It already <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,11 +287,26 @@ 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>Porting endian unaware codebase</h4>
<p>An existing codebase runs on expensive big endian systems. It does not
currently deal with endianness. The codebase needs to be modified so it can run
on lower-cost 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>little_int16_t</code>, and
<code>int</code> or <code>int32_t</code> to <code>little_int32_t</code>. No
changes are required for <code>.cpp</code> files.</p>
<h4>Reliability and arithmetic-speed use case</h4> <h4>Reliability and arithmetic-speed use case</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