123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508 |
- [/==============================================================================
- 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 <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` ]]
- [[`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<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` ]]
- [[`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 <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` ]]
- [[`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]
|