ceph/src/boost/libs/spirit/doc/karma/binary.qbk

   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]