]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | <html> |
2 | ||
3 | <head> | |
4 | <meta http-equiv="Content-Language" content="en-us"> | |
5 | <meta name="GENERATOR" content="Microsoft FrontPage 5.0"> | |
6 | <meta name="ProgId" content="FrontPage.Editor.Document"> | |
7 | <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> | |
8 | <title>Endian Buffer Types</title> | |
9 | <link href="styles.css" rel="stylesheet"> | |
10 | </style> | |
11 | </head> | |
12 | ||
13 | <body> | |
14 | ||
15 | ||
16 | <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%"> | |
17 | <tr> | |
18 | <td> | |
19 | <a href="../../../index.html"> | |
20 | <img src="../../../boost.png" alt="Boost logo" align="middle" border="0" width="277" height="86"></a></td> | |
21 | <td align="middle"> | |
22 | <b> | |
23 | <font size="6">Endian Buffer Types</font> </b> | |
24 | </td> | |
25 | </tr> | |
26 | </table> | |
27 | ||
28 | <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="100%"> | |
29 | <tr> | |
30 | <td><b> | |
31 | <a href="index.html">Endian Home</a> | |
32 | <a href="conversion.html">Conversion Functions</a> | |
33 | <a href="arithmetic.html">Arithmetic Types</a> | |
34 | <a href="buffers.html">Buffer Types</a> | |
35 | <a href="choosing_approach.html">Choosing Approach</a></b></td> | |
36 | </tr> | |
37 | </table> | |
38 | ||
39 | <p></p> | |
40 | ||
41 | <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" align="right"> | |
42 | <tr> | |
43 | <td width="100%" bgcolor="#D7EEFF" align="center"> | |
44 | <i><b>Contents</b></i></td> | |
45 | </tr> | |
46 | <tr> | |
47 | <td width="100%" bgcolor="#E8F5FF"> | |
48 | <a href="#Introduction">Introduction</a><br> | |
49 | <a href="#Example">Example</a><br> | |
50 | <a href="#Limitations">Limitations</a><br> | |
51 | <a href="#Feature-set">Feature set</a><br> | |
52 | <a href="#Types">Enums and typedefs</a><br> | |
53 | <a href="#Class_template_endian">Class template <code>endian_buffer</code></a><br> | |
54 | | |
55 | <a href="#Synopsis">Synopsis</a><br> | |
56 | <a href="#Members">Members</a><br> | |
57 | <a href="#Non-member-functions">Non-Members</a><br> | |
58 | <a href="#FAQ">FAQ</a><br> | |
59 | <a href="#Design">Design</a><br> | |
60 | <a href="#C++0x">C++11</a><br> | |
61 | <a href="#Compilation">Compilation</a></td> | |
62 | </tr> | |
63 | </table> | |
64 | <h2><a name="Introduction">Introduction</a></h2> | |
65 | <p>The internal byte order of arithmetic types is traditionally called <b><i>endianness</i></b>. See | |
66 | the | |
67 | <a href="http://en.wikipedia.org/wiki/Endian" name="endianness">Wikipedia</a> for | |
68 | a full | |
69 | exploration of <b><i>endianness</i></b>, including definitions of <i><b>big | |
70 | endian</b></i> and <i><b>little endian</b></i>.</p> | |
71 | <p>Header <b><code>boost/endian/buffers.hpp</code></b> | |
72 | provides <code>endian_buffer</code>, a portable endian integer binary buffer | |
73 | class template with control over | |
74 | byte order, value type, size, and alignment independent of the platform's native | |
75 | endianness. Typedefs provide easy-to-use names | |
76 | for common configurations.</p> | |
77 | <p>Use cases primarily involve data portability, either via files or network | |
78 | connections, but these byte-holders may | |
79 | also be used to reduce memory use, file size, or network activity since they | |
80 | ||
81 | provide binary numeric sizes not otherwise available.</p> | |
82 | <p dir="ltr">Class <code>endian_buffer</code> is aimed at users who wish | |
83 | explicit control over when endianness conversions occur. It also serves as the | |
84 | base class for the <code><a href="arithmetic.html">endian_arithmetic</a></code> | |
85 | class template, which is aimed at users who wish fully automatic endianness | |
86 | conversion and direct support for all normal arithmetic operations.</p> | |
87 | <h2><a name="Example">Example</a></h2> | |
88 | <p>The <b><code>example/endian_example.cpp</code></b> program writes a | |
89 | binary file containing four-byte, big-endian and little-endian integers:</p> | |
90 | <blockquote> | |
91 | <pre>#include <iostream> | |
92 | #include <cstdio> | |
93 | #include <boost/endian/buffers.hpp> // see <a href="#Synopsis">Synopsis</a> below | |
94 | #include <boost/static_assert.hpp> | |
95 | ||
96 | using namespace boost::endian; | |
97 | ||
98 | namespace | |
99 | { | |
100 | // This is an extract from a very widely used GIS file format. | |
101 | // Why the designer decided to mix big and little endians in | |
102 | // the same file is not known. But this is a real-world format | |
103 | // and users wishing to write low level code manipulating these | |
104 | // files have to deal with the mixed endianness. | |
105 | ||
106 | struct header | |
107 | { | |
108 | big_int32_<code>buf_</code>t file_code; | |
109 | big_int32_<code>buf_</code>t file_length; | |
110 | little_int32_<code>buf_</code>t version; | |
111 | little_int32_<code>buf_</code>t shape_type; | |
112 | }; | |
113 | ||
114 | const char* filename = "test.dat"; | |
115 | } | |
116 | ||
117 | int main(int, char* []) | |
118 | { | |
119 | header h; | |
120 | ||
121 | BOOST_STATIC_ASSERT(sizeof(h) == 16U); // reality check | |
122 | ||
123 | h.file_code = 0x01020304; | |
124 | h.file_length = sizeof(header); | |
125 | h.version = 1; | |
126 | h.shape_type = 0x01020304; | |
127 | ||
128 | // Low-level I/O such as POSIX read/write or <cstdio> | |
129 | // fread/fwrite is sometimes used for binary file operations | |
130 | // when ultimate efficiency is important. Such I/O is often | |
131 | // performed in some C++ wrapper class, but to drive home the | |
132 | // point that endian integers are often used in fairly | |
133 | // low-level code that does bulk I/O operations, <cstdio> | |
134 | // fopen/fwrite is used for I/O in this example. | |
135 | ||
136 | std::FILE* fi = std::fopen(filename, "wb"); // MUST BE BINARY | |
137 | ||
138 | if (!fi) | |
139 | { | |
140 | std::cout << "could not open " << filename << '\n'; | |
141 | return 1; | |
142 | } | |
143 | ||
144 | if (std::fwrite(&h, sizeof(header), 1, fi)!= 1) | |
145 | { | |
146 | std::cout << "write failure for " << filename << '\n'; | |
147 | return 1; | |
148 | } | |
149 | ||
150 | std::fclose(fi); | |
151 | ||
152 | std::cout << "created file " << filename << '\n'; | |
153 | ||
154 | return 0; | |
155 | } | |
156 | </pre> | |
157 | </blockquote> | |
158 | <p>After compiling and executing <b><code>example/endian_example.cpp</code></b>, | |
159 | a hex dump of <code>test.dat</code> shows:</p> | |
160 | <blockquote> | |
161 | <pre>01020304 00000010 01000000 04030201</pre> | |
162 | </blockquote> | |
163 | <p>Notice that the first two 32-bit integers are big endian while the second two | |
164 | are little endian, even though the machine this was compiled and run on was | |
165 | little endian.</p> | |
166 | <h2><a name="Limitations">Limitations</a></h2> | |
167 | <p>Requires <code><climits></code> <code>CHAR_BIT == 8</code>. If <code>CHAR_BIT</code> | |
168 | is some other value, compilation will result in an <code>#error</code>. This | |
169 | restriction is in place because the design, implementation, testing, and | |
170 | documentation has only considered issues related to 8-bit bytes, and there have | |
171 | been no real-world use cases presented for other sizes.</p> | |
172 | <p>In C++03, <code>endian_buffer</code> does not meet the requirements for POD types | |
173 | because it has constructors, private data members, and a base class. This means | |
174 | that common use cases are relying on unspecified behavior in that the C++ | |
175 | Standard does not guarantee memory layout for non-POD types. This has not been a | |
176 | problem in practice since all known C++ compilers lay out memory as if <code> | |
177 | endian</code> were a POD type. In C++11, it is possible to specify the | |
178 | default constructor as trivial, and private data members and base classes no longer disqualify a type from being a POD | |
179 | type. Thus under C++11, <code>endian_buffer</code> | |
180 | will no longer be relying on unspecified behavior.</p> | |
181 | <h2><a name="Feature-set">Feature set</a></h2> | |
182 | <ul> | |
183 | <li>Big endian| little endian | native endian byte ordering.</li> | |
184 | <li>Signed | unsigned</li> | |
185 | <li>Unaligned | aligned</li> | |
186 | <li>1-8 byte (unaligned) | 1, 2, 4, 8 byte (aligned)</li> | |
187 | <li>Choice of value type</li> | |
188 | </ul> | |
189 | <h2>Enums and t<a name="Types">ypedefs</a></h2> | |
190 | <p>Two scoped enums are provided:</p> | |
191 | <blockquote> | |
192 | <pre>enum class order {big, little, native}; | |
193 | ||
194 | enum class align {no, yes}; </pre> | |
195 | </blockquote> | |
196 | <p>One class template is provided:</p> | |
197 | <blockquote> | |
198 | <pre>template <order Order, typename T, std::size_t Nbits, | |
199 | align Align = align::no> | |
200 | class endian_buffer; | |
201 | </pre> | |
202 | </blockquote> | |
203 | <p>Typedefs, such as <code>big_int32_buf_t</code>, provide convenient naming | |
204 | conventions for common use cases:</p> | |
205 | <blockquote> | |
206 | <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="49%"> | |
207 | <tr> | |
208 | <td width="18%" align="center"><b><i>Name</i></b></td> | |
209 | <td width="49%" align="center"><b><i>Alignment</i></b></td> | |
210 | <td width="10%" align="center"><b><i>Endianness</i></b></td> | |
211 | <td width="10%" align="center"><b><i>Sign</i></b></td> | |
212 | <td width="15%" align="center"><b><i>Sizes in bits (n)</i></b></td> | |
213 | </tr> | |
214 | <tr> | |
215 | <td width="18%" dir="ltr"><code>big_int</code><b><i>n</i></b><code>_buf_t</code></td> | |
216 | <td width="49%" align="center" dir="ltr"><code>no</code></td> | |
217 | <td width="10%" align="center" dir="ltr"><code>big</code></td> | |
218 | <td width="10%" align="center" dir="ltr">signed</td> | |
219 | <td width="15%" dir="ltr">8,16,24,32,40,48,56,64</td> | |
220 | </tr> | |
221 | <tr> | |
222 | <td width="18%" dir="ltr"><code>big_uint</code><i><b>n</b></i><code>_buf_t</code></td> | |
223 | <td width="49%" align="center" dir="ltr"><code>no</code></td> | |
224 | <td width="10%" align="center" dir="ltr"><code>big</code></td> | |
225 | <td width="10%" align="center" dir="ltr">unsigned</td> | |
226 | <td width="15%" dir="ltr">8,16,24,32,40,48,56,64</td> | |
227 | </tr> | |
228 | <tr> | |
229 | <td width="18%"><code>little_int</code><i><b>n</b></i><code>_buf_t</code></td> | |
230 | <td width="49%" align="center"><code>no</code></td> | |
231 | <td width="10%" align="center"><code>little</code></td> | |
232 | <td width="10%" align="center">signed</td> | |
233 | <td width="15%">8,16,24,32,40,48,56,64</td> | |
234 | </tr> | |
235 | <tr> | |
236 | <td width="18%"><code>little_uint</code><i><b>n</b></i><code>_buf_t</code></td> | |
237 | <td width="49%" align="center"><code>no</code></td> | |
238 | <td width="10%" align="center"><code>little</code></td> | |
239 | <td width="10%" align="center">unsigned</td> | |
240 | <td width="15%">8,16,24,32,40,48,56,64</td> | |
241 | </tr> | |
242 | <tr> | |
243 | <td width="18%"><code>native_int</code><i><b>n</b></i><code>_buf_t</code></td> | |
244 | <td width="49%" align="center"><code>no</code></td> | |
245 | <td width="10%" align="center"><code>native</code></td> | |
246 | <td width="10%" align="center">signed</td> | |
247 | <td width="15%">8,16,24,32,40,48,56,64</td> | |
248 | </tr> | |
249 | <tr> | |
250 | <td width="18%"><code>native_uint</code><i><b>n</b></i><code>_buf_t</code></td> | |
251 | <td width="49%" align="center"><code>no</code></td> | |
252 | <td width="10%" align="center"><code>native</code></td> | |
253 | <td width="10%" align="center">unsigned</td> | |
254 | <td width="15%">8,16,24,32,40,48,56,64</td> | |
255 | </tr> | |
256 | <tr> | |
257 | <td width="18%"><code>big_int</code><i><b>n</b></i><code>_buf_at</code></td> | |
258 | <td width="49%" align="center"><code>yes</code></td> | |
259 | <td width="10%" align="center"><code>big</code></td> | |
260 | <td width="10%" align="center">signed</td> | |
261 | <td width="15%">8,16,32,64</td> | |
262 | </tr> | |
263 | <tr> | |
264 | <td width="18%"><code>big_uint</code><i><b>n</b></i><code>_</code><code>buf_at</code></td> | |
265 | <td width="49%" align="center"><code>yes</code></td> | |
266 | <td width="10%" align="center"><code>big</code></td> | |
267 | <td width="10%" align="center">unsigned</td> | |
268 | <td width="15%">8,16,32,64</td> | |
269 | </tr> | |
270 | <tr> | |
271 | <td width="18%"><code>little_int</code><i><b>n</b></i><code>_</code><code>buf_at</code></td> | |
272 | <td width="49%" align="center"><code>yes</code></td> | |
273 | <td width="10%" align="center"><code>little</code></td> | |
274 | <td width="10%" align="center">signed</td> | |
275 | <td width="15%">8,16,32,64</td> | |
276 | </tr> | |
277 | <tr> | |
278 | <td width="18%"><code>little_uint</code><i><b>n</b></i><code>_</code><code>buf_at</code></td> | |
279 | <td width="49%" align="center"><code>yes</code></td> | |
280 | <td width="10%" align="center"><code>little</code></td> | |
281 | <td width="10%" align="center">unsigned</td> | |
282 | <td width="15%">8,16,32,64</td> | |
283 | </tr> | |
284 | </table> | |
285 | </blockquote> | |
286 | <p>The unaligned types do not cause compilers to insert padding bytes in classes | |
287 | and structs. This is an important characteristic that can be exploited to minimize wasted space in | |
288 | memory, files, and network transmissions. </p> | |
289 | <p><font color="#FF0000"><b><i><span style="background-color: #FFFFFF">Warning:</span></i></b></font><span style="background-color: #FFFFFF"> | |
290 | Code that uses a</span>ligned types is possibly non-portable because alignment | |
291 | requirements vary between hardware architectures and because alignment may be | |
292 | affected by compiler switches or pragmas. For example, alignment of an 64-bit | |
293 | integer may be to a 32-bit boundary on a 32-bit machine and to a 64-bit boundary | |
294 | on a 64-bit machine. Furthermore, aligned types | |
295 | are only available on architectures with 8, 16, 32, and 64-bit integer types. </p> | |
296 | <p><i><b>Recommendation:</b></i> Prefer unaligned buffer types.</p> | |
297 | <p><i><b>Recommendation:</b></i> Protect yourself against alignment ills. For | |
298 | example:</p> | |
299 | <blockquote> | |
300 | <pre>static_assert(sizeof(containing_struct) == 12, "sizeof(containing_struct) is wrong"); </pre> | |
301 | </blockquote> | |
302 | <p><b><i>Note:</i></b> One-byte big and little buffer types | |
303 | have identical layout on all platforms, so they never actually reverse endianness. They are provided to enable generic code, and | |
304 | to improve code readability and searchability.</p> | |
305 | <h2><a name="Class_template_endian">Class template <code>endian</code></a><code>_buffer</code></h2> | |
306 | <p>An <code>endian_buffer</code> is a byte-holder for arithmetic types with user-specified <a href="#endianness"> | |
307 | endianness</a>, value type, size, and <a href="#alignment">alignment</a>.</p> | |
308 | <h3><a name="Synopsis">Synopsis</a></h3> | |
309 | <pre>#include <boost/endian/conversion.hpp | |
310 | ||
311 | namespace boost | |
312 | { | |
313 | namespace endian | |
314 | { | |
315 | // C++11 features emulated if not available | |
316 | ||
317 | enum class <a name="alignment">align</a> {no, yes}; | |
318 | ||
319 | template <order Order, class T, std::size_t Nbits, | |
320 | align Align = align::no> | |
321 | class endian_buffer | |
322 | { | |
323 | public: | |
324 | typedef T value_type; | |
325 | ||
326 | <a href="#endian">endian_buffer</a>() noexcept = default; | |
327 | explicit <a href="#explicit-endian">endian_buffer</a>(T v) noexcept; | |
328 | ||
329 | endian_buffer& <a href="#operator-eq">operator=</a>(T v) noexcept; | |
330 | value_type <a href="#value">value</a>() const noexcept; | |
331 | const char* <a href="#data">data</a>() const noexcept; | |
332 | protected: | |
333 | <b><i>implementaton-defined</i></b> endian_value; // for exposition only | |
334 | }; | |
335 | ||
336 | // stream inserter | |
337 | template <class charT, class traits, order Order, class T, | |
338 | std::size_t n_bits, align Align> | |
339 | std::basic_ostream<charT, traits>& | |
340 | <a href="#inserter">operator<<</a>(std::basic_ostream<charT, traits>& os, | |
341 | const endian_buffer<Order, T, n_bits, Align>& x); | |
342 | ||
343 | // stream extractor | |
344 | template <class charT, class traits, order Order, class T, | |
345 | std::size_t n_bits, align A> | |
346 | std::basic_istream<charT, traits>& | |
347 | <a href="#extractor">operator>></a>(std::basic_istream<charT, traits>& is, | |
348 | endian_buffer<Order, T, n_bits, Align>& x); | |
349 | ||
350 | // typedefs | |
351 | ||
352 | // unaligned big endian signed integer buffers | |
353 | typedef endian_buffer<order::big, int_least8_t, 8> big_int8_buf_t; | |
354 | typedef endian_buffer<order::big, int_least16_t, 16> big_int16_buf_t; | |
355 | typedef endian_buffer<order::big, int_least32_t, 24> big_int24_buf_t; | |
356 | typedef endian_buffer<order::big, int_least32_t, 32> big_int32_buf_t; | |
357 | typedef endian_buffer<order::big, int_least64_t, 40> big_int40_buf_t; | |
358 | typedef endian_buffer<order::big, int_least64_t, 48> big_int48_buf_t; | |
359 | typedef endian_buffer<order::big, int_least64_t, 56> big_int56_buf_t; | |
360 | typedef endian_buffer<order::big, int_least64_t, 64> big_int64_buf_t; | |
361 | ||
362 | // unaligned big endian unsigned integer buffers | |
363 | typedef endian_buffer<order::big, uint_least8_t, 8> big_uint8_buf_t; | |
364 | typedef endian_buffer<order::big, uint_least16_t, 16> big_uint16_buf_t; | |
365 | typedef endian_buffer<order::big, uint_least32_t, 24> big_uint24_buf_t; | |
366 | typedef endian_buffer<order::big, uint_least32_t, 32> big_uint32_buf_t; | |
367 | typedef endian_buffer<order::big, uint_least64_t, 40> big_uint40_buf_t; | |
368 | typedef endian_buffer<order::big, uint_least64_t, 48> big_uint48_buf_t; | |
369 | typedef endian_buffer<order::big, uint_least64_t, 56> big_uint56_buf_t; | |
370 | typedef endian_buffer<order::big, uint_least64_t, 64> big_uint64_buf_t; | |
371 | ||
372 | // unaligned little endian signed integer buffers | |
373 | typedef endian_buffer<order::little, int_least8_t, 8> little_int8_buf_t; | |
374 | typedef endian_buffer<order::little, int_least16_t, 16> little_int16_buf_t; | |
375 | typedef endian_buffer<order::little, int_least32_t, 24> little_int24_buf_t; | |
376 | typedef endian_buffer<order::little, int_least32_t, 32> little_int32_buf_t; | |
377 | typedef endian_buffer<order::little, int_least64_t, 40> little_int40_buf_t; | |
378 | typedef endian_buffer<order::little, int_least64_t, 48> little_int48_buf_t; | |
379 | typedef endian_buffer<order::little, int_least64_t, 56> little_int56_buf_t; | |
380 | typedef endian_buffer<order::little, int_least64_t, 64> little_int64_buf_t; | |
381 | ||
382 | // unaligned little endian unsigned integer buffers | |
383 | typedef endian_buffer<order::little, uint_least8_t, 8> little_uint8_buf_t; | |
384 | typedef endian_buffer<order::little, uint_least16_t, 16> little_uint16_buf_t; | |
385 | typedef endian_buffer<order::little, uint_least32_t, 24> little_uint24_buf_t; | |
386 | typedef endian_buffer<order::little, uint_least32_t, 32> little_uint32_buf_t; | |
387 | typedef endian_buffer<order::little, uint_least64_t, 40> little_uint40_buf_t; | |
388 | typedef endian_buffer<order::little, uint_least64_t, 48> little_uint48_buf_t; | |
389 | typedef endian_buffer<order::little, uint_least64_t, 56> little_uint56_buf_t; | |
390 | typedef endian_buffer<order::little, uint_least64_t, 64> little_uint64_buf_t; | |
391 | ||
392 | // unaligned native endian signed integer types | |
393 | typedef <b><i>implementation-defined</i></b>_int8_buf_t native_int8_buf_t; | |
394 | typedef <b><i>implementation-defined</i></b>_int16_buf_t native_int16_buf_t; | |
395 | typedef <b><i>implementation-defined</i></b>_int24_buf_t native_int24_buf_t; | |
396 | typedef <b><i>implementation-defined</i></b>_int32_buf_t native_int32_buf_t; | |
397 | typedef <b><i>implementation-defined</i></b>_int40_buf_t native_int40_buf_t; | |
398 | typedef <b><i>implementation-defined</i></b>_int48_buf_t native_int48_buf_t; | |
399 | typedef <b><i>implementation-defined</i></b>_int56_buf_t native_int56_buf_t; | |
400 | typedef <b><i>implementation-defined</i></b>_int64_buf_t native_int64_buf_t; | |
401 | ||
402 | // unaligned native endian unsigned integer types | |
403 | typedef <b><i>implementation-defined</i></b>_uint8_buf_t native_uint8_buf_t; | |
404 | typedef <b><i>implementation-defined</i></b>_uint16_buf_t native_uint16_buf_t; | |
405 | typedef <b><i>implementation-defined</i></b>_uint24_buf_t native_uint24_buf_t; | |
406 | typedef <b><i>implementation-defined</i></b>_uint32_buf_t native_uint32_buf_t; | |
407 | typedef <b><i>implementation-defined</i></b>_uint40_buf_t native_uint40_buf_t; | |
408 | typedef <b><i>implementation-defined</i></b>_uint48_buf_t native_uint48_buf_t; | |
409 | typedef <b><i>implementation-defined</i></b>_uint56_buf_t native_uint56_buf_t; | |
410 | typedef <b><i>implementation-defined</i></b>_uint64_buf_t native_uint64_buf_t; | |
411 | ||
412 | // aligned big endian signed integer buffers | |
413 | typedef endian_buffer<order::big, int8_t, 8, align::yes> big_int8_buf_at; | |
414 | typedef endian_buffer<order::big, int16_t, 16, align::yes> big_int16_buf_at; | |
415 | typedef endian_buffer<order::big, int32_t, 32, align::yes> big_int32_buf_at; | |
416 | typedef endian_buffer<order::big, int64_t, 64, align::yes> big_int64_buf_at; | |
417 | ||
418 | // aligned big endian unsigned integer buffers | |
419 | typedef endian_buffer<order::big, uint8_t, 8, align::yes> big_uint8_buf_at; | |
420 | typedef endian_buffer<order::big, uint16_t, 16, align::yes> big_uint16_buf_at; | |
421 | typedef endian_buffer<order::big, uint32_t, 32, align::yes> big_uint32_buf_at; | |
422 | typedef endian_buffer<order::big, uint64_t, 64, align::yes> big_uint64_buf_at; | |
423 | ||
424 | // aligned little endian signed integer buffers | |
425 | typedef endian_buffer<order::little, int8_t, 8, align::yes> little_int8_buf_at; | |
426 | typedef endian_buffer<order::little, int16_t, 16, align::yes> little_int16_buf_at; | |
427 | typedef endian_buffer<order::little, int32_t, 32, align::yes> little_int32_buf_at; | |
428 | typedef endian_buffer<order::little, int64_t, 64, align::yes> little_int64_buf_at; | |
429 | ||
430 | // aligned little endian unsigned integer buffers | |
431 | typedef endian_buffer<order::little, uint8_t, 8, align::yes> little_uint8_buf_at; | |
432 | typedef endian_buffer<order::little, uint16_t, 16, align::yes> little_uint16_buf_at; | |
433 | typedef endian_buffer<order::little, uint32_t, 32, align::yes> little_uint32_buf_at; | |
434 | typedef endian_buffer<order::little, uint64_t, 64, align::yes> little_uint64_buf_at; | |
435 | ||
436 | // aligned native endian typedefs are not provided because | |
437 | // <cstdint> types are superior for this use case | |
438 | ||
439 | } // namespace endian | |
440 | } // namespace boost</pre> | |
441 | <p>The <i><b><code>implementation-defined</code></b></i> text in typedefs above is either | |
442 | <code>big</code> or <code>little</code> according to the native endianness of the | |
443 | platform.</p> | |
444 | <p>The expository data member <code>endian_value</code> stores the current value | |
445 | of an <code>endian_value</code> object as a sequence of bytes ordered as | |
446 | specified by the <code>Order</code> template parameter. The <i><b><code> | |
447 | implementation-defined</code></b></i> type of <code>endian_value</code> is a | |
448 | type such as <code><span style="font-size: 85%">char[Nbits/CHAR_BIT]</span></code> | |
449 | or <code><span style="font-size: 85%">T</span></code> that meets the | |
450 | requirements imposed by the <code>Nbits</code> and <code>Align</code> template | |
451 | parameters. The <code><span style="font-size: 85%">CHAR_BIT</span></code> | |
452 | macro is defined in <code><span style="font-size: 85%"><climits></span></code>. | |
453 | The only value of <code><span style="font-size: 85%">CHAR_BIT</span></code> that | |
454 | is required to be supported is 8.</p> | |
455 | <p>Template parameter <code><span style="font-size: 85%">T</span></code> is | |
456 | required to be a standard integer type (C++std, 3.9.1) and <code> | |
457 | <span style="font-size: 85%">sizeof(T)*CHAR_BIT</span></code> is required to be | |
458 | greater or equal to <span style="font-size: 85%"> <code>Nbits</code>.</span></p> | |
459 | <h3><a name="Members">Members</a></h3> | |
460 | <pre><code><a name="endian">endian</a>_buffer() noexcept = default;</code></pre> | |
461 | <blockquote> | |
462 | <p><i>Effects:</i> Constructs an uninitialized object of type <code>endian_buffer<Order, T, | |
463 | Nbits, Align></code>.</p> | |
464 | </blockquote> | |
465 | <pre><code>explicit <a name="explicit-endian">endian</a>_buffer(T v) noexcept;</code></pre> | |
466 | <blockquote> | |
467 | <p><i>Effects:</i> Constructs an object of type <code>endian_buffer<Order, T, | |
468 | Nbits, Align></code>.</p> | |
469 | <p><i>Postcondition:</i> <code>value() == v & mask</code>, where <code>mask</code> | |
470 | is a constant of type <code>value_type</code> with <code>Nbits</code> low-order | |
471 | bits set to one.</p> | |
472 | <p><i>Remarks:</i> If <code>Align</code> is <code>align::yes</code> then | |
473 | endianness conversion, if required, is performed by <code> | |
474 | boost::endian::endian_reverse</code>.</p> | |
475 | </blockquote> | |
476 | <pre><code>endian_buffer& <a name="operator-eq">operator=</a>(T v) noexcept;</code></pre> | |
477 | <blockquote> | |
478 | <p><i>Postcondition:</i> <code>value() == v & mask</code>, where <code>mask</code> | |
479 | is a constant of type <code>value_type</code> with <code>Nbits</code> | |
480 | low-order bits set to one.</p> | |
481 | <p><i>Returns:</i> <code>*this</code>.</p> | |
482 | <p><i>Remarks:</i> If <code>Align</code> is <code>align::yes</code> then | |
483 | endianness conversion, if required, is performed by <code> | |
484 | boost::endian::endian_reverse</code>.</p> | |
485 | </blockquote> | |
486 | <pre>value_type <a name="value">value</a>()<code> const noexcept;</code></pre> | |
487 | <blockquote> | |
488 | <p><i>Returns:</i> <code>endian_value</code>, converted to <code>value_type</code>, | |
489 | if required, and having the endianness of the native platform.</p> | |
490 | <p><i>Remarks:</i> If <code>Align</code> is <code>align::yes</code> then | |
491 | endianness conversion, if required, is performed by <code> | |
492 | boost::endian::endian_reverse</code>.</p> | |
493 | </blockquote> | |
494 | <pre><code>const char* <a name="data">data</a>() const noexcept;</code></pre> | |
495 | <blockquote> | |
496 | <p><i>Returns:</i> A pointer to the first byte of <code>endian_value</code>.</p> | |
497 | </blockquote> | |
498 | <h3><a name="Non-member-functions">Non-member functions</a></h3> | |
499 | <pre>template <class charT, class traits, order Order, class T, | |
500 | std::size_t n_bits, align Align> | |
501 | std::basic_ostream<charT, traits>& <a name="inserter">operator<<</a>(std::basic_ostream<charT, traits>& os, | |
502 | const endian_buffer<Order, T, n_bits, Align>& x); | |
503 | </pre> | |
504 | <blockquote> | |
505 | <p><i>Returns:</i> <code>os << x.value()</code>.</p> | |
506 | </blockquote> | |
507 | <pre>template <class charT, class traits, order Order, class T, | |
508 | std::size_t n_bits, align A> | |
509 | std::basic_istream<charT, traits>& <a name="extractor">operator>></a>(std::basic_istream<charT, traits>& is, | |
510 | endian_buffer<Order, T, n_bits, Align>& x); | |
511 | </pre> | |
512 | <blockquote> | |
513 | <p><i>Effects: </i>As if:</p> | |
514 | <blockquote> | |
515 | <pre>T i; | |
516 | if (is >> i) | |
517 | x = i; | |
518 | </pre> | |
519 | </blockquote> | |
520 | <p><i>Returns:</i> <code>is</code>.</p> | |
521 | </blockquote> | |
522 | <h2><a name="FAQ">FAQ</a></h2> | |
523 | ||
524 | <p>See the <a href="index.html#FAQ">Endian home page</a> FAQ for a library-wide | |
525 | FAQ.</p> | |
526 | ||
527 | <p><b>Why not just use Boost.Serialization?</b> Serialization involves a | |
528 | conversion for every object involved in I/O. Endian integers require no | |
529 | conversion or copying. They are already in the desired format for binary I/O. | |
530 | Thus they can be read or written in bulk.</p> | |
531 | <p><b>Are endian types PODs?</b> Yes for C++11. No for C++03, although several | |
532 | <a href="#Compilation">macros</a> are available to force PODness in all cases.</p> | |
533 | <p><b>What are the implications of endian integer types not being PODs with C++03 | |
534 | compilers?</b> They | |
535 | can't be used in unions. Also, compilers aren't required to align or lay | |
536 | out storage in portable ways, although this potential problem hasn't prevented | |
537 | use of Boost.Endian with | |
538 | real compilers.</p> | |
539 | <p><b>What good is <i>native </i>endianness?</b> It provides alignment and | |
540 | size guarantees not available from the built-in types. It eases generic | |
541 | programming.</p> | |
542 | <p><b>Why bother with the aligned endian types?</b> Aligned integer operations | |
543 | may be faster (as much as 10 to 20 times faster) if the endianness and alignment of | |
544 | the type matches the endianness and alignment requirements of the machine. The code, | |
545 | however, is | |
546 | likely to be somewhat less portable than with the unaligned types.</p> | |
547 | <h2><a name="Design">Design</a> considerations for Boost.Endian buffers</h2> | |
548 | <ul> | |
549 | <li>Must be suitable for I/O - in other words, must be memcpyable.</li> | |
550 | <li>Must provide exactly the size and internal byte ordering specified.</li> | |
551 | <li>Must work correctly when the internal integer representation has more bits | |
552 | that the sum of the bits in the external byte representation. Sign extension | |
553 | must work correctly when the internal integer representation type has more | |
554 | bits than the sum of the bits in the external bytes. For example, using | |
555 | a 64-bit integer internally to represent 40-bit (5 byte) numbers must work for | |
556 | both positive and negative values.</li> | |
557 | <li>Must work correctly (including using the same defined external | |
558 | representation) regardless of whether a compiler treats char as signed or | |
559 | unsigned.</li> | |
560 | <li>Unaligned types must not cause compilers to insert padding bytes.</li> | |
561 | <li>The implementation should supply optimizations with great care. Experience has shown that optimizations of endian | |
562 | integers often become pessimizations when changing | |
563 | machines or compilers. Pessimizations can also happen when changing compiler switches, | |
564 | compiler versions, or CPU models of the same architecture.</li> | |
565 | </ul> | |
566 | <h2><a name="C++0x">C++11</a></h2> | |
567 | <p>The availability of the C++11 | |
568 | <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm"> | |
569 | Defaulted Functions</a> feature is detected automatically, and will be used if | |
570 | present to ensure that objects of <code>class endian_buffer</code> are trivial, and | |
571 | thus PODs.</p> | |
572 | <h2><a name="Compilation">Compilation</a></h2> | |
573 | <p>Boost.Endian is implemented entirely within headers, with no need to link to | |
574 | any Boost object libraries.</p> | |
575 | <p>Several macros allow user control over features:</p> | |
576 | <ul> | |
577 | <li>BOOST_ENDIAN_NO_CTORS causes <code>class endian_buffer</code> to have no | |
578 | constructors. The intended use is for compiling user code that must be | |
579 | portable between compilers regardless of C++11 | |
580 | <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm"> | |
581 | Defaulted Functions</a> support. Use of constructors will always fail, <br> | |
582 | </li> | |
583 | <li>BOOST_ENDIAN_FORCE_PODNESS causes BOOST_ENDIAN_NO_CTORS to be defined if | |
584 | the compiler does not support C++11 | |
585 | <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm"> | |
586 | Defaulted Functions</a>. This is ensures that objects of <code>class endian_buffer</code> | |
587 | are PODs, and so can be used in C++03 unions. | |
588 | In C++11, <code>class endian_buffer</code> objects are PODs, even though they have | |
589 | constructors, so can always be used in unions.</li> | |
590 | </ul> | |
591 | <hr> | |
592 | <p>Last revised: | |
593 | <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->14 October, 2015<!--webbot bot="Timestamp" endspan i-checksum="38874" --></p> | |
594 | <p>© Copyright Beman Dawes, 2006-2009, 2013</p> | |
595 | <p>Distributed under the Boost Software License, Version 1.0. See | |
596 | <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/ LICENSE_1_0.txt</a></p> | |
597 | ||
598 | </body> | |
599 | ||
600 | </html> |