| Home | Libraries | People | FAQ | More

##### Binary Native Endianness Generators

###### Description

The binary native endianness generators described in this section are used to emit binary byte streams laid out conforming to the native endianness (byte order) of the target architecture.

###### Header

    // forwards to <boost/spirit/home/karma/binary.hpp>
    #include <boost/spirit/include/karma_binary.hpp>

Also, see Include Structure.

###### Namespace

Name
`boost::spirit::byte_ // alias: boost::spirit::karma::byte_`
`boost::spirit::word // alias: boost::spirit::karma::word`
`boost::spirit::dword // alias: boost::spirit::karma::dword`
`boost::spirit::qword // alias: boost::spirit::karma::qword`

| Note
The generators `qword` and `qword(qw)` are only available on platforms where the preprocessor constant `BOOST_HAS_LONG_LONG` is defined (i.e. on platforms having native support for `unsigned long long` (64 bit) integer types).

###### Model of

> `PrimitiveGenerator`

Notation

`b`

  A single byte (8 bit binary value) or a Lazy Argument that evaluates to a single byte

`w`

  A 16 bit binary value or a Lazy Argument that evaluates to a 16 bit binary value. This value is always interpreted using native endianness.

`dw`

  A 32 bit binary value or a Lazy Argument that evaluates to a 32 bit binary value. This value is always interpreted using native endianness.

`qw`

  A 64 bit binary value or a Lazy Argument that evaluates to a 64 bit binary value. This value is always interpreted using native endianness.

###### Expression Semantics

Semantics of an expression is defined only where it differs from, or is not defined in `PrimitiveGenerator`.

Expression | Description
--- | ---
`byte_` | Output the binary representation of the least significant byte of the mandatory attribute. This generator never fails (unless the underlying output stream reports an error).
`word` | Output the binary representation of the least significant 16 bits of the mandatory attribute in native endian representation. This generator never fails (unless the underlying output stream reports an error).
`dword` | Output the binary representation of the least significant 32 bits of the mandatory attribute in native endian representation. This generator never fails (unless the underlying output stream reports an error).
`qword` | Output the binary representation of the least significant 64 bits of the mandatory attribute in native endian representation. This generator never fails (unless the underlying output stream reports an error).
`byte_(b)` | Output the binary representation of the least significant byte of the immediate parameter. This generator never fails (unless the underlying output stream reports an error).
`word(w)` | Output the binary representation of the least significant 16 bits of the immediate parameter in native endian representation. This generator never fails (unless the underlying output stream reports an error).
`dword(dw)` | Output the binary representation of the least significant 32 bits of the immediate parameter in native endian representation. This generator never fails (unless the underlying output stream reports an error).
`qword(qw)` | Output the binary representation of the least significant 64 bits of the immediate parameter in native endian representation. This generator never fails (unless the underlying output stream reports an error).

###### Attributes

Expression | Attribute
--- | ---
`byte_` | `boost::uint_least8_t`, attribute is mandatory (otherwise compilation will fail)
`word` | `boost::uint_least16_t`, attribute is mandatory (otherwise compilation will fail)
`dword` | `boost::uint_least32_t`, attribute is mandatory (otherwise compilation will fail)
`qword` | `boost::uint_least64_t`, attribute is mandatory (otherwise compilation will fail)
`byte_(b)` | `unused`
`word(w)` | `unused`
`dword(dw)` | `unused`
`qword(qw)` | `unused`

| Note
In addition to their usual attribute of type `Attrib` all listed generators accept an instance of a `boost::optional<Attrib>` as well. If the `boost::optional<>` is initialized (holds a value) the generators behave as if their attribute was an instance of `Attrib` and emit the value stored in the `boost::optional<>`. Otherwise the generators will fail.

###### Complexity

> O(N), where N is the number of bytes emitted by the binary generator

###### Example

| Note
The test harness for the example(s) below is presented in the Basics Examples section.

Some includes:

    #include <boost/spirit/include/karma.hpp>
    #include <boost/spirit/include/phoenix_core.hpp>
    #include <boost/spirit/include/phoenix_operator.hpp>
    #include <boost/fusion/include/std_pair.hpp>
    #include <iostream>
    #include <string>

Some using declarations:

    using boost::spirit::karma::byte_;
    using boost::spirit::karma::word;
    using boost::spirit::karma::dword;
    using boost::spirit::karma::qword;

Basic usage of the native binary generators with some results for little endian platforms:

    test_binary_generator("\x01", 1, byte_(0x01));
    test_binary_generator("\x01\x02", 2, word(0x0201));
    test_binary_generator("\x01\x02\x03\x04", 4, dword(0x04030201));
    test_binary_generator("\x01\x02\x03\x04\x05\x06\x07\x08", 8, qword(0x0807060504030201LL));

    test_binary_generator_attr("\x01", 1, byte_, 0x01);
    test_binary_generator_attr("\x01\x02", 2, word, 0x0201);
    test_binary_generator_attr("\x01\x02\x03\x04", 4, dword, 0x04030201);
    test_binary_generator_attr("\x01\x02\x03\x04\x05\x06\x07\x08", 8, qword, 0x0807060504030201LL);

Basic usage of the native binary generators with some results for big endian platforms:

    test_binary_generator("\x01", 1, byte_(0x01));
    test_binary_generator("\x02\x01", 2, word(0x0201));
    test_binary_generator("\x04\x03\x02\x01", 4, dword(0x04030201));
    test_binary_generator("\x08\x07\x06\x05\x04\x03\x02\x01", 8, qword(0x0807060504030201LL));

    test_binary_generator_attr("\x01", 1, byte_, 0x01);
    test_binary_generator_attr("\x02\x01", 2, word, 0x0201);
    test_binary_generator_attr("\x04\x03\x02\x01", 4, dword, 0x04030201);
    test_binary_generator_attr("\x08\x07\x06\x05\x04\x03\x02\x01", 8, qword, 0x0807060504030201LL);