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

    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 generators allowing to output binary data. 
It includes generators for default, little, and big endian binary output and 
a `pad` generator allowing to control padding of the generated output 
stream.

[heading Module Header]

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

Also, see __include_structure__.

[/////////////////////////////////////////////////////////////////////////////]
[section:binary_native Binary Native Endianness Generators]

[heading 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.

[heading Header]

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

Also, see __include_structure__.

[heading Namespace]

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

[heading Model of]

[:__primitive_generator_concept__]

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

[heading Expression Semantics]

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

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

[heading Attributes]

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

[heading Complexity]

[:O(N), where N is the number of bytes emitted by the binary generator]

[heading Example]

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

Some includes:

[reference_karma_includes]

Some using declarations:

[reference_karma_using_declarations_native_binary]

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

[reference_karma_native_binary_little]

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

[reference_karma_native_binary_big]

[endsect]

[/////////////////////////////////////////////////////////////////////////////]
[section:binary_little Binary Little Endianness Generators]

[heading Description]

The little native endianness generators described in this section are used to
emit binary byte streams laid out conforming to the little endianness byte 
order.

[heading Header]

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

Also, see __include_structure__.

[heading Namespace]

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

[note   The generators `little_qword` and `little_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).]

[heading Model of]

[:__primitive_generator_concept__]

[variablelist Notation
    [[`w`]    [A 16 bit binary value or a __karma_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 __karma_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 __karma_lazy_argument__ that 
               evaluates to a 64 bit binary value. This value is always 
               interpreted using native endianness.]]
]

[heading Expression Semantics]

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

[table
    [[Expression]           [Description]]
    [[`little_word`]        [Output the binary representation of the least
                             significant 16 bits of the mandatory attribute
                             in little endian representation. This generator 
                             never fails (unless the underlying output stream 
                             reports an error).]]
    [[`little_dword`]       [Output the binary representation of the least
                             significant 32 bits of the mandatory attribute
                             in little endian representation. This generator 
                             never fails (unless the underlying output stream 
                             reports an error).]]
    [[`little_qword`]       [Output the binary representation of the least
                             significant 64 bits of the mandatory attribute
                             in little endian representation. This generator 
                             never fails (unless the underlying output stream 
                             reports an error).]]
    [[`little_word(w)`]     [Output the binary representation of the least
                             significant 16 bits of the immediate parameter
                             in little endian representation. This generator 
                             never fails (unless the underlying output stream 
                             reports an error).]]
    [[`little_dword(dw)`]   [Output the binary representation of the least
                             significant 32 bits of the immediate parameter
                             in little endian representation. This generator 
                             never fails (unless the underlying output stream 
                             reports an error).]]
    [[`little_qword(qw)`]   [Output the binary representation of the least
                             significant 64 bits of the immediate parameter
                             in little endian representation. This generator 
                             never fails (unless the underlying output stream 
                             reports an error).]]
]

[heading Attributes]

[table
    [[Expression]           [Attribute]]
    [[`little_word`]        [`boost::uint_least16_t`, attribute is mandatory 
                             (otherwise compilation will fail)]]
    [[`little_dword`]       [`boost::uint_least32_t`, attribute is mandatory 
                             (otherwise compilation will fail)]]
    [[`little_qword`]       [`boost::uint_least64_t`, attribute is mandatory 
                             (otherwise compilation will fail)]]
    [[`little_word(w)`]     [__unused__]]
    [[`little_dword(dw)`]   [__unused__]]
    [[`little_qword(qw)`]   [__unused__]]
]

[heading Complexity]

[:O(N), where N is the number of bytes emitted by the binary generator]

[heading Example]

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

Some includes:

[reference_karma_includes]

Some using declarations:

[reference_karma_using_declarations_little_binary]

Basic usage of the little binary generators:

[reference_karma_little_binary]

[endsect]

[/////////////////////////////////////////////////////////////////////////////]
[section:binary_big Binary Big Endianness Generators]

[heading Description]

The big native endianness generators described in this section are used to
emit binary byte streams laid out conforming to the big endianness byte 
order.

[heading Header]

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

Also, see __include_structure__.

[heading Namespace]

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

[note   The generators `big_qword` and `big_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).]

[heading Model of]

[:__primitive_generator_concept__]

[variablelist Notation
    [[`w`]    [A 16 bit binary value or a __karma_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 __karma_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 __karma_lazy_argument__ that 
               evaluates to a 64 bit binary value. This value is always 
               interpreted using native endianness.]]
]

[heading Expression Semantics]

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

[table
    [[Expression]           [Description]]
    [[`big_word`]           [Output the binary representation of the least
                             significant 16 bits of the mandatory attribute
                             in big endian representation. This generator 
                             never fails (unless the underlying output stream 
                             reports an error).]]
    [[`big_dword`]          [Output the binary representation of the least
                             significant 32 bits of the mandatory attribute
                             in big endian representation. This generator 
                             never fails (unless the underlying output stream 
                             reports an error).]]
    [[`big_qword`]          [Output the binary representation of the least
                             significant 64 bits of the mandatory attribute
                             in big endian representation. This generator 
                             never fails (unless the underlying output stream 
                             reports an error).]]
    [[`big_word(w)`]        [Output the binary representation of the least
                             significant 16 bits of the immediate parameter
                             in big endian representation. This generator 
                             never fails (unless the underlying output stream 
                             reports an error).]]
    [[`big_dword(dw)`]      [Output the binary representation of the least
                             significant 32 bits of the immediate parameter
                             in big endian representation. This generator 
                             never fails (unless the underlying output stream 
                             reports an error).]]
    [[`big_qword(qw)`]      [Output the binary representation of the least
                             significant 64 bits of the immediate parameter
                             in big endian representation. This generator 
                             never fails (unless the underlying output stream 
                             reports an error).]]
]

[heading Attributes]

[table
    [[Expression]           [Attribute]]
    [[`big_word`]           [`boost::uint_least16_t`, attribute is mandatory 
                             (otherwise compilation will fail)]]
    [[`big_dword`]          [`boost::uint_least32_t`, attribute is mandatory 
                             (otherwise compilation will fail)]]
    [[`big_qword`]          [`boost::uint_least64_t`, attribute is mandatory 
                             (otherwise compilation will fail)]]
    [[`big_word(w)`]        [__unused__]]
    [[`big_dword(dw)`]      [__unused__]]
    [[`big_qword(qw)`]      [__unused__]]
]

[heading Complexity]

[:O(N), where N is the number of bytes emitted by the binary generator]

[heading Example]

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

Some includes:

[reference_karma_includes]

Some using declarations:

[reference_karma_using_declarations_big_binary]

Basic usage of the big binary generators:

[reference_karma_big_binary]

[endsect]

[endsect]