]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/============================================================================== |
2 | Copyright (C) 2001-2011 Hartmut Kaiser | |
3 | Copyright (C) 2001-2011 Joel de Guzman | |
4 | ||
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 | ===============================================================================/] | |
8 | ||
9 | [section:binary Binary Generators] | |
10 | ||
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 | |
14 | stream. | |
15 | ||
16 | [heading Module Header] | |
17 | ||
18 | // forwards to <boost/spirit/home/karma/binary.hpp> | |
19 | #include <boost/spirit/include/karma_binary.hpp> | |
20 | ||
21 | Also, see __include_structure__. | |
22 | ||
23 | [/////////////////////////////////////////////////////////////////////////////] | |
24 | [section:binary_native Binary Native Endianness Generators] | |
25 | ||
26 | [heading Description] | |
27 | ||
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. | |
31 | ||
32 | [heading Header] | |
33 | ||
34 | // forwards to <boost/spirit/home/karma/binary.hpp> | |
35 | #include <boost/spirit/include/karma_binary.hpp> | |
36 | ||
37 | Also, see __include_structure__. | |
38 | ||
39 | [heading Namespace] | |
40 | ||
41 | [table | |
42 | [[Name]] | |
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` ]] | |
49 | ] | |
50 | ||
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).] | |
55 | ||
56 | [heading Model of] | |
57 | ||
58 | [:__primitive_generator_concept__] | |
59 | ||
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.]] | |
78 | ] | |
79 | ||
80 | [heading Expression Semantics] | |
81 | ||
82 | Semantics of an expression is defined only where it differs from, or is | |
83 | not defined in __primitive_generator_concept__. | |
84 | ||
85 | [table | |
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 | |
95 | reports an error).]] | |
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 | |
100 | reports an error).]] | |
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 | |
105 | reports an error).]] | |
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 | |
122 | reports an error).]] | |
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 | |
127 | reports an error).]] | |
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 | |
132 | reports an error).]] | |
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).]] | |
141 | ] | |
142 | ||
143 | [heading Attributes] | |
144 | ||
145 | [table | |
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__]] | |
165 | ] | |
166 | ||
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.] | |
172 | ||
173 | [heading Complexity] | |
174 | ||
175 | [:O(N), where N is the number of bytes emitted by the binary generator] | |
176 | ||
177 | [heading Example] | |
178 | ||
179 | [note The test harness for the example(s) below is presented in the | |
180 | __karma_basics_examples__ section.] | |
181 | ||
182 | Some includes: | |
183 | ||
184 | [reference_karma_includes] | |
185 | ||
186 | Some using declarations: | |
187 | ||
188 | [reference_karma_using_declarations_native_binary] | |
189 | ||
190 | Basic usage of the native binary generators with some results for little endian | |
191 | platforms: | |
192 | ||
193 | [reference_karma_native_binary_little] | |
194 | ||
195 | Basic usage of the native binary generators with some results for big endian | |
196 | platforms: | |
197 | ||
198 | [reference_karma_native_binary_big] | |
199 | ||
200 | [endsect] | |
201 | ||
202 | [/////////////////////////////////////////////////////////////////////////////] | |
203 | [section:binary_little Binary Little Endianness Generators] | |
204 | ||
205 | [heading Description] | |
206 | ||
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 | |
209 | order. | |
210 | ||
211 | [heading Header] | |
212 | ||
213 | // forwards to <boost/spirit/home/karma/binary.hpp> | |
214 | #include <boost/spirit/include/karma_binary.hpp> | |
215 | ||
216 | Also, see __include_structure__. | |
217 | ||
218 | [heading Namespace] | |
219 | ||
220 | [table | |
221 | [[Name]] | |
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` ]] | |
227 | ] | |
228 | ||
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).] | |
233 | ||
234 | [heading Model of] | |
235 | ||
236 | [:__primitive_generator_concept__] | |
237 | ||
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.]] | |
254 | ] | |
255 | ||
256 | [heading Expression Semantics] | |
257 | ||
258 | Semantics of an expression is defined only where it differs from, or is | |
259 | not defined in __primitive_generator_concept__. | |
260 | ||
261 | [table | |
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 | |
267 | reports an error).]] | |
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 | |
272 | reports an error).]] | |
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 | |
277 | reports an error).]] | |
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 | |
290 | reports an error).]] | |
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 | |
295 | reports an error).]] | |
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 | |
300 | reports an error).]] | |
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).]] | |
309 | ] | |
310 | ||
311 | [heading Attributes] | |
312 | ||
313 | [table | |
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__]] | |
330 | ] | |
331 | ||
332 | [heading Complexity] | |
333 | ||
334 | [:O(N), where N is the number of bytes emitted by the binary generator] | |
335 | ||
336 | [heading Example] | |
337 | ||
338 | [note The test harness for the example(s) below is presented in the | |
339 | __karma_basics_examples__ section.] | |
340 | ||
341 | Some includes: | |
342 | ||
343 | [reference_karma_includes] | |
344 | ||
345 | Some using declarations: | |
346 | ||
347 | [reference_karma_using_declarations_little_binary] | |
348 | ||
349 | Basic usage of the little binary generators: | |
350 | ||
351 | [reference_karma_little_binary] | |
352 | ||
353 | [endsect] | |
354 | ||
355 | [/////////////////////////////////////////////////////////////////////////////] | |
356 | [section:binary_big Binary Big Endianness Generators] | |
357 | ||
358 | [heading Description] | |
359 | ||
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 | |
362 | order. | |
363 | ||
364 | [heading Header] | |
365 | ||
366 | // forwards to <boost/spirit/home/karma/binary.hpp> | |
367 | #include <boost/spirit/include/karma_binary.hpp> | |
368 | ||
369 | Also, see __include_structure__. | |
370 | ||
371 | [heading Namespace] | |
372 | ||
373 | [table | |
374 | [[Name]] | |
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` ]] | |
380 | ] | |
381 | ||
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).] | |
386 | ||
387 | [heading Model of] | |
388 | ||
389 | [:__primitive_generator_concept__] | |
390 | ||
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.]] | |
407 | ] | |
408 | ||
409 | [heading Expression Semantics] | |
410 | ||
411 | Semantics of an expression is defined only where it differs from, or is | |
412 | not defined in __primitive_generator_concept__. | |
413 | ||
414 | [table | |
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 | |
420 | reports an error).]] | |
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 | |
425 | reports an error).]] | |
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 | |
430 | reports an error).]] | |
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 | |
443 | reports an error).]] | |
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 | |
448 | reports an error).]] | |
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 | |
453 | reports an error).]] | |
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).]] | |
462 | ] | |
463 | ||
464 | [heading Attributes] | |
465 | ||
466 | [table | |
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__]] | |
483 | ] | |
484 | ||
485 | [heading Complexity] | |
486 | ||
487 | [:O(N), where N is the number of bytes emitted by the binary generator] | |
488 | ||
489 | [heading Example] | |
490 | ||
491 | [note The test harness for the example(s) below is presented in the | |
492 | __karma_basics_examples__ section.] | |
493 | ||
494 | Some includes: | |
495 | ||
496 | [reference_karma_includes] | |
497 | ||
498 | Some using declarations: | |
499 | ||
500 | [reference_karma_using_declarations_big_binary] | |
501 | ||
502 | Basic usage of the big binary generators: | |
503 | ||
504 | [reference_karma_big_binary] | |
505 | ||
506 | [endsect] | |
507 | ||
508 | [endsect] |