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

   1 [/==============================================================================
   2     Copyright (C) 2001-2011 Joel de Guzman
   3     Copyright (C) 2001-2011 Hartmut Kaiser
   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 Parsers]
  10
  11 This module includes different parsers for parsing binary data in
  12 various __endianness__. It includes parsers for default (native),
  13 little, and big endian binary input.
  14
  15 [heading Module Header]
  16
  17     // forwards to <boost/spirit/home/qi/binary.hpp>
  18     #include <boost/spirit/include/qi_binary.hpp>
  19
  20 Also, see __include_structure__.
  21
  22 [/////////////////////////////////////////////////////////////////////////////]
  23 [section:binary_native Binary Native Endianness Parsers]
  24
  25 [heading Description]
  26
  27 Binary native endian parsers are designed to parse binary byte streams
  28 that are laid out in the native __endianness__ of the target
  29 architecture.
  30
  31 [heading Header]
  32
  33     // forwards to <boost/spirit/home/qi/binary.hpp>
  34     #include <boost/spirit/include/qi_binary.hpp>
  35
  36 Also, see __include_structure__.
  37
  38 [heading Namespace]
  39
  40 [table
  41     [[Name]]
  42     [[`boost::spirit::byte_     // alias: boost::spirit::qi::byte_`]]
  43     [[`boost::spirit::word      // alias: boost::spirit::qi::word`]]
  44     [[`boost::spirit::dword     // alias: boost::spirit::qi::dword`]]
  45     [[`boost::spirit::qword     // alias: boost::spirit::qi::qword`]]
  46     [[`boost::spirit::bin_float     // alias: boost::spirit::qi::bin_float`]]
  47     [[`boost::spirit::bin_double     // alias: boost::spirit::qi::bin_double`]]
  48 ]
  49
  50 [note `qword` is only available on platforms where the preprocessor
  51 constant `BOOST_HAS_LONG_LONG` is defined (i.e. on platforms having
  52 native support for `unsigned long long` (64 bit) integer types).]
  53
  54 [heading Model of]
  55
  56 [:__primitive_parser_concept__]
  57
  58 [variablelist Notation
  59     [[`b`]    [A single byte (8 bit binary value) or a __qi_lazy_argument__
  60                that evaluates to a single byte. This value is always
  61                in native endian.]]
  62     [[`w`]    [A 16 bit binary value or a __qi_lazy_argument__ that
  63                evaluates to a 16 bit binary value. This value is always
  64                in native endian.]]
  65     [[`dw`]   [A 32 bit binary value or a __qi_lazy_argument__ that
  66                evaluates to a 32 bit binary value. This value is always
  67                in native endian.]]
  68     [[`qw`]   [A 64 bit binary value or a __qi_lazy_argument__ that
  69                evaluates to a 64 bit binary value. This value is always
  70                in native endian.]]
  71     [[`f`]    [A float binary value or a __qi_lazy_argument__ that
  72                evaluates to a float binary value. This value is always
  73                in native endian.]]
  74     [[`d`]    [A double binary value or a __qi_lazy_argument__ that
  75                evaluates to a double binary value. This value is always
  76                in native endian.]]
  77 ]
  78
  79 [heading Expression Semantics]
  80
  81 Semantics of an expression is defined only where it differs from, or is
  82 not defined in __primitive_parser_concept__.
  83
  84 [table
  85     [[Expression]           [Description]]
  86     [[`byte_`]              [Matches any 8 bit native endian binary.]]
  87     [[`word`]               [Matches any 16 bit native endian binary.]]
  88     [[`dword`]              [Matches any 32 bit native endian binary.]]
  89     [[`qword`]              [Matches any 64 bit native endian binary.]]
  90     [[`bin_float`]          [Matches any float native endian binary.]]
  91     [[`bin_double`]         [Matches any double native endian binary.]]
  92     [[`byte_(b)`]           [Matches an exact 8 bit native endian binary.]]
  93     [[`word(w)`]            [Matches an exact 16 bit native endian binary.]]
  94     [[`dword(dw)`]          [Matches an exact 32 bit native endian binary.]]
  95     [[`qword(qw)`]          [Matches an exact 64 bit native endian binary.]]
  96     [[`bin_float(f)`]       [Matches an exact float native endian binary.]]
  97     [[`bin_double(d)`]      [Matches an exact double native endian binary.]]
  98 ]
  99
 100 [heading Attributes]
 101
 102 [table
 103     [[Expression]           [Attribute]]
 104     [[`byte_`]              [`boost::uint_least8_t`]]
 105     [[`word`]               [`boost::uint_least16_t`]]
 106     [[`dword`]              [`boost::uint_least32_t`]]
 107     [[`qword`]              [`boost::uint_least64_t`]]
 108     [[`bin_float`]          [`float`]]
 109     [[`bin_double`]         [`double`]]
 110     [[`byte_(b)`]           [__unused__]]
 111     [[`word(w)`]            [__unused__]]
 112     [[`dword(dw)`]          [__unused__]]
 113     [[`qword(qw)`]          [__unused__]]
 114     [[`bin_float(f)`]       [__unused__]]
 115     [[`bin_double(d)`]      [__unused__]]
 116 ]
 117
 118 [heading Complexity]
 119
 120 [:O(N), where N is the number of bytes parsed]
 121
 122 [heading Example]
 123
 124 [note The test harness for the example(s) below is presented in the
 125 __qi_basics_examples__ section.]
 126
 127 [reference_qi_native_binary]
 128
 129 [endsect]
 130
 131 [/////////////////////////////////////////////////////////////////////////////]
 132 [section:binary_little Binary Little Endianness Parser]
 133
 134 [heading Description]
 135
 136 Binary little endian parsers are designed to parse binary byte streams
 137 that are laid out in little endian.
 138
 139 [heading Header]
 140
 141     // forwards to <boost/spirit/home/qi/binary.hpp>
 142     #include <boost/spirit/include/qi_binary.hpp>
 143
 144 Also, see __include_structure__.
 145
 146 [heading Namespace]
 147
 148 [table
 149     [[Name]]
 150     [[`boost::spirit::little_word        // alias: boost::spirit::qi::little_word` ]]
 151     [[`boost::spirit::little_dword       // alias: boost::spirit::qi::little_dword` ]]
 152     [[`boost::spirit::little_qword       // alias: boost::spirit::qi::little_qword` ]]
 153     [[`boost::spirit::little_bin_float   // alias: boost::spirit::qi::little_bin_float` ]]
 154     [[`boost::spirit::little_bin_double  // alias: boost::spirit::qi::little_bin_double` ]]
 155 ]
 156
 157 [note `little_qword` is only available on platforms where the
 158 preprocessor constant `BOOST_HAS_LONG_LONG` is defined (i.e. on
 159 platforms having native support for `unsigned long long` (64 bit)
 160 integer types).]
 161
 162 [heading Model of]
 163
 164 [:__primitive_parser_concept__]
 165
 166 [variablelist Notation
 167     [[`w`]    [A 16 bit binary value or a __qi_lazy_argument__ that
 168                evaluates to a 16 bit binary value. This value is always
 169                in native endian.]]
 170     [[`dw`]   [A 32 bit binary value or a __qi_lazy_argument__ that
 171                evaluates to a 32 bit binary value. This value is always
 172                in native endian.]]
 173     [[`qw`]   [A 64 bit binary value or a __qi_lazy_argument__ that
 174                evaluates to a 64 bit binary value. This value is always
 175                in native endian.]]
 176     [[`f`]    [A float binary value or a __qi_lazy_argument__ that
 177                evaluates to a float binary value. This value is always
 178                in native endian.]]
 179     [[`d`]    [A double binary value or a __qi_lazy_argument__ that
 180                evaluates to a double binary value. This value is always
 181                in native endian.]]
 182 ]
 183
 184 [heading Expression Semantics]
 185
 186 Semantics of an expression is defined only where it differs from, or is
 187 not defined in __primitive_parser_concept__.
 188
 189 [table
 190     [[Expression]              [Description]]
 191     [[`little_word`]           [Matches any 16 bit little endian binary.]]
 192     [[`little_dword`]          [Matches any 32 bit little endian binary.]]
 193     [[`little_qword`]          [Matches any 64 bit little endian binary.]]
 194     [[`little_bin_float`]      [Matches any float little endian binary.]]
 195     [[`little_bin_double`]     [Matches any double little endian binary.]]
 196     [[`little_word(w)`]        [Matches an exact 16 bit little endian binary.]]
 197     [[`little_dword(dw)`]      [Matches an exact 32 bit little endian binary.]]
 198     [[`little_qword(qw)`]      [Matches an exact 32 bit little endian binary.]]
 199     [[`little_bin_float(f)`]   [Matches an exact float little endian binary.]]
 200     [[`little_bin_double(d)`]  [Matches an exact double little endian binary.]]
 201 ]
 202
 203 [heading Attributes]
 204
 205 [table
 206     [[Expression]              [Attribute]]
 207     [[`little_word`]           [`boost::uint_least16_t`]]
 208     [[`little_dword`]          [`boost::uint_least32_t`]]
 209     [[`little_qword`]          [`boost::uint_least64_t`]]
 210     [[`little_bin_float`]      [`float`]]
 211     [[`little_bin_double`]     [`double`]]
 212     [[`little_word(w)`]        [__unused__]]
 213     [[`little_dword(dw)`]      [__unused__]]
 214     [[`little_qword(qw)`]      [__unused__]]
 215     [[`little_bin_float(f)`]   [__unused__]]
 216     [[`little_bin_double(d)`]  [__unused__]]
 217 ]
 218
 219 [heading Complexity]
 220
 221 [:O(N), where N is the number of bytes parsed]
 222
 223 [heading Example]
 224
 225 [note The test harness for the example(s) below is presented in the
 226 __qi_basics_examples__ section.]
 227
 228 [reference_qi_little_binary]
 229
 230 [endsect]
 231
 232 [/////////////////////////////////////////////////////////////////////////////]
 233 [section:binary_big Binary Big Endianness Parsers]
 234
 235 [heading Description]
 236
 237 Binary big endian parsers are designed to parse binary byte streams that
 238 are laid out in big endian.
 239
 240 [heading Header]
 241
 242     // forwards to <boost/spirit/home/qi/binary.hpp>
 243     #include <boost/spirit/include/qi_binary.hpp>
 244
 245 Also, see __include_structure__.
 246
 247 [heading Namespace]
 248
 249 [table
 250     [[Name]]
 251     [[`boost::spirit::big_word         // alias: boost::spirit::qi::big_word` ]]
 252     [[`boost::spirit::big_dword        // alias: boost::spirit::qi::big_dword` ]]
 253     [[`boost::spirit::big_qword        // alias: boost::spirit::qi::big_qword` ]]
 254     [[`boost::spirit::big_bin_float    // alias: boost::spirit::qi::big_bin_float` ]]
 255     [[`boost::spirit::big_bin_double   // alias: boost::spirit::qi::big_bin_double` ]]
 256 ]
 257
 258 [note `big_qword` is only available on platforms where the
 259 preprocessor constant `BOOST_HAS_LONG_LONG` is defined (i.e. on
 260 platforms having native support for `unsigned long long` (64 bit)
 261 integer types).]
 262
 263 [heading Model of]
 264
 265 [:__primitive_parser_concept__]
 266
 267 [variablelist Notation
 268     [[`w`]      [A 16 bit binary value or a __qi_lazy_argument__ that
 269                 evaluates to a 16 bit binary value. This value is always
 270                 in native endian.]]
 271     [[`dw`]     [A 32 bit binary value or a __qi_lazy_argument__ that
 272                 evaluates to a 32 bit binary value. This value is always
 273                 in native endian.]]
 274     [[`qw`]     [A 64 bit binary value or a __qi_lazy_argument__ that
 275                 evaluates to a 64 bit binary value. This value is always
 276                 in native endian.]]
 277     [[`f`]      [A float binary value or a __qi_lazy_argument__ that
 278                 evaluates to a float binary value. This value is always
 279                 in native endian.]]
 280     [[`d`]      [A double binary value or a __qi_lazy_argument__ that
 281                 evaluates to a double binary value. This value is always
 282                 in native endian.]]
 283 ]
 284
 285 [heading Expression Semantics]
 286
 287 Semantics of an expression is defined only where it differs from, or is
 288 not defined in __primitive_parser_concept__.
 289
 290 [table
 291     [[Expression]           [Description]]
 292     [[`big_word`]           [Matches any 16 bit big endian binary.]]
 293     [[`big_dword`]          [Matches any 32 bit big endian binary.]]
 294     [[`big_qword`]          [Matches any 64 bit big endian binary.]]
 295     [[`big_bin_float`]      [Matches any float big endian binary.]]
 296     [[`big_bin_double`]     [Matches any double big endian binary.]]
 297     [[`big_word(w)`]        [Matches an exact 16 bit big endian binary.]]
 298     [[`big_dword(dw)`]      [Matches an exact 32 bit big endian binary.]]
 299     [[`big_qword(qw)`]      [Matches an exact 32 bit big endian binary.]]
 300     [[`big_bin_float(f)`]   [Matches an exact float big endian binary.]]
 301     [[`big_bin_double(d)`]  [Matches an exact double big endian binary.]]
 302 ]
 303
 304 [heading Attributes]
 305
 306 [table
 307     [[Expression]           [Attribute]]
 308     [[`big_word`]           [`boost::uint_least16_t`]]
 309     [[`big_dword`]          [`boost::uint_least32_t`]]
 310     [[`big_qword`]          [`boost::uint_least64_t`]]
 311     [[`big_bin_float`]      [`float`]]
 312     [[`big_bin_double`]     [`double`]]
 313     [[`big_word(w)`]        [__unused__]]
 314     [[`big_dword(dw)`]      [__unused__]]
 315     [[`big_qword(qw)`]      [__unused__]]
 316     [[`big_bin_float(f)`]   [__unused__]]
 317     [[`big_bin_double(d)`]  [__unused__]]
 318 ]
 319
 320 [heading Complexity]
 321
 322 [:O(N), where N is the number of bytes parsed]
 323
 324 [heading Example]
 325
 326 [note The test harness for the example(s) below is presented in the
 327 __qi_basics_examples__ section.]
 328
 329 [reference_qi_big_binary]
 330
 331 [endsect]
 332
 333 [endsect]