Add missing one byte aligned types, plus other minor fixes.

This commit is contained in:
Beman
2015-02-21 07:38:03 -05:00
parent c62aa232e1
commit 963f00ec8f
2 changed files with 36 additions and 26 deletions

View File

@ -86,19 +86,25 @@ endian</b></i> and <i><b>little endian</b></i>.</p>
<p>Boost endian integers provide the same full set of C++ assignment, <p>Boost endian integers provide the same full set of C++ assignment,
arithmetic, and relational operators&nbsp;as C++ standard integral types, with arithmetic, and relational operators&nbsp;as C++ standard integral types, with
the standard semantics.</p> the standard semantics.</p>
<p>Unary arithmetic operators are <code>+</code>, <code>-</code>, <code>~</code>, <p>Unary arithmetic operators are <b> <code><font face="Courier New">+</font></code></b>,
<code>!</code>, prefix and postfix <code>--</code> and <code>++</code>. Binary <b> <code>-</code></b>, <b> <code>~</code></b>, <b>
arithmetic operators are <code>+</code>, <code>+=</code>, <code>-</code>, <code> <code>!</code></b>, plus both prefix and postfix <b> <code>--</code></b> and <b> <code>++</code></b>. Binary
-=</code>, <code>*</code>, <code>*=</code>, <code>/</code>, <code>/=</code>, arithmetic operators are <b> <code>+</code></b>, <b> <code>+=</code></b>, <b> <code>-</code></b>,
<code>%/ %=</code>, <code>&amp;</code>, <code>&amp;=</code>, <code>|</code>, <code>|=</code>, <b> <code>
<code>^</code>, <code>^=</code>, <code>&lt;&lt;</code>, <code>&lt;&lt;=</code>, <code>&gt;&gt;</code>, -=</code></b>, <b> <code>*</code></b>, <b> <code>*=</code></b>, <b> <code>/</code></b>,
<code>&gt;&gt;=</code>. Binary relational operators are <code>==</code>, <code>!=</code>, <b> <code>/=</code></b>, <b> <code>&amp;</code></b>, <b> <code>&amp;=</code></b>,
<code>&lt;</code>, <code>&lt;=</code>, <code>&gt;</code>, <code>&gt;=</code>.</p> <b> <code>|</code></b>, <b> <code>|=</code></b>, <b>
<p>Automatic implicit conversion to the underlying value type is provided. A <code>^</code></b>, <b> <code>^=</code></b>, <b> <code>&lt;&lt;</code></b>, <b> <code>&lt;&lt;=</code></b>, <code>
conversion constructor from the underlying value type is provided. </p> <b>&gt;&gt;</b></code>, and <b>
<code>&gt;&gt;=</code></b>. Binary relational operators are <b> <code>==</code></b>,
<b> <code>!=</code></b>, <b>
<code>&lt;</code></b>, <b> <code>&lt;=</code></b>, <b> <code>&gt;</code></b>,
and <b> <code>&gt;=</code></b>.</p>
<p>Implicit conversion to the underlying value type is provided. An implicit
constructor converting from the underlying value type is provided. </p>
<h2><a name="Example">Example</a></h2> <h2><a name="Example">Example</a></h2>
<p>The <a href="../example/endian_example.cpp">endian_example.cpp</a> program writes a <p>The <a href="../example/endian_example.cpp">endian_example.cpp</a> program writes a
binary file containing four byte big-endian and little-endian integers:</p> binary file containing four-byte, big-endian and little-endian integers:</p>
<blockquote> <blockquote>
<pre>#include &lt;iostream&gt; <pre>#include &lt;iostream&gt;
#include &lt;cstdio&gt; #include &lt;cstdio&gt;
@ -128,10 +134,10 @@ namespace
int main(int, char* []) int main(int, char* [])
{ {
BOOST_STATIC_ASSERT(sizeof(header) == 16U); // reality check
header h; header h;
BOOST_STATIC_ASSERT(sizeof(h) == 16U); // reality check
h.file_code = 0x01020304; h.file_code = 0x01020304;
h.file_length = sizeof(header); h.file_length = sizeof(header);
h.version = 1; h.version = 1;
@ -181,14 +187,14 @@ is some other value, compilation will result in an <code>#error</code>. This
restriction is in place because the design, implementation, testing, and restriction is in place because the design, implementation, testing, and
documentation has only considered issues related to 8-bit bytes, and there have documentation has only considered issues related to 8-bit bytes, and there have
been no real-world use cases presented for other sizes.</p> been no real-world use cases presented for other sizes.</p>
<p>In C++03, <code>endian</code> does not meet the requirements for POD types <p>In C++03, <code>endian_arithmetic</code> does not meet the requirements for POD types
because it has constructors, private data members, and a base class. This means because it has constructors, private data members, and a base class. This means
that common use cases are relying on unspecified behavior in that the C++ that common use cases are relying on unspecified behavior in that the C++
Standard does not guarantee memory layout for non-POD types. This has not been a Standard does not guarantee memory layout for non-POD types. This has not been a
problem in practice since all known C++ compilers do layout memory as if <code> problem in practice since all known C++ compilers lay out memory as if <code>
endian</code> were a POD type. In C++11, it is possible to specify the endian</code> were a POD type. In C++11, it is possible to specify the
default constructor as trivial, and private data members and base classes will default constructor as trivial, and private data members and base classes no longer disqualify a type from being a POD
no longer disqualify a type from being a POD. Thus under C++11, <code>endian</code> type. Thus under C++11, <code>endian_arithmetic</code>
will no longer be relying on unspecified behavior.</p> will no longer be relying on unspecified behavior.</p>
<h2><a name="Feature-set">Feature set</a></h2> <h2><a name="Feature-set">Feature set</a></h2>
<ul> <ul>
@ -196,7 +202,7 @@ will no longer be relying on unspecified behavior.</p>
<li>Signed | unsigned</li> <li>Signed | unsigned</li>
<li>Unaligned | aligned</li> <li>Unaligned | aligned</li>
<li>Integer | floating point</li> <li>Integer | floating point</li>
<li>1-8 byte (unaligned) | 2, 4, 8 byte (aligned)</li> <li>1-8 byte (unaligned) | 1, 2, 4, 8 byte (aligned)</li>
<li>Choice of value type</li> <li>Choice of value type</li>
</ul> </ul>
<h2>Enums and t<a name="Types">ypedefs</a></h2> <h2>Enums and t<a name="Types">ypedefs</a></h2>
@ -347,14 +353,14 @@ requirements vary between hardware architectures and because alignment may be
affected by compiler switches or pragmas. For example, alignment of an 64-bit affected by compiler switches or pragmas. For example, alignment of an 64-bit
integer may be to a 32-bit boundary on a 32-bit machine. Furthermore, aligned types integer may be to a 32-bit boundary on a 32-bit machine. Furthermore, aligned types
are only available on architectures with 8, 16, 32, and 64-bit integer types.</p> are only available on architectures with 8, 16, 32, and 64-bit integer types.</p>
<p><i><b>Recommendation:</b></i> Prefer unaligned endian types.</p> <p><i><b>Recommendation:</b></i> Prefer unaligned arithmetic types.</p>
<p><i><b>Recommendation:</b></i> Protect yourself against alignment ills. For <p><i><b>Recommendation:</b></i> Protect yourself against alignment ills. For
example:</p> example:</p>
<blockquote> <blockquote>
<pre>static_assert(sizeof(containing_struct) == 12, &quot;sizeof(containing_struct) is wrong&quot;); </pre> <pre>static_assert(sizeof(containing_struct) == 12, &quot;sizeof(containing_struct) is wrong&quot;); </pre>
</blockquote> </blockquote>
<p><b><i>Note:</i></b> One-byte big and little buffer types <p><b><i>Note:</i></b> <b><i>Note:</i></b> One-byte arithmetic types
never actually reverse endianness. They are provided to enable generic code, and have identical layout on all platforms, so they never actually reverse endianness. They are provided to enable generic code, and
to improve code readability and searchability.</p> to improve code readability and searchability.</p>
<h2><a name="Class_template_endian">Class template <code>endian</code></a><code>_arithmetic</code></h2> <h2><a name="Class_template_endian">Class template <code>endian</code></a><code>_arithmetic</code></h2>
<p>An endian is an integer byte-holder with user-specified <a href="#endianness"> <p>An endian is an integer byte-holder with user-specified <a href="#endianness">
@ -540,11 +546,11 @@ platform.</p>
<pre><code><a name="endian">endian</a>() = default; // C++03: endian(){}</code></pre> <pre><code><a name="endian">endian</a>() = default; // C++03: endian(){}</code></pre>
</div> </div>
<blockquote> <blockquote>
<p><i>Effects:</i> Constructs an object of type <code>endian&lt;E, T, n_bits, A&gt;</code>.</p> <p><i>Effects:</i> Constructs an uninitialized object of type <code>endian_arithmetic&lt;E, T, n_bits, A&gt;</code>.</p>
</blockquote> </blockquote>
<pre><code><a name="explicit-endian">endian</a>(T v);</code></pre> <pre><code><a name="explicit-endian">endian</a>(T v);</code></pre>
<blockquote> <blockquote>
<p><i>Effects:</i> Constructs an object of type <code>endian&lt;E, T, n_bits, A&gt;</code>.</p> <p><i>Effects:</i> Constructs an object of type <code>endian_arithmetic&lt;E, T, n_bits, A&gt;</code>.</p>
<p><i>Postcondition:</i> <code>x == v,</code> where <code>x</code> is the <p><i>Postcondition:</i> <code>x == v,</code> where <code>x</code> is the
constructed object.</p> constructed object.</p>
</blockquote> </blockquote>

View File

@ -184,7 +184,7 @@ will no longer be relying on unspecified behavior.</p>
<li>Signed | unsigned</li> <li>Signed | unsigned</li>
<li>Unaligned | aligned</li> <li>Unaligned | aligned</li>
<li>Integer | floating point</li> <li>Integer | floating point</li>
<li>1-8 byte (unaligned) | 2, 4, 8 byte (aligned)</li> <li>1-8 byte (unaligned) | 1, 2, 4, 8 byte (aligned)</li>
<li>Choice of value type</li> <li>Choice of value type</li>
</ul> </ul>
<h2>Enums and t<a name="Types">ypedefs</a></h2> <h2>Enums and t<a name="Types">ypedefs</a></h2>
@ -336,7 +336,7 @@ affected by compiler switches or pragmas. For example, alignment of an 64-bit
integer may be to a 32-bit boundary on a 32-bit machine and to a 64-bit boundary integer may be to a 32-bit boundary on a 32-bit machine and to a 64-bit boundary
on a 64-bit machine. Furthermore, aligned types on a 64-bit machine. Furthermore, aligned types
are only available on architectures with 8, 16, 32, and 64-bit integer types. </p> are only available on architectures with 8, 16, 32, and 64-bit integer types. </p>
<p><i><b>Recommendation:</b></i> Prefer unaligned endian types.</p> <p><i><b>Recommendation:</b></i> Prefer unaligned buffer types.</p>
<p><i><b>Recommendation:</b></i> Protect yourself against alignment ills. For <p><i><b>Recommendation:</b></i> Protect yourself against alignment ills. For
example:</p> example:</p>
<blockquote> <blockquote>
@ -415,21 +415,25 @@ usual operations on integers are supplied.</p>
typedef endian_buffer&lt;order::little, double, 64, align::no&gt; little_float64_buf_ut; typedef endian_buffer&lt;order::little, double, 64, align::no&gt; little_float64_buf_ut;
// aligned big endian signed integer buffers // aligned big endian signed integer buffers
typedef endian_buffer&lt;order::big, int8_t, 8, align::yes&gt; big_int8_buf_t;
typedef endian_buffer&lt;order::big, int16_t, 16, align::yes&gt; big_int16_buf_t; typedef endian_buffer&lt;order::big, int16_t, 16, align::yes&gt; big_int16_buf_t;
typedef endian_buffer&lt;order::big, int32_t, 32, align::yes&gt; big_int32_buf_t; typedef endian_buffer&lt;order::big, int32_t, 32, align::yes&gt; big_int32_buf_t;
typedef endian_buffer&lt;order::big, int64_t, 64, align::yes&gt; big_int64_buf_t; typedef endian_buffer&lt;order::big, int64_t, 64, align::yes&gt; big_int64_buf_t;
// aligned big endian unsigned integer buffers // aligned big endian unsigned integer buffers
typedef endian_buffer&lt;order::big, uint8_t, 8, align::yes&gt; big_uint8_buf_t;
typedef endian_buffer&lt;order::big, uint16_t, 16, align::yes&gt; big_uint16_buf_t; typedef endian_buffer&lt;order::big, uint16_t, 16, align::yes&gt; big_uint16_buf_t;
typedef endian_buffer&lt;order::big, uint32_t, 32, align::yes&gt; big_uint32_buf_t; typedef endian_buffer&lt;order::big, uint32_t, 32, align::yes&gt; big_uint32_buf_t;
typedef endian_buffer&lt;order::big, uint64_t, 64, align::yes&gt; big_uint64_buf_t; typedef endian_buffer&lt;order::big, uint64_t, 64, align::yes&gt; big_uint64_buf_t;
// aligned little endian signed integer buffers // aligned little endian signed integer buffers
typedef endian_buffer&lt;order::little, int8_t, 8, align::yes&gt; little_int8_buf_t;
typedef endian_buffer&lt;order::little, int16_t, 16, align::yes&gt; little_int16_buf_t; typedef endian_buffer&lt;order::little, int16_t, 16, align::yes&gt; little_int16_buf_t;
typedef endian_buffer&lt;order::little, int32_t, 32, align::yes&gt; little_int32_buf_t; typedef endian_buffer&lt;order::little, int32_t, 32, align::yes&gt; little_int32_buf_t;
typedef endian_buffer&lt;order::little, int64_t, 64, align::yes&gt; little_int64_buf_t; typedef endian_buffer&lt;order::little, int64_t, 64, align::yes&gt; little_int64_buf_t;
// aligned little endian unsigned integer buffers // aligned little endian unsigned integer buffers
typedef endian_buffer&lt;order::little, uint8_t, 8, align::yes&gt; little_uint8_buf_t;
typedef endian_buffer&lt;order::little, uint16_t, 16, align::yes&gt; little_uint16_buf_t; typedef endian_buffer&lt;order::little, uint16_t, 16, align::yes&gt; little_uint16_buf_t;
typedef endian_buffer&lt;order::little, uint32_t, 32, align::yes&gt; little_uint32_buf_t; typedef endian_buffer&lt;order::little, uint32_t, 32, align::yes&gt; little_uint32_buf_t;
typedef endian_buffer&lt;order::little, uint64_t, 64, align::yes&gt; little_uint64_buf_t; typedef endian_buffer&lt;order::little, uint64_t, 64, align::yes&gt; little_uint64_buf_t;
@ -546,7 +550,7 @@ boost::endian::endian_reverse</code>.</p>
</blockquote> </blockquote>
<pre>value_type <a name="value">value</a>()<code> const noexcept;</code></pre> <pre>value_type <a name="value">value</a>()<code> const noexcept;</code></pre>
<blockquote> <blockquote>
<p><i>Returns:</i> <code>endian_value</code>, converted to <code>value_type</code> <p><i>Returns:</i> <code>endian_value</code>, converted to <code>value_type</code>,
if required, and having the endianness of the native platform.</p> if required, and having the endianness of the native platform.</p>
<p><i>Remarks:</i> If <code>Align</code> is <code>align::yes</code> then <p><i>Remarks:</i> If <code>Align</code> is <code>align::yes</code> then
endianness conversion, if required, is performed by <code> endianness conversion, if required, is performed by <code>