forked from boostorg/endian
Initial done_list.html. Improve general FAQ. Update example. Add BOOST_NOEXCEPT to types.hpp and cover_operators.hpp.
This commit is contained in:
1 parent
c7beb10785
commit
41f0c15844
7 files changed
+242
-171
No files matched your search
+104
-94
@@ -109,64 +109,69 @@ using namespace boost::endian;
|
||||
|
||||
namespace
|
||||
{
|
||||
// This is an extract from a very widely used GIS file format. I have no idea
|
||||
// why a designer would mix big and little endians in the same file - but
|
||||
// this is a real-world format and users wishing to write low level code
|
||||
// manipulating these files have to deal with the mixed endianness.
|
||||
// This is an extract from a very widely used GIS file format. Who knows
|
||||
// why a designer would mix big and little endians in the same file - but
|
||||
// this is a real-world format and users wishing to write low level code
|
||||
// manipulating these files have to deal with the mixed endianness.
|
||||
|
||||
struct header
|
||||
{
|
||||
big32_t file_code;
|
||||
big32_t file_length;
|
||||
little32_t version;
|
||||
little32_t shape_type;
|
||||
big_int32_t file_code;
|
||||
big_int32_t file_length;
|
||||
little_int32_t version;
|
||||
little_int32_t shape_type;
|
||||
};
|
||||
|
||||
const char * filename = "test.dat";
|
||||
const char* filename = "test.dat";
|
||||
}
|
||||
|
||||
int main()
|
||||
int main(int, char* [])
|
||||
{
|
||||
BOOST_STATIC_ASSERT( sizeof( header ) == 16U ); // check requirement
|
||||
|
||||
BOOST_STATIC_ASSERT(sizeof(header) == 16U); // reality check
|
||||
|
||||
header h;
|
||||
|
||||
h.file_code = 0x01020304;
|
||||
h.file_length = sizeof( header );
|
||||
h.version = -1;
|
||||
h.file_length = sizeof(header);
|
||||
h.version = 1;
|
||||
h.shape_type = 0x01020304;
|
||||
|
||||
// Low-level I/O such as POSIX read/write or <cstdio> fread/fwrite is sometimes
|
||||
// used for binary file operations when ultimate efficiency is important.
|
||||
// Such I/O is often performed in some C++ wrapper class, but to drive home the
|
||||
// point that endian integers are often used in fairly low-level code that
|
||||
// does bulk I/O operations, <cstdio> fopen/fwrite is used for I/O in this example.
|
||||
// Low-level I/O such as POSIX read/write or <cstdio> fread/fwrite is sometimes
|
||||
// used for binary file operations when ultimate efficiency is important.
|
||||
// Such I/O is often performed in some C++ wrapper class, but to drive home the
|
||||
// point that endian integers are often used in fairly low-level code that
|
||||
// does bulk I/O operations, <cstdio> fopen/fwrite is used for I/O in this example.
|
||||
|
||||
std::FILE * fi;
|
||||
|
||||
if ( !(fi = std::fopen( filename, "wb" )) ) // MUST BE BINARY
|
||||
std::FILE* fi = std::fopen(filename, "wb"); // MUST BE BINARY
|
||||
|
||||
if (!fi)
|
||||
{
|
||||
std::cout << "could not open " << filename << '\n';
|
||||
return 1;
|
||||
}
|
||||
|
||||
if ( std::fwrite( &h, sizeof( header ), 1, fi ) != 1 )
|
||||
if (std::fwrite(&h, sizeof(header), 1, fi)!= 1)
|
||||
{
|
||||
std::cout << "write failure for " << filename << '\n';
|
||||
return 1;
|
||||
}
|
||||
|
||||
std::fclose( fi );
|
||||
std::fclose(fi);
|
||||
|
||||
std::cout << "created file " << filename << '\n';
|
||||
|
||||
return 0;
|
||||
}</pre>
|
||||
}
|
||||
</pre>
|
||||
</blockquote>
|
||||
<p>After compiling and executing <a href="endian_example.cpp">endian_example.cpp</a>,
|
||||
a hex dump of <code>test.dat</code> shows:</p>
|
||||
<blockquote>
|
||||
<pre>0102 0304 0000 0010 ffff ffff 0403 0201</pre>
|
||||
<pre>01020304 00000010 01000000 04030201</pre>
|
||||
</blockquote>
|
||||
<p>Notice that the first two 32-bit integers are big endian while the second two
|
||||
are little endian, even though the machine this was compiled and run on was
|
||||
little endian.</p>
|
||||
<h2><a name="Limitations">Limitations</a></h2>
|
||||
<p>Requires <code><climits></code> <code>CHAR_BIT == 8</code>. If <code>CHAR_BIT</code>
|
||||
is some other value, compilation will result in an <code>#error</code>. This
|
||||
@@ -178,7 +183,7 @@ 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++
|
||||
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>
|
||||
endian</code> were a POD type. In C++11, it will be 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
|
||||
no longer disqualify a type from being a POD. Thus under C++11, <code>endian</code>
|
||||
will no longer be relying on unspecified behavior.</p>
|
||||
@@ -190,15 +195,19 @@ will no longer be relying on unspecified behavior.</p>
|
||||
<li>1-8 byte (unaligned) | 2, 4, 8 byte (aligned)</li>
|
||||
<li>Choice of integer value type</li>
|
||||
</ul>
|
||||
<h2><a name="Types">Typedefs</a></h2>
|
||||
<h2>Enums and t<a name="Types">ypedefs</a></h2>
|
||||
<p>Two scoped enums are provided:</p>
|
||||
<blockquote>
|
||||
<pre>enum class order {big, little, native};
|
||||
enum class align {no, yes}; </pre>
|
||||
</blockquote>
|
||||
<p>One class template is provided:</p>
|
||||
<blockquote>
|
||||
<pre>template <<a href="#endianness">endianness</a>::enum_t E, typename T, std::size_t n_bytes,
|
||||
<a href="#alignment">alignment</a>::enum_t A = alignment::unaligned>
|
||||
class endian;
|
||||
<pre>template <order Order, typename T, std::size_t n_bits, align A = align::no>
|
||||
class endian;
|
||||
</pre>
|
||||
</blockquote>
|
||||
<p>Sixty typedefs, such as <code>big32_t</code>, provide convenient naming
|
||||
<p>Typedefs, such as <code>big_int32_t</code>, provide convenient naming
|
||||
conventions for common use cases:</p>
|
||||
<blockquote>
|
||||
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="49%">
|
||||
@@ -210,76 +219,76 @@ conventions for common use cases:</p>
|
||||
<td width="49%" align="center"><b><i>Alignment</i></b></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>big</code><b><i>n</i></b><code>_t</code></td>
|
||||
<td width="10%"><code>big</code></td>
|
||||
<td width="10%">signed</td>
|
||||
<td width="15%">8,16,24,32,40,48,56,64</td>
|
||||
<td width="49%"><code>unaligned</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>ubig</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="10%"><code>big</code></td>
|
||||
<td width="10%">unsigned</td>
|
||||
<td width="15%">8,16,24,32,40,48,56,64</td>
|
||||
<td width="49%"><code>unaligned</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>little</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="10%"><code>little</code></td>
|
||||
<td width="10%">signed</td>
|
||||
<td width="15%">8,16,24,32,40,48,56,64</td>
|
||||
<td width="49%"><code>unaligned</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>ulittle</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="10%"><code>little</code></td>
|
||||
<td width="10%">unsigned</td>
|
||||
<td width="15%">8,16,24,32,40,48,56,64</td>
|
||||
<td width="49%"><code>unaligned</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>native</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="10%"><code>native</code></td>
|
||||
<td width="10%">signed</td>
|
||||
<td width="15%">8,16,24,32,40,48,56,64</td>
|
||||
<td width="49%"><code>unaligned</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>unative</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="10%"><code>native</code></td>
|
||||
<td width="10%">unsigned</td>
|
||||
<td width="15%">8,16,24,32,40,48,56,64</td>
|
||||
<td width="49%"><code>unaligned</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>aligned_big</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="10%"><code>big</code></td>
|
||||
<td width="10%">signed</td>
|
||||
<td width="18%"><code>big_int</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="10%" align="center"><code>big</code></td>
|
||||
<td width="10%" align="center">signed</td>
|
||||
<td width="15%">16,32,64</td>
|
||||
<td width="49%"><code>aligned</code></td>
|
||||
<td width="49%" align="center"><code>yes</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>aligned_ubig</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="10%"><code>big</code></td>
|
||||
<td width="10%">unsigned</td>
|
||||
<td width="18%"><code>big_uint</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="10%" align="center"><code>big</code></td>
|
||||
<td width="10%" align="center">unsigned</td>
|
||||
<td width="15%">16,32,64</td>
|
||||
<td width="49%"><code>aligned</code></td>
|
||||
<td width="49%" align="center"><code>yes</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>aligned_little</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="10%"><code>little</code></td>
|
||||
<td width="10%">signed</td>
|
||||
<td width="18%"><code>little_int</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="10%" align="center"><code>little</code></td>
|
||||
<td width="10%" align="center">signed</td>
|
||||
<td width="15%">16,32,64</td>
|
||||
<td width="49%"><code>aligned</code></td>
|
||||
<td width="49%" align="center"><code>yes</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>aligned_ulittle</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="10%"><code>little</code></td>
|
||||
<td width="10%">unsigned</td>
|
||||
<td width="18%"><code>little_uint</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="10%" align="center"><code>little</code></td>
|
||||
<td width="10%" align="center">unsigned</td>
|
||||
<td width="15%">16,32,64</td>
|
||||
<td width="49%"><code>aligned</code></td>
|
||||
<td width="49%" align="center"><code>yes</code></td>
|
||||
</tr>
|
||||
</table>
|
||||
<tr>
|
||||
<td width="18%"><code>big_</code><b><i>n</i></b><code>_t</code></td>
|
||||
<td width="10%" align="center"><code>big</code></td>
|
||||
<td width="10%" align="center">signed</td>
|
||||
<td width="15%">8,16,24,32,40,48,56,64</td>
|
||||
<td width="49%" align="center"><code>no</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>big_u</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="10%" align="center"><code>big</code></td>
|
||||
<td width="10%" align="center">unsigned</td>
|
||||
<td width="15%">8,16,24,32,40,48,56,64</td>
|
||||
<td width="49%" align="center"><code>no</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>little_</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="10%" align="center"><code>little</code></td>
|
||||
<td width="10%" align="center">signed</td>
|
||||
<td width="15%">8,16,24,32,40,48,56,64</td>
|
||||
<td width="49%" align="center"><code>no</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>little_u</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="10%" align="center"><code>little</code></td>
|
||||
<td width="10%" align="center">unsigned</td>
|
||||
<td width="15%">8,16,24,32,40,48,56,64</td>
|
||||
<td width="49%" align="center"><code>no</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>native_</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="10%" align="center"><code>native</code></td>
|
||||
<td width="10%" align="center">signed</td>
|
||||
<td width="15%">8,16,24,32,40,48,56,64</td>
|
||||
<td width="49%" align="center"><code>no</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="18%"><code>native_u</code><i><b>n</b></i><code>_t</code></td>
|
||||
<td width="10%" align="center"><code>native</code></td>
|
||||
<td width="10%" align="center">unsigned</td>
|
||||
<td width="15%">8,16,24,32,40,48,56,64</td>
|
||||
<td width="49%" align="center"><code>no</code></td>
|
||||
</tr>
|
||||
</table>
|
||||
</blockquote>
|
||||
<p>The unaligned types do not cause compilers to insert padding bytes in classes
|
||||
and structs. This is an important characteristic that can be exploited to minimize wasted space in
|
||||
@@ -289,8 +298,9 @@ Code that uses a</span>ligned types is inherently non-portable because alignment
|
||||
requirements vary between hardware architectures and because alignment may be
|
||||
affected by compiler switches or pragmas. Furthermore, aligned types
|
||||
are only available on architectures with 16, 32, and 64-bit integer types.</p>
|
||||
<p><b><i>Note:</i></b> One-byte big-endian, little-endian, and native-endian types provide identical
|
||||
functionality. All three names are provided to improve code readability and searchability.</p>
|
||||
<p><b><i>Note:</i></b> One-byte big-endian, little-endian, and native-endian types
|
||||
have identical
|
||||
functionality. They are provided to improve code readability and searchability.</p>
|
||||
<h3><a name="Comment-on-naming">Comment on naming</a></h3>
|
||||
<p>When first exposed to endian types, programmers often fit them into a mental model
|
||||
based on the <code><cstdint></code> types. Using that model, it is natural to
|
||||
@@ -593,7 +603,7 @@ sign partial specialization to correctly extend the sign when cover integer size
|
||||
differs from endian representation size.</p>
|
||||
<hr>
|
||||
<p>Last revised:
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->21 May, 2013<!--webbot bot="Timestamp" endspan i-checksum="13978" --></p>
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->22 May, 2013<!--webbot bot="Timestamp" endspan i-checksum="13980" --></p>
|
||||
<p>© Copyright Beman Dawes, 2006-2009</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