| blob | de2e49e4477b0b0d53139048e22c963377d62f5e |
1 <html>
3 <head>
10 </head>
12 <body>
15 <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
16 <tr>
19 <img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="277" height="86" border="0"></a></td>
22 </td>
23 </tr>
24 </table>
26 <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="100%">
27 <tr>
29 </tr>
30 </table>
32 <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" align="right">
33 <tr>
36 </tr>
37 <tr>
46
57 </td>
58 </tr>
59 <tr>
62 </tr>
63 <tr>
66 <a href="../../../boost/integer/endian_binary_stream.hpp"><boost/integer/endian_binary_stream.hpp></a><br>
68 </tr>
69 </table>
71 <p>Header
73 integer-like byte-holder binary types with explicit control over
74 byte order, value type, size, and alignment. Typedefs provide easy-to-use names
75 for common configurations.</p>
76 <p>These types provide portable byte-holders for integer data, independent of
77 particular computer architectures. Use cases almost always involve I/O, either via files or
78 network connections. Although data portability is the primary motivation, these
79 integer byte-holders may
80 also be used to reduce memory use, file size, or network activity since they
81 provide binary integer sizes not otherwise available.</p>
84 a full
87 <p>Boost endian integers provide the same full set of C++ assignment,
88 arithmetic, and relational operators as C++ standard integral types, with
89 the standard semantics.</p>
95 <code>^</code>, <code>^=</code>, <code><<</code>, <code><<=</code>, <code>>></code>,
99 <p>Header <a href="../../../boost/integer/endian_binary_stream.hpp"><boost/integer/endian_binary_stream.hpp></a>
101 formatted character) stream insertion and extraction of endian types.</p>
104 formatted character) stream insertion and extraction of built-in and std::string
105 types.</p>
107 <blockquote>
113 using namespace boost;
114 using namespace boost::integer;
116 int main()
117 {
119 // value chosen to work on text stream
120 big32_t b(v);
121 little32_t l(v);
127 }</pre>
128 </blockquote>
130 <blockquote>
131 <pre>Hello, endian world!
133 825373492 825373492 825373492
135 </blockquote>
139 restriction is in place because the design, implementation, testing, and
140 documentation has only considered issues related to 8-bit bytes, and there have
141 been no real-world use cases presented for other sizes.</p>
143 because it has constructors, private data members, and a base class. This means
144 that common use cases are relying on unspecified behavior in that the C++
145 Standard does not guarantee memory layout for non-POD types. This has not been a
146 problem in practice since all known C++ compilers do layout memory as if <code>
148 default constructor as trivial, and private data members and base classes will
150 will no longer be relying on unspecified behavior.</p>
152 <ul>
158 </ul>
161 <blockquote>
162 <pre>template <<a href="#endianness">endianness</a>::enum_t E, typename T, std::size_t n_bytes,
164 class endian;
165 </pre>
166 </blockquote>
168 conventions for common use cases:</p>
169 <blockquote>
170 <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="49%">
171 <tr>
177 </tr>
178 <tr>
184 </tr>
185 <tr>
191 </tr>
192 <tr>
198 </tr>
199 <tr>
205 </tr>
206 <tr>
212 </tr>
213 <tr>
219 </tr>
220 <tr>
226 </tr>
227 <tr>
233 </tr>
234 <tr>
240 </tr>
241 <tr>
247 </tr>
248 </table>
249 </blockquote>
250 <p>The unaligned types do not cause compilers to insert padding bytes in classes
251 and structs. This is an important characteristic that can be exploited to minimize wasted space in
252 memory, files, and network transmissions. </p>
253 <p><font color="#FF0000"><b><i><span style="background-color: #FFFFFF">Warning:</span></i></b></font><span style="background-color: #FFFFFF">
254 Code that uses a</span>ligned types is inherently non-portable because alignment
255 requirements vary between hardware architectures and because alignment may be
256 affected by compiler switches or pragmas. Furthermore, aligned types
258 <p><b><i>Note:</i></b> One-byte big-endian, little-endian, and native-endian types provide identical
259 functionality. All three names are provided to improve code readability and searchability.</p>
261 <p>When first exposed to endian types, programmers often fit them into a mental model
265 <p>As experience using these type grows, the realization creeps in that they are
266 lousy arithmetic integers - they are really byte holders that for convenience
267 support arithmetic operations - and that for use in internal interfaces or
268 anything more than trivial arithmetic computations it is far better to convert
269 values of these endian types to traditional integer types.</p>
270 <p>That seems to lead to formation of a new mental model specific to endian byte-holder types. In that model, the endianness
271 is the key feature, and the integer aspect is downplayed.
273 reflection of the mental model</p>
277 usual operations on integers are supplied.</p>
279 <pre>namespace boost
280 {
281 namespace integer
282 {
284 enum class <a name="endianness">endianness</a> { big, little, native }; // scoped enum emulated on C++03
285 enum class <a name="alignment">alignment</a> { unaligned, aligned }; // scoped enum emulated on C++03
287 template <endianness E, typename T, std::size_t n_bits,
288 alignment A = alignment::unaligned>
289 class endian : <a href="../../../boost/integer/cover_operators.hpp">integer_cover_operators</a>< endian<E, T, n_bits, A>, T >
290 {
291 public:
292 typedef T value_type;
297 };
299 // unaligned big endian signed integer types
309 // unaligned big endian unsigned integer types
319 // unaligned little endian signed integer types
329 // unaligned little endian unsigned integer types
339 // unaligned native endian signed integer types
349 // unaligned native endian unsigned integer types
359 // These types only present if platform has exact size integers:
361 // aligned big endian signed integer types
366 // aligned big endian unsigned integer types
371 // aligned little endian signed integer types
376 // aligned little endian unsigned integer types
377 typedef endian< endianness::little, uint16_t, 16, alignment::aligned > aligned_ulittle2_t;
378 typedef endian< endianness::little, uint32_t, 32, alignment::aligned > aligned_ulittle4_t;
379 typedef endian< endianness::little, uint64_t, 64, alignment::aligned > aligned_ulittle8_t;
382 // aligned native endian typedefs are not provided because
385 } // namespace integer
386 } // namespace boost</pre>
389 <blockquote>
391 </blockquote>
393 <blockquote>
396 constructed object.</p>
397 </blockquote>
399 <blockquote>
401 constructed object.</p>
403 </blockquote>
405 <blockquote>
408 </blockquote>
410 <p>Other operators on endian objects are forwarded to the equivalent
414 and space efficiency. Availability
415 of additional binary integer sizes and alignments is important in some
416 applications.</p>
418 conversion for every object involved in I/O. Endian objects require no
419 conversion or copying. They are already in the desired format for binary I/O.
420 Thus they can be read or written in bulk.</p>
421 <p><b>Why bother with binary I/O? Why not just use C++ Standard Library stream
422 inserters and extractors?</b> Using binary rather than character representations
423 can be more space efficient, with a side benefit of faster I/O. CPU time is
424 minimized because conversions to and from string are eliminated.
425 Furthermore, binary integers are fixed size, and so fixed-size disk records
426 are possible, easing sorting and allowing direct access. Disadvantages, such as the inability to use
427 text utilities on the resulting files, limit usefulness to applications where
428 the
429 binary I/O advantages are paramount.</p>
431 native endianness which can be used for fine grained control over size and
432 alignment.</p>
434 compared to arithmetic operations on native integer types. However, these types
435 are usually be faster, and sometimes much faster, for I/O compared to stream
436 inserters and extractors, or to serialization.</p>
440 can't be used in unions. In theory, compilers aren't required to align or lay
441 out storage in portable ways, although this problem has never been observed in a
442 real compiler.</p>
444 bit more of an industry standard, but little-endian may be preferred for
445 applications that run primarily on x86 (Intel/AMD) and other little-endian
447 gives more pros and cons.</p>
449 size guarantees not available from the built-in types. It eases generic
450 programming.</p>
452 may be faster (20 times, in one measurement) if the endianness and alignment of
453 the type matches the endianness and alignment requirements of the machine. On
454 common CPU architectures, that optimization is only available for aligned types.
455 That allows I/O of maximally efficient types on an application's primary
456 platform, yet produces data files are portable to all platforms. The code,
457 however, is
458 likely to be more fragile and less portable than with the unaligned types.</p>
459 <p><b>These types are really just byte-holders. Why provide the arithmetic
460 operations at all?</b> Providing a full set of operations reduces program
461 clutter and makes code both easier to write and to read. Consider
462 incrementing a variable in a record. It is very convenient to write:</p>
466 ++temp;
467 record.foo = temp;</pre>
469 rather than <<= and >>=?</b> <<= and >>= associate right-to-left, which is the
471 associate left-to-right. </p>
473 <p><font color="#FF0000"><b><i><span style="background-color: #FFFFFF">Warning:</span></i></b></font><span style="background-color: #FFFFFF"> </span> Use
475 unformatted binary I/O should not be with the standard streams (cout, cin, etc.)
476 since they are opened in text mode. Use on text streams may produce incorrect
477 results, such as insertion of unwanted characters or premature end-of-file. For
481 operator <= or >=) stream I/O, be aware that << and >> take precedence over <=
483 <blockquote>
486 </blockquote>
487 <p>As a practical matter, it may be easier and safer to never mix the character
488 and binary insertion or extraction operators in the same statement.</p>
491 binary file containing four byte big-endian and little-endian integers:</p>
492 <blockquote>
498 using namespace boost::integer;
500 namespace
501 {
502 // This is an extract from a very widely used GIS file format. I have no idea
503 // why a designer would mix big and little endians in the same file - but
504 // this is a real-world format and users wishing to write low level code
505 // manipulating these files have to deal with the mixed endianness.
507 struct header
508 {
509 big32_t file_code;
510 big32_t file_length;
511 little32_t version;
512 little32_t shape_type;
513 };
516 }
518 int main()
519 {
520 assert( sizeof( header ) == 16 ); // requirement for interoperability
522 header h;
524 h.file_code = 0x04030201;
525 h.file_length = sizeof( header );
526 h.version = -1;
527 h.shape_type = 0x04030201;
530 // used for binary file operations when ultimate efficiency is important.
531 // Such I/O is often performed in some C++ wrapper class, but to drive home the
532 // point that endian integers are often used in fairly low-level code that
535 std::FILE * fi;
538 {
540 return 1;
541 }
544 {
546 return 1;
547 }
549 std::fclose( fi );
552 return 0;
553 }</pre>
554 </blockquote>
555 <p>After compiling and executing <a href="endian_example.cpp">endian_example.cpp</a>, a hex dump of <code>test.dat</code> shows:</p>
556 <blockquote>
558 </blockquote>
560 <ul>
563 <li>Must work correctly when the internal integer representation has more bits
564 that the sum of the bits in the external byte representation. Sign extension
565 must work correctly when the internal integer representation type has more
566 bits than the sum of the bits in the external bytes. For example, using
568 both positive and negative values.</li>
569 <li>Must work correctly (including using the same defined external
570 representation) regardless of whether a compiler treats char as signed or
571 unsigned.</li>
573 <li>The implementation should supply optimizations only in very limited
574 circumstances. Experience has shown that optimizations of endian
575 integers often become pessimizations. While this may be obvious when changing
576 machines or compilers, it also happens when changing compiler switches,
577 compiler versions, or CPU models of the same architecture.</li>
578 <li>It is better software engineering if the same implementation works regardless
579 of the CPU endianness. In other words, #ifdefs should be avoided where
580 possible.</li>
581 </ul>
583 <p>Classes with similar functionality have been independently developed by
584 several Boost programmers and used very successful in high-value, high-use
585 applications for many years. These independently developed endian libraries
586 often evolved from C libraries that were also widely used. Endian integers have proven widely useful across a wide
587 range of computer architectures and applications.</p>
591 Defaulted Functions</a> feature is detected automatically, and will be used if
593 thus POD's.</p>
595 <p>Boost.Endian is implemented entirely within headers, with no need to link to
596 any Boost object libraries.</p>
598 <ul>
600 constructors. The intended use is for compiling user code that must be
601 portable between compilers regardless of C++0x
605 <li>BOOST_ENDIAN_FORCE_PODNESS causes BOOST_ENDIAN_NO_CTORS to be defined if
606 the compiler does not support C++0x
608 Defaulted Functions</a>. This is ensures that , and so can be used in unions.
610 constructors.</li>
611 </ul>
613 <p>Original design developed by Darin Adler based on classes developed by Mark
615 class template by Beman Dawes, who put the library together, provided
617 sign partial specialization to correctly extend the sign when cover integer size
618 differs from endian representation size.</p>
619 <p>Comments and suggestions were
620 received from
621 Benaka Moorthi,
622 Christopher Kohlhoff,
623 Cliff Green,
624 Gennaro Proto,
625 Jeff Flinn,
626 John Maddock,
627 Kim Barrett,
628 Marsh Ray,
629 Martin Bonner,
630 Matias Capeletto,
631 Rene Rivera,
632 Scott McMurray,
633 Sebastian Redl,
634 Tomas Puverle, and
635 Yuval Ronen.</p>
636 <hr>
637 <p>Last revised:
638 <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->19 March, 2009<!--webbot bot="Timestamp" endspan i-checksum="29039" --></p>
644 </body>
646 </html>