[/============================================================================== Copyright (C) 2001-2011 Hartmut Kaiser Copyright (C) 2001-2011 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 Generators] 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 #include 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 #include 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` ]] [[`boost::spirit::bin_float // alias: boost::spirit::karma::bin_float` ]] [[`boost::spirit::bin_double // alias: boost::spirit::karma::bin_double` ]] ] [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.]] [[`f`] [A float binary value or a __karma_lazy_argument__ that evaluates to a float binary value. This value is always interpreted using native endianness.]] [[`d`] [A double binary value or a __karma_lazy_argument__ that evaluates to a double 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).]] [[`bin_float`] [Output the binary representation of the mandatory float attribute in native endian representation. This generator never fails (unless the underlying output stream reports an error).]] [[`bin_double`] [Output the binary representation of the mandatory double 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).]] [[`bin_float(f)`] [Output the binary representation of the immediate float parameter in native endian representation. This generator never fails (unless the underlying output stream reports an error).]] [[`bin_double(d)`] [Output the binary representation of the immediate double 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)]] [[`bin_float`] [`float`, attribute is mandatory (otherwise compilation will fail)]] [[`bin_double`] [`double`, attribute is mandatory (otherwise compilation will fail)]] [[`byte_(b)`] [__unused__]] [[`word(w)`] [__unused__]] [[`dword(dw)`] [__unused__]] [[`qword(qw)`] [__unused__]] [[`bin_float(f)`] [__unused__]] [[`bin_double(d)`] [__unused__]] ] [note In addition to their usual attribute of type `Attrib` all listed generators accept an instance of a `boost::optional` 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 #include 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` ]] [[`boost::spirit::little_bin_float // alias: boost::spirit::karma::little_bin_float` ]] [[`boost::spirit::little_bin_double // alias: boost::spirit::karma::little_bin_double` ]] ] [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.]] [[`f`] [A float binary value or a __karma_lazy_argument__ that evaluates to a float binary value. This value is always interpreted using native endianness.]] [[`d`] [A double binary value or a __karma_lazy_argument__ that evaluates to a double 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_bin_float`] [Output the binary representation of the mandatory float attribute in little endian representation. This generator never fails (unless the underlying output stream reports an error).]] [[`little_bin_double`] [Output the binary representation of the mandatory double 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).]] [[`little_bin_float(f)`] [Output the binary representation of the immediate float parameter in little endian representation. This generator never fails (unless the underlying output stream reports an error).]] [[`little_bin_double(d)`] [Output the binary representation of the immediate double 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_bin_float`] [`float`, attribute is mandatory (otherwise compilation will fail)]] [[`little_bin_double`] [`double`, attribute is mandatory (otherwise compilation will fail)]] [[`little_word(w)`] [__unused__]] [[`little_dword(dw)`] [__unused__]] [[`little_qword(qw)`] [__unused__]] [[`little_bin_float(f)`] [__unused__]] [[`little_bin_double(d)`] [__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 #include 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` ]] [[`boost::spirit::big_bin_float // alias: boost::spirit::karma::big_bin_float` ]] [[`boost::spirit::big_bin_double // alias: boost::spirit::karma::big_bin_double` ]] ] [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.]] [[`f`] [A float binary value or a __karma_lazy_argument__ that evaluates to a float binary value. This value is always interpreted using native endianness.]] [[`d`] [A double binary value or a __karma_lazy_argument__ that evaluates to a double 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_bin_float`] [Output the binary representation of the mandatory float attribute in big endian representation. This generator never fails (unless the underlying output stream reports an error).]] [[`big_bin_double`] [Output the binary representation of the mandatory double 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).]] [[`big_bin_float(f)`] [Output the binary representation of the immediate float parameter in big endian representation. This generator never fails (unless the underlying output stream reports an error).]] [[`big_bin_double(d)`] [Output the binary representation of the immediate double 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_bin_float`] [`float`, attribute is mandatory (otherwise compilation will fail)]] [[`big_bin_double`] [`double`, attribute is mandatory (otherwise compilation will fail)]] [[`big_word(w)`] [__unused__]] [[`big_dword(dw)`] [__unused__]] [[`big_qword(qw)`] [__unused__]] [[`big_bin_float(f)`] [__unused__]] [[`big_bin_double(d)`] [__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]