[/==============================================================================
    Copyright (C) 2001-2010 Joel de Guzman
    Copyright (C) 2001-2010 Hartmut Kaiser

    Distributed under the Boost Software License, Version 1.0. (See accompanying
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
===============================================================================/]

[section:binary Binary]

This module includes different parsers for parsing binary data in
various __endianness__. It includes parsers for default (native),
little, and big endian binary input.

[heading Module Header]

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

Also, see __include_structure__.

[/////////////////////////////////////////////////////////////////////////////]
[section:binary_native Binary Native Endian]

[heading Description]

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

[heading Header]

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

Also, see __include_structure__.

[heading Namespace]

[table
    [[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).] 

[heading Model of]

[:__primitive_parser_concept__]

[variablelist Notation
    [[`b`]    [A single byte (8 bit binary value) or a __qi_lazy_argument__ 
               that evaluates to a single byte. This value is always 
               in native endian.]]
    [[`w`]    [A 16 bit binary value or a __qi_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 __qi_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 __qi_lazy_argument__ that 
               evaluates to a 64 bit binary value. This value is always 
               in native endian.]]
]

[heading Expression Semantics]

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

[table
    [[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.]]
]

[heading Attributes]

[table
    [[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__]]
]

[heading Complexity]

[:O(N), where N is the number of bytes parsed]

[heading Example]

[note The test harness for the example(s) below is presented in the
__qi_basics_examples__ section.]

[reference_qi_native_binary]

[endsect]

[/////////////////////////////////////////////////////////////////////////////]
[section:binary_little Binary Little Endian]

[heading Description]

Binary little endian parsers are designed to parse binary byte streams
that are laid out in little endian.

[heading Header]

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

Also, see __include_structure__.

[heading Namespace]

[table
    [[Name]]
    [[`boost::spirit::little_word   // alias: boost::spirit::qi::little_word` ]]
    [[`boost::spirit::little_dword  // alias: boost::spirit::qi::little_dword` ]]
    [[`boost::spirit::little_qword  // alias: boost::spirit::qi::little_qword` ]]
]

[note `little_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).] 

[heading Model of]

[:__primitive_parser_concept__]

[variablelist Notation
    [[`w`]    [A 16 bit binary value or a __qi_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 __qi_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 __qi_lazy_argument__ that 
               evaluates to a 64 bit binary value. This value is always 
               in native endian.]]
]

[heading Expression Semantics]

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

[table
    [[Expression]           [Description]]
    [[`little_word`]        [Matches any 16 bit little endian binary.]]
    [[`little_dword`]       [Matches any 32 bit little endian binary.]]
    [[`little_qword`]       [Matches any 64 bit little endian binary.]]
    [[`little_word(w)`]     [Matches an exact 16 bit little endian binary.]]
    [[`little_dword(dw)`]   [Matches an exact 32 bit little endian binary.]]
    [[`little_qword(qw)`]   [Matches an exact 32 bit little endian binary.]]
]

[heading Attributes]

[table
    [[Expression]           [Attribute]]
    [[`little_word`]        [`boost::uint_least16_t`]]
    [[`little_dword`]       [`boost::uint_least32_t`]]
    [[`little_qword`]       [`boost::uint_least64_t`]]
    [[`little_word(w)`]     [__unused__]]
    [[`little_dword(dw)`]   [__unused__]]
    [[`little_qword(qw)`]   [__unused__]]
]

[heading Complexity]

[:O(N), where N is the number of bytes parsed]

[heading Example]

[note The test harness for the example(s) below is presented in the
__qi_basics_examples__ section.]

[reference_qi_little_binary]

[endsect]

[/////////////////////////////////////////////////////////////////////////////]
[section:binary_big Binary Big Endian]

[heading Description]

Binary big endian parsers are designed to parse binary byte streams that
are laid out in big endian.

[heading Header]

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

Also, see __include_structure__.

[heading Namespace]

[table
    [[Name]]
    [[`boost::spirit::big_word      // alias: boost::spirit::qi::big_word` ]]
    [[`boost::spirit::big_dword     // alias: boost::spirit::qi::big_dword` ]]
    [[`boost::spirit::big_qword     // alias: boost::spirit::qi::big_qword` ]]
]

[note `big_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).] 

[heading Model of]

[:__primitive_parser_concept__]

[variablelist Notation
    [[`w`]      [A 16 bit binary value or a __qi_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 __qi_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 __qi_lazy_argument__ that 
                evaluates to a 64 bit binary value. This value is always 
                in native endian.]]
]

[heading Expression Semantics]

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

[table
    [[Expression]           [Description]]
    [[`big_word`]           [Matches any 16 bit big endian binary.]]
    [[`big_dword`]          [Matches any 32 bit big endian binary.]]
    [[`big_qword`]          [Matches any 64 bit big endian binary.]]
    [[`big_word(w)`]        [Matches an exact 16 bit big endian binary.]]
    [[`big_dword(dw)`]      [Matches an exact 32 bit big endian binary.]]
    [[`big_qword(qw)`]      [Matches an exact 32 bit big endian binary.]]
]

[heading Attributes]

[table
    [[Expression]           [Attribute]]
    [[`big_word`]           [`boost::uint_least16_t`]]
    [[`big_dword`]          [`boost::uint_least32_t`]]
    [[`big_qword`]          [`boost::uint_least64_t`]]
    [[`big_word(w)`]        [__unused__]]
    [[`big_dword(dw)`]      [__unused__]]
    [[`big_qword(qw)`]      [__unused__]]
]

[heading Complexity]

[:O(N), where N is the number of bytes parsed]

[heading Example]

[note The test harness for the example(s) below is presented in the
__qi_basics_examples__ section.]

[reference_qi_big_binary]

[endsect]

[endsect]