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
11This module includes different parsers for parsing binary data in
12various __endianness__. It includes parsers for default (native),
13little, 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
20Also, see __include_structure__.
21
22[/////////////////////////////////////////////////////////////////////////////]
23[section:binary_native Binary Native Endianness Parsers]
24
25[heading Description]
26
27Binary native endian parsers are designed to parse binary byte streams
28that are laid out in the native __endianness__ of the target
29architecture.
30
31[heading Header]
32
33    // forwards to <boost/spirit/home/qi/binary.hpp>
34    #include <boost/spirit/include/qi_binary.hpp>
35
36Also, 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
51constant `BOOST_HAS_LONG_LONG` is defined (i.e. on platforms having
52native 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
81Semantics of an expression is defined only where it differs from, or is
82not 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
136Binary little endian parsers are designed to parse binary byte streams
137that 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
144Also, 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
158preprocessor constant `BOOST_HAS_LONG_LONG` is defined (i.e. on
159platforms having native support for `unsigned long long` (64 bit)
160integer 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
186Semantics of an expression is defined only where it differs from, or is
187not 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
237Binary big endian parsers are designed to parse binary byte streams that
238are 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
245Also, 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
259preprocessor constant `BOOST_HAS_LONG_LONG` is defined (i.e. on
260platforms having native support for `unsigned long long` (64 bit)
261integer 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
287Semantics of an expression is defined only where it differs from, or is
288not 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]
334