1 [/==============================================================================
2 Copyright (C) 2001-2011 Hartmut Kaiser
3 Copyright (C) 2001-2011 Joel de Guzman
5 Distributed under the Boost Software License, Version 1.0. (See accompanying
6 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7 ===============================================================================/]
9 [section:binary Binary Generators]
11 This module includes different generators allowing to output binary data.
12 It includes generators for default, little, and big endian binary output and
13 a `pad` generator allowing to control padding of the generated output
16 [heading Module Header]
18 // forwards to <boost/spirit/home/karma/binary.hpp>
19 #include <boost/spirit/include/karma_binary.hpp>
21 Also, see __include_structure__.
23 [/////////////////////////////////////////////////////////////////////////////]
24 [section:binary_native Binary Native Endianness Generators]
28 The binary native endianness generators described in this section are used to
29 emit binary byte streams laid out conforming to the native endianness (byte
30 order) of the target architecture.
34 // forwards to <boost/spirit/home/karma/binary.hpp>
35 #include <boost/spirit/include/karma_binary.hpp>
37 Also, see __include_structure__.
43 [[`boost::spirit::byte_ // alias: boost::spirit::karma::byte_` ]]
44 [[`boost::spirit::word // alias: boost::spirit::karma::word` ]]
45 [[`boost::spirit::dword // alias: boost::spirit::karma::dword` ]]
46 [[`boost::spirit::qword // alias: boost::spirit::karma::qword` ]]
47 [[`boost::spirit::bin_float // alias: boost::spirit::karma::bin_float` ]]
48 [[`boost::spirit::bin_double // alias: boost::spirit::karma::bin_double` ]]
51 [note The generators `qword` and `qword(qw)` are only available on
52 platforms where the preprocessor constant `BOOST_HAS_LONG_LONG` is
53 defined (i.e. on platforms having native support for `unsigned long long`
54 (64 bit) integer types).]
58 [:__primitive_generator_concept__]
60 [variablelist Notation
61 [[`b`] [A single byte (8 bit binary value) or a __karma_lazy_argument__
62 that evaluates to a single byte]]
63 [[`w`] [A 16 bit binary value or a __karma_lazy_argument__ that
64 evaluates to a 16 bit binary value. This value is always
65 interpreted using native endianness.]]
66 [[`dw`] [A 32 bit binary value or a __karma_lazy_argument__ that
67 evaluates to a 32 bit binary value. This value is always
68 interpreted using native endianness.]]
69 [[`qw`] [A 64 bit binary value or a __karma_lazy_argument__ that
70 evaluates to a 64 bit binary value. This value is always
71 interpreted using native endianness.]]
72 [[`f`] [A float binary value or a __karma_lazy_argument__ that
73 evaluates to a float binary value. This value is always
74 interpreted using native endianness.]]
75 [[`d`] [A double binary value or a __karma_lazy_argument__ that
76 evaluates to a double binary value. This value is always
77 interpreted using native endianness.]]
80 [heading Expression Semantics]
82 Semantics of an expression is defined only where it differs from, or is
83 not defined in __primitive_generator_concept__.
86 [[Expression] [Description]]
87 [[`byte_`] [Output the binary representation of the least
88 significant byte of the mandatory attribute. This
89 generator never fails (unless the underlying
90 output stream reports an error).]]
91 [[`word`] [Output the binary representation of the least
92 significant 16 bits of the mandatory attribute
93 in native endian representation. This generator
94 never fails (unless the underlying output stream
96 [[`dword`] [Output the binary representation of the least
97 significant 32 bits of the mandatory attribute
98 in native endian representation. This generator
99 never fails (unless the underlying output stream
101 [[`qword`] [Output the binary representation of the least
102 significant 64 bits of the mandatory attribute
103 in native endian representation. This generator
104 never fails (unless the underlying output stream
106 [[`bin_float`] [Output the binary representation of the mandatory
107 float attribute in native endian representation.
108 This generator never fails (unless the underlying
109 output stream reports an error).]]
110 [[`bin_double`] [Output the binary representation of the mandatory
111 double attribute in native endian representation.
112 This generator never fails (unless the underlying
113 output stream reports an error).]]
114 [[`byte_(b)`] [Output the binary representation of the least
115 significant byte of the immediate parameter. This
116 generator never fails (unless the underlying
117 output stream reports an error).]]
118 [[`word(w)`] [Output the binary representation of the least
119 significant 16 bits of the immediate parameter
120 in native endian representation. This generator
121 never fails (unless the underlying output stream
123 [[`dword(dw)`] [Output the binary representation of the least
124 significant 32 bits of the immediate parameter
125 in native endian representation. This generator
126 never fails (unless the underlying output stream
128 [[`qword(qw)`] [Output the binary representation of the least
129 significant 64 bits of the immediate parameter
130 in native endian representation. This generator
131 never fails (unless the underlying output stream
133 [[`bin_float(f)`] [Output the binary representation of the immediate
134 float parameter in native endian representation.
135 This generator never fails (unless the underlying
136 output stream reports an error).]]
137 [[`bin_double(d)`] [Output the binary representation of the immediate
138 double parameter in native endian representation.
139 This generator never fails (unless the underlying
140 output stream reports an error).]]
146 [[Expression] [Attribute]]
147 [[`byte_`] [`boost::uint_least8_t`, attribute is mandatory
148 (otherwise compilation will fail)]]
149 [[`word`] [`boost::uint_least16_t`, attribute is mandatory
150 (otherwise compilation will fail)]]
151 [[`dword`] [`boost::uint_least32_t`, attribute is mandatory
152 (otherwise compilation will fail)]]
153 [[`qword`] [`boost::uint_least64_t`, attribute is mandatory
154 (otherwise compilation will fail)]]
155 [[`bin_float`] [`float`, attribute is mandatory
156 (otherwise compilation will fail)]]
157 [[`bin_double`] [`double`, attribute is mandatory
158 (otherwise compilation will fail)]]
159 [[`byte_(b)`] [__unused__]]
160 [[`word(w)`] [__unused__]]
161 [[`dword(dw)`] [__unused__]]
162 [[`qword(qw)`] [__unused__]]
163 [[`bin_float(f)`] [__unused__]]
164 [[`bin_double(d)`] [__unused__]]
167 [note In addition to their usual attribute of type `Attrib` all listed generators
168 accept an instance of a `boost::optional<Attrib>` as well. If the
169 `boost::optional<>` is initialized (holds a value) the generators behave
170 as if their attribute was an instance of `Attrib` and emit the value stored
171 in the `boost::optional<>`. Otherwise the generators will fail.]
175 [:O(N), where N is the number of bytes emitted by the binary generator]
179 [note The test harness for the example(s) below is presented in the
180 __karma_basics_examples__ section.]
184 [reference_karma_includes]
186 Some using declarations:
188 [reference_karma_using_declarations_native_binary]
190 Basic usage of the native binary generators with some results for little endian
193 [reference_karma_native_binary_little]
195 Basic usage of the native binary generators with some results for big endian
198 [reference_karma_native_binary_big]
202 [/////////////////////////////////////////////////////////////////////////////]
203 [section:binary_little Binary Little Endianness Generators]
205 [heading Description]
207 The little native endianness generators described in this section are used to
208 emit binary byte streams laid out conforming to the little endianness byte
213 // forwards to <boost/spirit/home/karma/binary.hpp>
214 #include <boost/spirit/include/karma_binary.hpp>
216 Also, see __include_structure__.
222 [[`boost::spirit::little_word // alias: boost::spirit::karma::little_word` ]]
223 [[`boost::spirit::little_dword // alias: boost::spirit::karma::little_dword` ]]
224 [[`boost::spirit::little_qword // alias: boost::spirit::karma::little_qword` ]]
225 [[`boost::spirit::little_bin_float // alias: boost::spirit::karma::little_bin_float` ]]
226 [[`boost::spirit::little_bin_double // alias: boost::spirit::karma::little_bin_double` ]]
229 [note The generators `little_qword` and `little_qword(qw)` are only available on
230 platforms where the preprocessor constant `BOOST_HAS_LONG_LONG` is
231 defined (i.e. on platforms having native support for `unsigned long long`
232 (64 bit) integer types).]
236 [:__primitive_generator_concept__]
238 [variablelist Notation
239 [[`w`] [A 16 bit binary value or a __karma_lazy_argument__ that
240 evaluates to a 16 bit binary value. This value is always
241 interpreted using native endianness.]]
242 [[`dw`] [A 32 bit binary value or a __karma_lazy_argument__ that
243 evaluates to a 32 bit binary value. This value is always
244 interpreted using native endianness.]]
245 [[`qw`] [A 64 bit binary value or a __karma_lazy_argument__ that
246 evaluates to a 64 bit binary value. This value is always
247 interpreted using native endianness.]]
248 [[`f`] [A float binary value or a __karma_lazy_argument__ that
249 evaluates to a float binary value. This value is always
250 interpreted using native endianness.]]
251 [[`d`] [A double binary value or a __karma_lazy_argument__ that
252 evaluates to a double binary value. This value is always
253 interpreted using native endianness.]]
256 [heading Expression Semantics]
258 Semantics of an expression is defined only where it differs from, or is
259 not defined in __primitive_generator_concept__.
262 [[Expression] [Description]]
263 [[`little_word`] [Output the binary representation of the least
264 significant 16 bits of the mandatory attribute
265 in little endian representation. This generator
266 never fails (unless the underlying output stream
268 [[`little_dword`] [Output the binary representation of the least
269 significant 32 bits of the mandatory attribute
270 in little endian representation. This generator
271 never fails (unless the underlying output stream
273 [[`little_qword`] [Output the binary representation of the least
274 significant 64 bits of the mandatory attribute
275 in little endian representation. This generator
276 never fails (unless the underlying output stream
278 [[`little_bin_float`] [Output the binary representation of the mandatory
279 float attribute in little endian representation.
280 This generator never fails (unless the underlying
281 output stream reports an error).]]
282 [[`little_bin_double`] [Output the binary representation of the mandatory
283 double attribute in little endian representation.
284 This generator never fails (unless the underlying
285 output stream reports an error).]]
286 [[`little_word(w)`] [Output the binary representation of the least
287 significant 16 bits of the immediate parameter
288 in little endian representation. This generator
289 never fails (unless the underlying output stream
291 [[`little_dword(dw)`] [Output the binary representation of the least
292 significant 32 bits of the immediate parameter
293 in little endian representation. This generator
294 never fails (unless the underlying output stream
296 [[`little_qword(qw)`] [Output the binary representation of the least
297 significant 64 bits of the immediate parameter
298 in little endian representation. This generator
299 never fails (unless the underlying output stream
301 [[`little_bin_float(f)`] [Output the binary representation of the immediate
302 float parameter in little endian representation.
303 This generator never fails (unless the underlying
304 output stream reports an error).]]
305 [[`little_bin_double(d)`] [Output the binary representation of the immediate
306 double parameter in little endian representation.
307 This generator never fails (unless the underlying
308 output stream reports an error).]]
314 [[Expression] [Attribute]]
315 [[`little_word`] [`boost::uint_least16_t`, attribute is mandatory
316 (otherwise compilation will fail)]]
317 [[`little_dword`] [`boost::uint_least32_t`, attribute is mandatory
318 (otherwise compilation will fail)]]
319 [[`little_qword`] [`boost::uint_least64_t`, attribute is mandatory
320 (otherwise compilation will fail)]]
321 [[`little_bin_float`] [`float`, attribute is mandatory
322 (otherwise compilation will fail)]]
323 [[`little_bin_double`] [`double`, attribute is mandatory
324 (otherwise compilation will fail)]]
325 [[`little_word(w)`] [__unused__]]
326 [[`little_dword(dw)`] [__unused__]]
327 [[`little_qword(qw)`] [__unused__]]
328 [[`little_bin_float(f)`] [__unused__]]
329 [[`little_bin_double(d)`] [__unused__]]
334 [:O(N), where N is the number of bytes emitted by the binary generator]
338 [note The test harness for the example(s) below is presented in the
339 __karma_basics_examples__ section.]
343 [reference_karma_includes]
345 Some using declarations:
347 [reference_karma_using_declarations_little_binary]
349 Basic usage of the little binary generators:
351 [reference_karma_little_binary]
355 [/////////////////////////////////////////////////////////////////////////////]
356 [section:binary_big Binary Big Endianness Generators]
358 [heading Description]
360 The big native endianness generators described in this section are used to
361 emit binary byte streams laid out conforming to the big endianness byte
366 // forwards to <boost/spirit/home/karma/binary.hpp>
367 #include <boost/spirit/include/karma_binary.hpp>
369 Also, see __include_structure__.
375 [[`boost::spirit::big_word // alias: boost::spirit::karma::big_word` ]]
376 [[`boost::spirit::big_dword // alias: boost::spirit::karma::big_dword` ]]
377 [[`boost::spirit::big_qword // alias: boost::spirit::karma::big_qword` ]]
378 [[`boost::spirit::big_bin_float // alias: boost::spirit::karma::big_bin_float` ]]
379 [[`boost::spirit::big_bin_double // alias: boost::spirit::karma::big_bin_double` ]]
382 [note The generators `big_qword` and `big_qword(qw)` are only available on
383 platforms where the preprocessor constant `BOOST_HAS_LONG_LONG` is
384 defined (i.e. on platforms having native support for `unsigned long long`
385 (64 bit) integer types).]
389 [:__primitive_generator_concept__]
391 [variablelist Notation
392 [[`w`] [A 16 bit binary value or a __karma_lazy_argument__ that
393 evaluates to a 16 bit binary value. This value is always
394 interpreted using native endianness.]]
395 [[`dw`] [A 32 bit binary value or a __karma_lazy_argument__ that
396 evaluates to a 32 bit binary value. This value is always
397 interpreted using native endianness.]]
398 [[`qw`] [A 64 bit binary value or a __karma_lazy_argument__ that
399 evaluates to a 64 bit binary value. This value is always
400 interpreted using native endianness.]]
401 [[`f`] [A float binary value or a __karma_lazy_argument__ that
402 evaluates to a float binary value. This value is always
403 interpreted using native endianness.]]
404 [[`d`] [A double binary value or a __karma_lazy_argument__ that
405 evaluates to a double binary value. This value is always
406 interpreted using native endianness.]]
409 [heading Expression Semantics]
411 Semantics of an expression is defined only where it differs from, or is
412 not defined in __primitive_generator_concept__.
415 [[Expression] [Description]]
416 [[`big_word`] [Output the binary representation of the least
417 significant 16 bits of the mandatory attribute
418 in big endian representation. This generator
419 never fails (unless the underlying output stream
421 [[`big_dword`] [Output the binary representation of the least
422 significant 32 bits of the mandatory attribute
423 in big endian representation. This generator
424 never fails (unless the underlying output stream
426 [[`big_qword`] [Output the binary representation of the least
427 significant 64 bits of the mandatory attribute
428 in big endian representation. This generator
429 never fails (unless the underlying output stream
431 [[`big_bin_float`] [Output the binary representation of the mandatory
432 float attribute in big endian representation.
433 This generator never fails (unless the underlying
434 output stream reports an error).]]
435 [[`big_bin_double`] [Output the binary representation of the mandatory
436 double attribute in big endian representation.
437 This generator never fails (unless the underlying
438 output stream reports an error).]]
439 [[`big_word(w)`] [Output the binary representation of the least
440 significant 16 bits of the immediate parameter
441 in big endian representation. This generator
442 never fails (unless the underlying output stream
444 [[`big_dword(dw)`] [Output the binary representation of the least
445 significant 32 bits of the immediate parameter
446 in big endian representation. This generator
447 never fails (unless the underlying output stream
449 [[`big_qword(qw)`] [Output the binary representation of the least
450 significant 64 bits of the immediate parameter
451 in big endian representation. This generator
452 never fails (unless the underlying output stream
454 [[`big_bin_float(f)`] [Output the binary representation of the immediate
455 float parameter in big endian representation.
456 This generator never fails (unless the underlying
457 output stream reports an error).]]
458 [[`big_bin_double(d)`] [Output the binary representation of the immediate
459 double parameter in big endian representation.
460 This generator never fails (unless the underlying
461 output stream reports an error).]]
467 [[Expression] [Attribute]]
468 [[`big_word`] [`boost::uint_least16_t`, attribute is mandatory
469 (otherwise compilation will fail)]]
470 [[`big_dword`] [`boost::uint_least32_t`, attribute is mandatory
471 (otherwise compilation will fail)]]
472 [[`big_qword`] [`boost::uint_least64_t`, attribute is mandatory
473 (otherwise compilation will fail)]]
474 [[`big_bin_float`] [`float`, attribute is mandatory
475 (otherwise compilation will fail)]]
476 [[`big_bin_double`] [`double`, attribute is mandatory
477 (otherwise compilation will fail)]]
478 [[`big_word(w)`] [__unused__]]
479 [[`big_dword(dw)`] [__unused__]]
480 [[`big_qword(qw)`] [__unused__]]
481 [[`big_bin_float(f)`] [__unused__]]
482 [[`big_bin_double(d)`] [__unused__]]
487 [:O(N), where N is the number of bytes emitted by the binary generator]
491 [note The test harness for the example(s) below is presented in the
492 __karma_basics_examples__ section.]
496 [reference_karma_includes]
498 Some using declarations:
500 [reference_karma_using_declarations_big_binary]
502 Basic usage of the big binary generators:
504 [reference_karma_big_binary]