mirror of
https://github.com/boostorg/endian.git
synced 2025-08-02 05:54:31 +02:00
Last pass through docs
This commit is contained in:
Beman
@@ -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>Boost Endian Conversion Functions</title>
|
||||
<link rel="stylesheet" type="text/css" href="../../../doc/src/minimal.css">
|
||||
@@ -26,7 +26,7 @@
|
||||
<td><b><a href="../../../index.htm">Boost Home</a>
|
||||
<a href="index.html">Endian Home</a>
|
||||
<a href="conversion.html">Conversion Functions</a>
|
||||
<a href="types.html">Endian Types</a> Tutorial</b></td>
|
||||
<a href="types.html">Endian Types</a></b></td>
|
||||
</tr>
|
||||
</table>
|
||||
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" align="right">
|
||||
@@ -37,12 +37,11 @@
|
||||
<tr>
|
||||
<td width="100%" bgcolor="#E8F5FF">
|
||||
<a href="#Introduction">Introduction</a><br>
|
||||
<a href="#FAQ">conversion.hpp FAQ</a><br>
|
||||
<a href="#Reference">Reference</a><br>
|
||||
<a href="#Synopsis">Synopsis</a><br>
|
||||
<a href="#Requirements">Requirements</a><br>
|
||||
<a href="#Functions">Functions</a><br>
|
||||
<a href="#Intrinsic">Intrinsic built-in support</a><br>
|
||||
<a href="#FAQ">FAQ</a><br>
|
||||
<a href="#Acknowledgements">Acknowledgements</a></td>
|
||||
</tr>
|
||||
<tr>
|
||||
@@ -58,13 +57,6 @@
|
||||
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
|
||||
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
|
||||
<tr>
|
||||
<td bgcolor="#FFFFCC">Please: If you haven't done so already, read
|
||||
<a href="index.html#Introduction-to-endianness">Introduction to endianness</a>!</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p>Header <a href="../../../boost/endian/conversion.hpp">boost/endian/conversion.hpp</a>
|
||||
provides byte order reversal and conversion functions that convert objects of
|
||||
the multi-byte built-in
|
||||
@@ -79,70 +71,6 @@ ordering. User defined types are also supported.</p>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h2>conversion.hpp <a name="FAQ">FAQ</a></h2>
|
||||
|
||||
<p><b>Is the implementation header only?</b></p>
|
||||
|
||||
<blockquote>
|
||||
|
||||
<p>Yes.</p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<p><b>Does the implementation use compiler intrinsic built-in byte swapping?</b></p>
|
||||
|
||||
<blockquote>
|
||||
|
||||
<p>Yes, if available. See <a href="#Intrinsic">Intrinsic built-in support</a>
|
||||
below.</p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<p><b>Why are the template versions of <code>reverse()</code> and <code>reverse_value()</code>
|
||||
in a detail namespace?</b></p>
|
||||
|
||||
<blockquote>
|
||||
|
||||
<p>They are unsafe for general use. Consider reversing
|
||||
the bytes of a <code>std::pai<b>r</b></code> as a whole - the bytes from <code>first</code>
|
||||
would end up in <code>second</code> and visa versa, and this is totally
|
||||
wrong!</p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<p><b>Why are both value returning and modify-in-place functions provided?</b></p>
|
||||
|
||||
<blockquote>
|
||||
|
||||
<p>Returning the result by value is the standard C and C++ idiom for functions that compute a
|
||||
value from an argument. Modify-in-place functions allow cleaner code in many real-world
|
||||
endian use cases and are more efficient for user defined types that have
|
||||
members such as string data that do not need to be reversed. Thus both forms are
|
||||
provided.</p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<p><b>What are the limitations of floating point support?</b></p>
|
||||
|
||||
<blockquote>
|
||||
|
||||
<p>The only supported types are four byte <code>float</code> and eight byte
|
||||
<code>double</code>. Even after endianness has been accounted for, floating
|
||||
point values will not be portable between systems that use different floating
|
||||
point formats. Systems where the integer endianness and floating point
|
||||
endianness are not supported.</p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<p><b>What are the limitations of integer support?</b></p>
|
||||
|
||||
<blockquote>
|
||||
|
||||
<p>Only 16-bit, 32-bit, and 64-bit integers are supported. Tests have been
|
||||
performed on machines that use two's complement arithmetic.</p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<h2><a name="Reference">Reference</a></h2>
|
||||
|
||||
<p>Functions are implemented <code>inline</code> if appropriate.<code> noexcept</code> is
|
||||
@@ -152,7 +80,7 @@ Boost scoped enum emulation is used so that the library still works for compiler
|
||||
<h3>
|
||||
<a name="Synopsis">Synopsis</a></h3>
|
||||
|
||||
<pre>#define BOOST_ENDIAN_INTRINSIC_MSG "message describing presence or absence of intrinsics"
|
||||
<pre>#define BOOST_ENDIAN_INTRINSIC_MSG "<b><font face="Arial"><i>message describing presence or absence of intrinsics</i></font></b>"
|
||||
|
||||
namespace boost
|
||||
{
|
||||
@@ -297,27 +225,27 @@ void reverse(double& x) noexcept;</pre>
|
||||
<a name="big_endian"></a>template <class Reversible>
|
||||
void big_endian(Reversible& x) noexcept;</pre>
|
||||
<blockquote>
|
||||
<p dir="ltr"><i>Returns (first form)</i>: <code>x</code> if the native byte order is big
|
||||
<p><i>Returns (first form)</i>: <code>x</code> if the native byte order is big
|
||||
endian, otherwise <code>reverse_value(x)</code>.</p>
|
||||
<p dir="ltr"><i>Effects (second form):</i> None if the native byte order is big
|
||||
<p><i>Effects (second form):</i> None if the native byte order is big
|
||||
endian, otherwise <code>reverse(x)</code>.</p>
|
||||
<p dir="ltr"><i>Example:</i></p>
|
||||
<p><i>Example:</i></p>
|
||||
<blockquote>
|
||||
<pre>int32_t x = <b><i>some-value</i></b>;
|
||||
big_endian(x); // reverses the byte order of x, unless
|
||||
// the native byte order is big-endian</pre>
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
<pre dir="ltr"><a name="little_endian_value"></a>template <class ReversibleValue >
|
||||
<pre><a name="little_endian_value"></a>template <class ReversibleValue >
|
||||
ReversibleValue little_endian_value(ReversibleValue x) noexcept;
|
||||
<a name="little_endian"></a>template <class Reversible>
|
||||
void little_endian(Reversible& x) noexcept;</pre>
|
||||
<blockquote>
|
||||
<p dir="ltr"><i>Returns (first form)</i>: <code>x</code> if the native byte order is little
|
||||
<p><i>Returns (first form)</i>: <code>x</code> if the native byte order is little
|
||||
endian, otherwise <code>reverse_value(x)</code>.</p>
|
||||
<p dir="ltr"><i>Effects (second form):</i> None if the native byte order is little
|
||||
<p><i>Effects (second form):</i> None if the native byte order is little
|
||||
endian, otherwise <code>reverse(x)</code>.</p>
|
||||
<p dir="ltr"><i>Example:</i></p>
|
||||
<p><i>Example:</i></p>
|
||||
<blockquote>
|
||||
<pre>int32_t x = <b><i>some-value</i></b>;
|
||||
int32_t y(little_endian(x));
|
||||
@@ -325,51 +253,84 @@ int32_t y(little_endian(x));
|
||||
// the native byte order is little-endian.</pre>
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
<pre dir="ltr"><a name="convert_value_generic"></a>template <order From, order To, class ReversibleValue>
|
||||
<pre><a name="convert_value_generic"></a>template <order From, order To, class ReversibleValue>
|
||||
ReversibleValue convert_value(ReversibleValue from) noexcept;
|
||||
<a name="convert_generic"></a>template <order From, order To, class Reversible>
|
||||
void convert(Reversible& x) noexcept;
|
||||
</pre>
|
||||
<blockquote>
|
||||
<p dir="ltr">The <b><i>effective order</i></b> of an order template parameter
|
||||
<p>The <b><i>effective order</i></b> of an order template parameter
|
||||
is the same as the order template parameter if the parameter is not <code>
|
||||
order::native</code>, otherwise it is the constant <code>order::big</code> or
|
||||
<code>order::little</code> that represents the actual native byte order.</p>
|
||||
<p dir="ltr"><i>Returns (first form)</i>: <code>from</code> if <code>From</code>
|
||||
<p><i>Returns (first form)</i>: <code>from</code> if <code>From</code>
|
||||
and <code>To</code> have the same effective order, otherwise <code>
|
||||
reverse_value(from)</code>.</p>
|
||||
<p dir="ltr"><i>Effects (second form):</i> None if <code>From</code> and <code>
|
||||
<p><i>Effects (second form):</i> None if <code>From</code> and <code>
|
||||
To</code> have the same effective order, otherwise <code>reverse(x)</code>.</p>
|
||||
<p dir="ltr"><i>Example:</i></p>
|
||||
<p><i>Example:</i></p>
|
||||
<blockquote>
|
||||
<pre>int32_t x;
|
||||
<i>... read an external big-endian value into x</i>
|
||||
convert<order::big, order::native>(x); // more generic equivalent of big_endian(x);</pre>
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
<pre><a name="effective_order"></a>order effective_order(order x) noexcept;<blockquote><p dir="ltr"><i>Returns:</i> <code>x</code> if <code>x != order::native</code>, otherwise the <code>order</code> constant for the actual native byte order.</p><p dir="ltr"><i>Example:</i></p><blockquote><pre dir="ltr">effective_order(order::big); // returns order::big
|
||||
<pre><a name="effective_order"></a>order effective_order(order x) noexcept;
|
||||
</pre>
|
||||
<blockquote>
|
||||
<p><i>Returns:</i> <code>x</code> if <code>x != order::native</code>, otherwise the <code>order</code> constant for the actual native byte order.</p><p><i>Example:</i></p><blockquote><pre>effective_order(order::big); // returns order::big
|
||||
effective_order(order::little); // returns order::little
|
||||
effective_order(order::native); // returns order::big if the native order
|
||||
// is big-endian, otherwise order::little</pre></blockquote></blockquote><pre dir="ltr"><a name="convert_value_runtime"></a>template <class ReversibleValue>
|
||||
// is big-endian, otherwise order::little</pre></blockquote></blockquote><pre><a name="convert_value_runtime"></a>template <class ReversibleValue>
|
||||
ReversibleValue convert_value(ReversibleValue from,
|
||||
order from_order, order to_order) noexcept;
|
||||
<a name="convert_runtime"></a>template <class Reversible>
|
||||
void convert(Reversible& x,
|
||||
order from_order, order to_order) noexcept;</pre><blockquote><p dir="ltr"><i>Returns (first form)</i>: <code>from</code> if <code>effect_order(from_order) == effective_order(to_order)</code>, otherwise <code>reverse_value(from)</code>.</p>
|
||||
<p dir="ltr"><i>Effects (second form):</i> None if <code>effect_order(from_order) == effective_order(to_order)</code>, otherwise <code>reverse(x)</code>.</p>
|
||||
<p dir="ltr"><i>Example:</i></p>
|
||||
order from_order, order to_order) noexcept;</pre><blockquote><p><i>Returns (first form)</i>: <code>from</code> if <code>effect_order(from_order) == effective_order(to_order)</code>, otherwise <code>reverse_value(from)</code>.</p>
|
||||
<p><i>Effects (second form):</i> None if <code>effect_order(from_order) == effective_order(to_order)</code>, otherwise <code>reverse(x)</code>.</p>
|
||||
<p><i>Example:</i></p>
|
||||
<blockquote>
|
||||
<pre>int32_t x;
|
||||
<i>... read an external value of an endianness know only at runtime into x</i>
|
||||
convert(x, some_order, order::native); // convert to native byte order if needed</pre>
|
||||
</blockquote>
|
||||
</blockquote><h2><a name="Intrinsic">Intrinsic</a> built-in support</h2>
|
||||
</blockquote>
|
||||
|
||||
<p>Recent compilers, including GCC, Clang, and Microsoft, supply intrinsic built-in support for byte swapping. Such support is automatically detected and used since it results in smaller and much faster generated code for release builds.</p><p>Defining BOOST_ENDIAN_NO_INTRINSICS 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>The macro BOOST_ENDIAN_INTRINSIC_MSG is defined as either <code>"no byte swap intrinsics"</code> or a string describing the particular set of intrinsics being used.</p><h2><a name="Acknowledgements">Acknowledgements</a></h2><p>Tomas Puverle was instrumental in identifying and articulating the need to
|
||||
<h2> <a name="FAQ">FAQ</a></h2>
|
||||
|
||||
<p>See the <a href="index.html#FAQ">Endian home page</a> FAQ for a library-wide
|
||||
FAQ.</p>
|
||||
|
||||
<p><b>Why are the template versions of <code>reverse()</code> and <code>reverse_value()</code>
|
||||
in a detail namespace?</b></p>
|
||||
|
||||
<blockquote>
|
||||
|
||||
<p>They are unsafe for general use. Consider reversing
|
||||
the bytes of a <code>std::pai<b>r</b></code> as a whole - the bytes from <code>first</code>
|
||||
would end up in <code>second</code> and visa versa, and this is totally
|
||||
wrong!</p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<p><b>Why are both value returning and modify-in-place functions provided?</b></p>
|
||||
|
||||
<blockquote>
|
||||
|
||||
<p>Returning the result by value is the standard C and C++ idiom for functions that compute a
|
||||
value from an argument. Modify-in-place functions allow cleaner code in many real-world
|
||||
endian use cases and are more efficient for user defined types that have
|
||||
members such as string data that do not need to be reversed. Thus both forms are
|
||||
provided.</p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<h2><a name="Acknowledgements">Acknowledgements</a></h2><p>Tomas Puverle was instrumental in identifying and articulating the need to
|
||||
support endian conversion as separate from endian integer types. Phil Endecott suggested the form of the value returning signatures. Vicente Botet and other reviewers suggested supporting floating point types and user defined types. General reverse template implementation approach using std::reverse suggested by Mathias Gaunard. Portable implementation approach for 16, 32, and 64-bit integers suggested by tymofey, with avoidance of undefined behavior as suggested by Giovanni Piero Deretta, and a further refinement suggested by Pyry Jahkola. Intrinsic builtins implementation approach for 16, 32, and 64-bit integers suggested by several reviewers, and by David Stone, who provided his Boost licensed macro implementation that became the starting point for <a href="../include/boost/endian/detail/intrinsic.hpp">boost/endian/detail/intrinsic.hpp</a>.</p>
|
||||
<hr>
|
||||
<p>Last revised: <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->20 May, 2013<!--webbot bot="Timestamp" endspan i-checksum="13976" --></p>
|
||||
<p><EFBFBD> Copyright Beman Dawes, 2011</p>
|
||||
<p>Last revised:
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->28 May, 2013<!--webbot bot="Timestamp" endspan i-checksum="13992" --></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>
|
||||
|
||||
</body>
|
||||
|
||||
@@ -14,19 +14,19 @@
|
||||
<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>Both the endian types and endian conversion functions have been renamed,
|
||||
using a naming pattern that is consistent for both integer and floating point,
|
||||
and that emphasizes that aligned types are usually preferred compared to
|
||||
unaligned types.</li>
|
||||
<li>The conversion.hpp conversion functions have been much revised,
|
||||
unaligned types which are deliberately given slightly uglier names.</li>
|
||||
<li>The conversion functions have been much revised,
|
||||
refactored, and otherwise improved based on review comments.<ul>
|
||||
<li>UDT's are supported, as requested.</li>
|
||||
<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
|
||||
can continue to use them if they wish.</li>
|
||||
<li>In addition to the fixed endianness functions, functions that perform
|
||||
<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>
|
||||
@@ -34,6 +34,7 @@
|
||||
<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>
|
||||
|
||||
@@ -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>Boost Endian Library</title>
|
||||
<link rel="stylesheet" type="text/css" href="../../../doc/src/minimal.css">
|
||||
@@ -26,7 +26,7 @@
|
||||
<td><b><a href="../../../index.htm">Boost Home</a>
|
||||
<a href="index.html">Endian Home</a>
|
||||
<a href="conversion.html">Conversion Functions</a>
|
||||
<a href="types.html">Endian Types</a> Tutorial</b></td>
|
||||
<a href="types.html">Endian Types</a></b></td>
|
||||
</tr>
|
||||
</table>
|
||||
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" align="right">
|
||||
@@ -40,6 +40,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="#Performance">Performance</a><br>
|
||||
<a href="#Timings">Timings</a><br>
|
||||
<a href="#Conclusions">Conclusions</a><br>
|
||||
@@ -79,7 +80,7 @@ floating point, and user defined data.</p>
|
||||
|
||||
<blockquote>
|
||||
<pre>int16_t i = 0x0102;
|
||||
FILE * file = fopen("test.bin", "wb"); // MUST BE BINARY
|
||||
FILE * file = fopen("test.bin", "wb"); // binary file!
|
||||
fwrite(&i, sizeof(int16_t), 1, file);
|
||||
fclose(file);</pre>
|
||||
</blockquote>
|
||||
@@ -103,7 +104,7 @@ ordering and the least-significant-byte-first is traditionally called
|
||||
<a href="http://en.wikipedia.org/wiki/Jonathan_Swift" title="Jonathan Swift">
|
||||
Jonathan Swift</a>'s satirical novel <i>
|
||||
<a href="http://en.wikipedia.org/wiki/Gulliver's_Travels" title="Gulliver's Travels">
|
||||
Gulliver<EFBFBD>s Travels</a></i>, where rival kingdoms opened their soft-boiled eggs
|
||||
Gulliver’s Travels</a></i>, where rival kingdoms opened their soft-boiled eggs
|
||||
at different ends.</p>
|
||||
<p>See the Wikipedia's
|
||||
<a href="http://en.wikipedia.org/wiki/Endianness">Endianness</a> article for an
|
||||
@@ -195,6 +196,18 @@ application needs.</p>
|
||||
</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
|
||||
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
|
||||
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
|
||||
either <code>"no byte swap intrinsics"</code> or a string describing the
|
||||
particular set of intrinsics being used.</p>
|
||||
|
||||
<h2><a name="Performance">Performance</a></h2>
|
||||
|
||||
<p>Consider this problem:</p>
|
||||
@@ -425,6 +438,23 @@ stores, multiple instructions are required.</p>
|
||||
|
||||
|
||||
<h2>Overall <a name="FAQ">FAQ</a></h2>
|
||||
|
||||
<p><b>Is the implementation header only?</b></p>
|
||||
|
||||
<blockquote>
|
||||
|
||||
<p>Yes.</p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<p><b>Does the implementation use compiler intrinsic built-in byte swapping?</b></p>
|
||||
|
||||
<blockquote>
|
||||
|
||||
<p>Yes, if available. See <a href="#Intrinsic">Intrinsic built-in support</a>.</p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<p><b>Why bother with endianness?</b></p>
|
||||
<blockquote>
|
||||
<p>Binary data portability is the primary use case.</p>
|
||||
@@ -448,6 +478,15 @@ files, limit usefulness to applications where the binary I/O advantages are
|
||||
paramount.</p>
|
||||
</blockquote>
|
||||
|
||||
<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
|
||||
CPU's. The <a href="http://en.wikipedia.org/wiki/Endian">Wikipedia</a> article
|
||||
gives more pros and cons.</p>
|
||||
</blockquote>
|
||||
|
||||
<p><b>Why is only big, little, and native endianness supported?</b></p>
|
||||
<blockquote>
|
||||
<p>These are the only endian schemes that have any practical value today. PDP-11
|
||||
@@ -455,6 +494,27 @@ and the other middle endian approaches are interesting historical curiosities
|
||||
but have no relevance to C++ developers.</p>
|
||||
</blockquote>
|
||||
|
||||
<p><b>What are the limitations of floating point support?</b></p>
|
||||
|
||||
<blockquote>
|
||||
|
||||
<p>The only supported types are four byte <code>float</code> and eight byte
|
||||
<code>double</code>. Even after endianness has been accounted for, floating
|
||||
point values will not be portable between systems that use different floating
|
||||
point formats. Systems where the integer endianness differs from floating point
|
||||
endianness are not supported.</p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<p><b>What are the limitations of integer support?</b></p>
|
||||
|
||||
<blockquote>
|
||||
|
||||
<p>Only 16-bit, 32-bit, and 64-bit integers are supported. Tests have only been
|
||||
performed on machines that use two's complement arithmetic.</p>
|
||||
|
||||
</blockquote>
|
||||
|
||||
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
|
||||
<p>Comments and suggestions were
|
||||
received from
|
||||
@@ -474,7 +534,7 @@ and Vitaly Budovski,.</p>
|
||||
<hr>
|
||||
<p>Last revised:
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->28 May, 2013<!--webbot bot="Timestamp" endspan i-checksum="13992" --></p>
|
||||
<p><EFBFBD> Copyright Beman Dawes, 2011, 2013</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>
|
||||
|
||||
|
||||
@@ -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>Boost Endian Integers</title>
|
||||
<link rel="stylesheet" type="text/css" href="../../../doc/src/minimal.css">
|
||||
</head>
|
||||
@@ -28,7 +28,7 @@
|
||||
<td><b><a href="../../../index.htm">Boost Home</a>
|
||||
<a href="index.html">Endian Home</a>
|
||||
<a href="conversion.html">Conversion Functions</a>
|
||||
<a href="types.html">Endian Types</a> Tutorial</b></td>
|
||||
<a href="types.html">Endian Types</a></b></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
@@ -510,29 +510,14 @@ in <code>*this</code>.</p>
|
||||
<p>Other operators on endian objects are forwarded to the equivalent
|
||||
operator on <code>value_type</code>.</p>
|
||||
<h2><a name="FAQ">FAQ</a></h2>
|
||||
<p><b>Why bother with endian types?</b> External data portability and both speed
|
||||
and space efficiency. Availability
|
||||
of additional binary integer sizes and alignments is important in some
|
||||
applications.</p>
|
||||
|
||||
<p>See the <a href="index.html#FAQ">Endian home page</a> FAQ for a library-wide
|
||||
FAQ.</p>
|
||||
|
||||
<p><b>Why not just use Boost.Serialization?</b> Serialization involves a
|
||||
conversion for every object involved in I/O. Endian integers require no
|
||||
conversion or copying. They are already in the desired format for binary I/O.
|
||||
Thus they can be read or written in bulk.</p>
|
||||
<p><b>Why bother with binary I/O? Why not just use C++ Standard Library stream
|
||||
inserters and extractors?</b> Using binary rather than character representations
|
||||
can be more space efficient, with a side benefit of faster I/O. CPU time is
|
||||
minimized because conversions to and from string are eliminated.
|
||||
Furthermore, binary integers are fixed size, and so fixed-size disk records
|
||||
are possible, easing sorting and allowing direct access. Disadvantages, such as the inability to use
|
||||
text utilities on the resulting files, limit usefulness to applications where
|
||||
the
|
||||
binary I/O advantages are paramount.</p>
|
||||
<p><b>Do these types have any uses outside of I/O?</b> Native endianness can be used for fine grained control over size and
|
||||
alignment, so may be used to save memory in applications not related to I/O.</p>
|
||||
<p><b>Is there is a performance hit when doing arithmetic using these types?</b> Yes, for sure,
|
||||
compared to arithmetic operations on native integer types. However, these types
|
||||
are usually be faster, and sometimes much faster, for I/O compared to stream
|
||||
inserters and extractors, or to serialization.</p>
|
||||
<p><b>Are endian types POD's?</b> Yes for C++11. No for C++03, although several
|
||||
<a href="#Compilation">macros</a> are available to force PODness in all cases.</p>
|
||||
<p><b>What are the implications endian integer types not being POD's with C++03
|
||||
@@ -541,24 +526,15 @@ can't be used in unions. Also, compilers aren't required to align or lay
|
||||
out storage in portable ways, although this potential problem hasn't prevented
|
||||
use of Boost.Endian with
|
||||
real compilers.</p>
|
||||
<p><b>Which is better, big-endian or little-endian?</b> 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
|
||||
CPU's. The <a href="http://en.wikipedia.org/wiki/Endian">Wikipedia</a> article
|
||||
gives more pros and cons.</p>
|
||||
<p><b>What good is <i>native </i>endianness?</b> It provides alignment and
|
||||
size guarantees not available from the built-in types. It eases generic
|
||||
programming.</p>
|
||||
<p><b>Why bother with the aligned endian types?</b> Aligned integer operations
|
||||
may be faster (20 times, in one measurement) if the endianness and alignment of
|
||||
the type matches the endianness and alignment requirements of the machine. On
|
||||
common CPU architectures, that optimization is only available for aligned types.
|
||||
That allows I/O of maximally efficient types on an application's primary
|
||||
platform, yet produces data files are portable to all platforms. The code,
|
||||
may be faster (as much as 10 to 20 times faster) if the endianness and alignment of
|
||||
the type matches the endianness and alignment requirements of the machine. The code,
|
||||
however, is
|
||||
likely to be somewhat less portable than with the unaligned types.</p>
|
||||
<p><b>The endian types are really just byte-holders. Why provide the arithmetic
|
||||
operations at all?</b> Providing a full set of operations reduces program
|
||||
<p><b>Why provide the arithmetic operations?</b> Providing a full set of operations reduces program
|
||||
clutter and makes code both easier to write and to read. Consider
|
||||
incrementing a variable in a record. It is very convenient to write:</p>
|
||||
<pre wrap> ++record.foo;</pre>
|
||||
@@ -629,11 +605,12 @@ Borgerding. Four original class templates combined into a single <code>endian</c
|
||||
class template by Beman Dawes, who put the library together, provided
|
||||
documentation, added the typedefs, and also added the <code>unrolled_byte_loops</code>
|
||||
sign partial specialization to correctly extend the sign when cover integer size
|
||||
differs from endian representation size.</p>
|
||||
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 -->26 May, 2013<!--webbot bot="Timestamp" endspan i-checksum="13988" --></p>
|
||||
<p>© Copyright Beman Dawes, 2006-2009</p>
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->28 May, 2013<!--webbot bot="Timestamp" endspan i-checksum="13992" --></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>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user