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>
</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
@ -169,13 +169,18 @@ integers. The types may be aligned.</p>
<h2><a name="Choosing">Choosing</a> between endian conversion functions, endian buffer types,
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 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>
<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
alignment requirements.</p>
@ -193,7 +198,7 @@ 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>
@ -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>
<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
<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,11 +287,26 @@ 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>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>
<p>A new, complex, multi-threaded application is to be developed that must run