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 11This module includes different generators allowing to output binary data. 12It includes generators for default, little, and big endian binary output and 13a `pad` generator allowing to control padding of the generated output 14stream. 15 16[heading Module Header] 17 18 // forwards to <boost/spirit/home/karma/binary.hpp> 19 #include <boost/spirit/include/karma_binary.hpp> 20 21Also, see __include_structure__. 22 23[/////////////////////////////////////////////////////////////////////////////] 24[section:binary_native Binary Native Endianness Generators] 25 26[heading Description] 27 28The binary native endianness generators described in this section are used to 29emit binary byte streams laid out conforming to the native endianness (byte 30order) 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 37Also, 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 82Semantics of an expression is defined only where it differs from, or is 83not 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 182Some includes: 183 184[reference_karma_includes] 185 186Some using declarations: 187 188[reference_karma_using_declarations_native_binary] 189 190Basic usage of the native binary generators with some results for little endian 191platforms: 192 193[reference_karma_native_binary_little] 194 195Basic usage of the native binary generators with some results for big endian 196platforms: 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 207The little native endianness generators described in this section are used to 208emit binary byte streams laid out conforming to the little endianness byte 209order. 210 211[heading Header] 212 213 // forwards to <boost/spirit/home/karma/binary.hpp> 214 #include <boost/spirit/include/karma_binary.hpp> 215 216Also, 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 258Semantics of an expression is defined only where it differs from, or is 259not 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 341Some includes: 342 343[reference_karma_includes] 344 345Some using declarations: 346 347[reference_karma_using_declarations_little_binary] 348 349Basic 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 360The big native endianness generators described in this section are used to 361emit binary byte streams laid out conforming to the big endianness byte 362order. 363 364[heading Header] 365 366 // forwards to <boost/spirit/home/karma/binary.hpp> 367 #include <boost/spirit/include/karma_binary.hpp> 368 369Also, 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 411Semantics of an expression is defined only where it differs from, or is 412not 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 494Some includes: 495 496[reference_karma_includes] 497 498Some using declarations: 499 500[reference_karma_using_declarations_big_binary] 501 502Basic usage of the big binary generators: 503 504[reference_karma_big_binary] 505 506[endsect] 507 508[endsect] 509