| Home | Libraries | People | FAQ | More

##### Binary Native Endianness Parsers

###### Description

Binary native endian parsers are designed to parse binary byte streams that are laid out in the native endianness of the target architecture.

###### Header

    // forwards to <boost/spirit/home/qi/binary.hpp>
    #include <boost/spirit/include/qi_binary.hpp>

Also, see Include Structure.

###### Namespace

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

| Note
`qword` is 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

> `PrimitiveParser`

Notation

`b`

  A single byte (8 bit binary value) or a Lazy Argument that evaluates to a single byte. This value is always in native endian.

`w`

  A 16 bit binary value or a Lazy Argument that evaluates to a 16 bit binary value. This value is always in native endian.

`dw`

  A 32 bit binary value or a Lazy Argument that evaluates to a 32 bit binary value. This value is always in native endian.

`qw`

  A 64 bit binary value or a Lazy Argument that evaluates to a 64 bit binary value. This value is always in native endian.

###### Expression Semantics

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

Expression | Description
--- | ---
`byte_` | Matches any 8 bit native endian binary.
`word` | Matches any 16 bit native endian binary.
`dword` | Matches any 32 bit native endian binary.
`qword` | Matches any 64 bit native endian binary.
`byte_(b)` | Matches an exact 8 bit native endian binary.
`word(w)` | Matches an exact 16 bit native endian binary.
`dword(dw)` | Matches an exact 32 bit native endian binary.
`qword(qw)` | Matches an exact 64 bit native endian binary.

###### Attributes

Expression | Attribute
--- | ---
`byte_` | `boost::uint_least8_t`
`word` | `boost::uint_least16_t`
`dword` | `boost::uint_least32_t`
`qword` | `boost::uint_least64_t`
`byte_(b)` | `unused`
`word(w)` | `unused`
`dword(dw)` | `unused`
`qword(qw)` | `unused`

###### Complexity

> O(N), where N is the number of bytes parsed

###### Example

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

Using declarations and variables:

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

    boost::uint8_t uc;
    boost::uint16_t us;
    boost::uint32_t ui;
    boost::uint64_t ul;

Basic usage of the native binary parsers for little endian platforms:

    test_parser_attr("\x01", byte_, uc); assert(uc == 0x01);
    test_parser_attr("\x01\x02", word, us); assert(us == 0x0201);
    test_parser_attr("\x01\x02\x03\x04", dword, ui); assert(ui == 0x04030201);
    test_parser_attr("\x01\x02\x03\x04\x05\x06\x07\x08", qword, ul);
    assert(ul == 0x0807060504030201LL);

    test_parser("\x01", byte_(0x01));
    test_parser("\x01\x02", word(0x0201));
    test_parser("\x01\x02\x03\x04", dword(0x04030201));
    test_parser("\x01\x02\x03\x04\x05\x06\x07\x08",
        qword(0x0807060504030201LL));

Basic usage of the native binary parsers for big endian platforms:

    test_parser_attr("\x01", byte_, uc); assert(uc == 0x01);
    test_parser_attr("\x01\x02", word, us); assert(us ==  0x0102);
    test_parser_attr("\x01\x02\x03\x04", dword, ui); assert(ui == 0x01020304);
    test_parser_attr("\x01\x02\x03\x04\x05\x06\x07\x08", qword, ul);
    assert(0x0102030405060708LL);

    test_parser("\x01", byte_(0x01));
    test_parser("\x01\x02", word(0x0102));
    test_parser("\x01\x02\x03\x04", dword(0x01020304));
    test_parser("\x01\x02\x03\x04\x05\x06\x07\x08",
        qword(0x0102030405060708LL));