]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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:numeric Numeric Parsers] | |
10 | ||
11 | The library includes a couple of predefined objects for parsing signed | |
12 | and unsigned integers and real numbers. These parsers are fully | |
13 | parametric. Most of the important aspects of numeric parsing can be | |
14 | finely adjusted to suit. This includes the radix base, the minimum and | |
15 | maximum number of allowable digits, the exponent, the fraction etc. | |
16 | Policies control the real number parsers' behavior. There are some | |
17 | predefined policies covering the most common real number formats but the | |
18 | user can supply her own when needed. | |
19 | ||
20 | The numeric parsers are fine tuned (employing loop unrolling and | |
21 | extensive template metaprogramming) with exceptional performance that | |
22 | rivals the low level C functions such as `atof`, `strtod`, `atol`, | |
23 | `strtol`. Benchmarks reveal up to 4X speed over the C counterparts. This | |
24 | goes to show that you can write extremely tight generic C++ code that | |
25 | rivals, if not surpasses C. | |
26 | ||
27 | [heading Module Header] | |
28 | ||
29 | // forwards to <boost/spirit/home/qi/numeric.hpp> | |
30 | #include <boost/spirit/include/qi_numeric.hpp> | |
31 | ||
32 | Also, see __include_structure__. | |
33 | ||
34 | [/------------------------------------------------------------------------------] | |
35 | [section:uint Unsigned Integer Parsers (`uint_`, etc.)] | |
36 | ||
37 | [heading Description] | |
38 | ||
39 | The `uint_parser` class is the simplest among the members of the | |
40 | numerics package. The `uint_parser` can parse unsigned integers of | |
41 | arbitrary length and size. The `uint_parser` parser can be used to parse | |
42 | ordinary primitive C/C++ integers or even user defined scalars such as | |
43 | bigints (unlimited precision integers) as long as the type follows | |
44 | certain expression requirements (documented below). The `uint_parser` is | |
45 | a template class. Template parameters fine tune its behavior. | |
46 | ||
47 | [heading Header] | |
48 | ||
49 | // forwards to <boost/spirit/home/qi/numeric/uint.hpp> | |
50 | #include <boost/spirit/include/qi_uint.hpp> | |
51 | ||
52 | Also, see __include_structure__. | |
53 | ||
54 | [heading Namespace] | |
55 | ||
56 | [table | |
57 | [[Name]] | |
58 | [[`boost::spirit::lit // alias: boost::spirit::qi::lit`]] | |
59 | [[`boost::spirit::bin // alias: boost::spirit::qi::bin`]] | |
60 | [[`boost::spirit::oct // alias: boost::spirit::qi::oct`]] | |
61 | [[`boost::spirit::hex // alias: boost::spirit::qi::hex`]] | |
62 | [[`boost::spirit::ushort_ // alias: boost::spirit::qi::ushort_`]] | |
63 | [[`boost::spirit::ulong_ // alias: boost::spirit::qi::ulong_`]] | |
64 | [[`boost::spirit::uint_ // alias: boost::spirit::qi::uint_`]] | |
65 | [[`boost::spirit::ulong_long // alias: boost::spirit::qi::ulong_long`]] | |
66 | ] | |
67 | ||
68 | [note `ulong_long` is only available on platforms where the preprocessor | |
69 | constant `BOOST_HAS_LONG_LONG` is defined (i.e. on platforms having | |
70 | native support for `unsigned long long` (64 bit) unsigned integer | |
71 | types).] | |
72 | ||
73 | [note `lit` is reused by the [qi_lit_char Character Parsers], and the Numeric | |
74 | Parsers. In general, a char parser is created when you pass in a | |
75 | character, and a numeric parser is created when you use a numeric | |
76 | literal.] | |
77 | ||
78 | [heading Synopsis] | |
79 | ||
80 | template < | |
81 | typename T | |
82 | , unsigned Radix | |
83 | , unsigned MinDigits | |
84 | , int MaxDigits> | |
85 | struct uint_parser; | |
86 | ||
87 | [heading Template parameters] | |
88 | ||
89 | [table | |
90 | [[Parameter] [Description] [Default]] | |
91 | [[`T`] [The numeric base type of the | |
92 | numeric parser.] [none]] | |
93 | [[`Radix`] [The radix base. This can be | |
94 | any base from 2..10 and 16] [10]] | |
95 | [[`MinDigits`] [The minimum number of digits | |
96 | allowable.] [1]] | |
97 | [[`MaxDigits`] [The maximum number of digits | |
98 | allowable. If this is -1, then the | |
99 | maximum limit becomes unbounded.] [-1]] | |
100 | ] | |
101 | ||
102 | [heading Model of] | |
103 | ||
104 | [:__primitive_parser_concept__] | |
105 | ||
106 | [variablelist Notation | |
107 | [[`n`] [An object of `T`, the numeric base type.]] | |
108 | [[`num`] [Numeric literal, any unsigned integer value, or a | |
109 | __qi_lazy_argument__ that evaluates to a unsigned integer | |
110 | value.]] | |
111 | ] | |
112 | ||
113 | [heading Expression Semantics] | |
114 | ||
115 | Semantics of an expression is defined only where it differs from, or is | |
116 | not defined in __primitive_parser_concept__. | |
117 | ||
118 | [table | |
119 | [ | |
120 | [Expression] | |
121 | [Semantics] | |
122 | ][ | |
123 | [`` | |
124 | ushort_ | |
125 | uint_ | |
126 | ulong_ | |
127 | ulong_long | |
128 | ``] | |
129 | [Parse an unsigned integer using the default radix (10).] | |
130 | ][ | |
131 | [`` | |
132 | lit(num) | |
133 | ushort_(num) | |
134 | uint_(num) | |
135 | ulong_(num) | |
136 | ulong_long(num) | |
137 | ``] | |
138 | [Match the literal `num` using the default radix (10). The parser will fail | |
139 | if the parsed value is not equal to the specified value.] | |
140 | ][ | |
141 | [`` | |
142 | bin | |
143 | oct | |
144 | hex | |
145 | ``] | |
146 | [Parse an unsigned integer using radix 2 for `bin`, radix 8 for `oct`, and | |
147 | radix 16 for `hex`.] | |
148 | ][ | |
149 | [`` | |
150 | bin(num) | |
151 | oct(num) | |
152 | hex(num) | |
153 | ``] | |
154 | [Match the literal `num` using radix 2 for `bin`, radix 8 for `oct`, and | |
155 | radix 16 for `hex`. The parser will fail | |
156 | if the parsed value is not equal to the specified value.] | |
157 | ][ | |
158 | [`` | |
159 | uint_parser< | |
160 | T, Radix, MinDigits, MaxDigits | |
161 | >() | |
162 | ``] | |
163 | [Parse an unsigned integer of type `T` using radix `Radix`, with | |
164 | a minimum of `MinDigits` and a maximum of `MaxDigits`.] | |
165 | ][ | |
166 | [`` | |
167 | uint_parser< | |
168 | T, Radix, MinDigits, MaxDigits | |
169 | >()(num) | |
170 | ``] | |
171 | [Match the literal `num` of type `T` using radix `Radix`, with | |
172 | a minimum of `MinDigits` and a maximum of `MaxDigits`. The parser will fail | |
173 | if the parsed value is not equal to the specified value.] | |
174 | ] | |
175 | ] | |
176 | ||
177 | [important All numeric parsers check for overflow conditions based on the type | |
178 | `T` the corresponding `uint_parser<>` has been instantiated with. If the | |
179 | parsed number overflows this type the parsing fails. Please be aware | |
180 | that the overflow check is not based on the type of the supplied | |
181 | attribute but solely depends on the template parameter `T`.] | |
182 | ||
183 | [heading Attributes] | |
184 | ||
185 | [table | |
186 | [ | |
187 | [Expression] | |
188 | [Attribute] | |
189 | ][ | |
190 | [`` | |
191 | lit(num) | |
192 | ``] | |
193 | [__unused__] | |
194 | ][ | |
195 | [`` | |
196 | ushort_ | |
197 | ushort_(num) | |
198 | ``] | |
199 | [`unsigned short`] | |
200 | ][ | |
201 | [`` | |
202 | uint_ | |
203 | uint_(num) | |
204 | bin | |
205 | bin(num) | |
206 | oct | |
207 | oct(num) | |
208 | hex | |
209 | hex(num) | |
210 | ``] | |
211 | [`unsigned int`] | |
212 | ][ | |
213 | [`` | |
214 | ulong_ | |
215 | ulong_(num) | |
216 | ``] | |
217 | [`unsigned long`] | |
218 | ][ | |
219 | [`` | |
220 | ulong_long | |
221 | ulong_long(num) | |
222 | ``] | |
223 | [`boost::ulong_long_type`] | |
224 | ][ | |
225 | [`` | |
226 | uint_parser< | |
227 | T, Radix, MinDigits, MaxDigits | |
228 | >() | |
229 | uint_parser< | |
230 | T, Radix, MinDigits, MaxDigits | |
231 | >()(num) | |
232 | ``] | |
233 | [`T`] | |
234 | ] | |
235 | ] | |
236 | ||
237 | [heading Complexity] | |
238 | ||
239 | [:O(N), where N is the number of digits being parsed.] | |
240 | ||
241 | [heading Minimum Expression Requirements for `T`] | |
242 | ||
243 | For the numeric base type, `T`, the expression requirements below must be | |
244 | valid: | |
245 | ||
246 | [table | |
247 | [[Expression] [Semantics]] | |
248 | [[`T()`] [Default construct.]] | |
249 | [[`T(0)`] [Construct from an `int`.]] | |
250 | [[`n + n`] [Addition.]] | |
251 | [[`n * n`] [Multiplication.]] | |
252 | [[`std::numeric_limits<T>::is_bounded`] [`true` or `false` if `T` bounded.]] | |
253 | [[`std::numeric_limits<T>::digits`] [Maximum Digits for `T`, radix digits. | |
254 | Required only if `T` is bounded.]] | |
255 | [[`std::numeric_limits<T>::digits10`] [Maximum Digits for `T`, base 10. | |
256 | Required only if `T` is bounded.]] | |
257 | [[`std::numeric_limits<T>::max()`] [Maximum value for `T`. | |
258 | Required only if `T` is bounded.]] | |
259 | [[`std::numeric_limits<T>::min()`] [Minimum value for `T`. | |
260 | Required only if `T` is bounded.]] | |
261 | ] | |
262 | ||
263 | [heading Example] | |
264 | ||
265 | [note The test harness for the example(s) below is presented in the | |
266 | __qi_basics_examples__ section.] | |
267 | ||
268 | Some using declarations: | |
269 | ||
270 | [reference_using_declarations_uint] | |
271 | ||
272 | Basic unsigned integers: | |
273 | ||
274 | [reference_uint] | |
275 | ||
276 | [reference_thousand_separated] | |
277 | ||
278 | [endsect] [/ Unsigned Integers] | |
279 | ||
280 | [/------------------------------------------------------------------------------] | |
281 | [section:int Signed Integer Parsers (`int_`, etc.)] | |
282 | ||
283 | [heading Description] | |
284 | ||
285 | The `int_parser` can parse signed integers of arbitrary length and size. | |
286 | This is almost the same as the `uint_parser`. The only difference is the | |
287 | additional task of parsing the `'+'` or `'-'` sign preceding the number. | |
288 | The class interface is the same as that of the `uint_parser`. | |
289 | ||
290 | The `int_parser` parser can be used to parse ordinary primitive C/C++ | |
291 | integers or even user defined scalars such as bigints (unlimited | |
292 | precision integers) as long as the type follows certain expression | |
293 | requirements (documented below). | |
294 | ||
295 | [heading Header] | |
296 | ||
297 | // forwards to <boost/spirit/home/qi/numeric/int.hpp> | |
298 | #include <boost/spirit/include/qi_int.hpp> | |
299 | ||
300 | Also, see __include_structure__. | |
301 | ||
302 | [heading Namespace] | |
303 | ||
304 | [table | |
305 | [[Name]] | |
306 | [[`boost::spirit::lit // alias: boost::spirit::qi::lit`]] | |
307 | [[`boost::spirit::short_ // alias: boost::spirit::qi::short_`]] | |
308 | [[`boost::spirit::int_ // alias: boost::spirit::qi::int_`]] | |
309 | [[`boost::spirit::long_ // alias: boost::spirit::qi::long_`]] | |
310 | [[`boost::spirit::long_long // alias: boost::spirit::qi::long_long`]] | |
311 | ] | |
312 | ||
313 | [note `long_long` is only available on platforms where the preprocessor | |
314 | constant `BOOST_HAS_LONG_LONG` is defined (i.e. on platforms having | |
315 | native support for `signed long long` (64 bit) unsigned integer types).] | |
316 | ||
317 | [note `lit` is reused by the [qi_lit_char Character Parsers], and the Numeric | |
318 | Parsers. In general, a char parser is created when you pass in a | |
319 | character, and a numeric parser is created when you use a numeric | |
320 | literal.] | |
321 | ||
322 | [heading Synopsis] | |
323 | ||
324 | template < | |
325 | typename T | |
326 | , unsigned Radix | |
327 | , unsigned MinDigits | |
328 | , int MaxDigits> | |
329 | struct int_parser; | |
330 | ||
331 | [heading Template parameters] | |
332 | ||
333 | [table | |
334 | [[Parameter] [Description] [Default]] | |
335 | [[`T`] [The numeric base type of the | |
336 | numeric parser.] [none]] | |
337 | [[`Radix`] [The radix base. This can be | |
338 | any base from 2..10 and 16] [10]] | |
339 | [[`MinDigits`] [The minimum number of digits | |
340 | allowable.] [1]] | |
341 | [[`MaxDigits`] [The maximum number of digits | |
342 | allowable. If this is -1, then the | |
343 | maximum limit becomes unbounded.] [-1]] | |
344 | ] | |
345 | ||
346 | [heading Model of] | |
347 | ||
348 | [:__primitive_parser_concept__] | |
349 | ||
350 | [variablelist Notation | |
351 | [[`n`] [An object of `T`, the numeric base type.]] | |
352 | [[`num`] [Numeric literal, any signed integer value, or a | |
353 | __qi_lazy_argument__ that evaluates to a signed integer | |
354 | value.]] | |
355 | ] | |
356 | ||
357 | [heading Expression Semantics] | |
358 | ||
359 | Semantics of an expression is defined only where it differs from, or is | |
360 | not defined in __primitive_parser_concept__. | |
361 | ||
362 | [table | |
363 | [ | |
364 | [Expression] | |
365 | [Semantics] | |
366 | ][ | |
367 | [`` | |
368 | short_ | |
369 | int_ | |
370 | long_ | |
371 | long_long | |
372 | ``] | |
373 | [Parse a signed integer using the default radix (10).] | |
374 | ][ | |
375 | [`` | |
376 | lit(num) | |
377 | short_(num) | |
378 | int_(num) | |
379 | long_(num) | |
380 | long_long(num) | |
381 | ``] | |
382 | [Match the literal `num` using the default radix (10). The parser will fail | |
383 | if the parsed value is not equal to the specified value.] | |
384 | ][ | |
385 | [`` | |
386 | int_parser< | |
387 | T, Radix, MinDigits, MaxDigits | |
388 | >() | |
389 | ``] | |
390 | [Parse a signed integer of type `T` using radix `Radix`, with | |
391 | a minimum of `MinDigits` and a maximum of `MaxDigits`.] | |
392 | ][ | |
393 | [`` | |
394 | int_parser< | |
395 | T, Radix, MinDigits, MaxDigits | |
396 | >()(num) | |
397 | ``] | |
398 | [Match the literal `num` of type `T` using radix `Radix`, with | |
399 | a minimum of `MinDigits` and a maximum of `MaxDigits`. The parser will fail | |
400 | if the parsed value is not equal to the specified value.] | |
401 | ] | |
402 | ] | |
403 | ||
404 | [important All numeric parsers check for overflow conditions based on the type `T` | |
405 | the corresponding `int_parser<>` has been instantiated with. If the | |
406 | parsed number overflows this type the parsing fails. Please be aware | |
407 | that the overflow check is not based on the type of the supplied | |
408 | attribute but solely depends on the template parameter `T`.] | |
409 | ||
410 | [heading Attributes] | |
411 | ||
412 | [table | |
413 | [ | |
414 | [Expression] | |
415 | [Attribute] | |
416 | ][ | |
417 | [`` | |
418 | lit(num) | |
419 | ``] | |
420 | [__unused__] | |
421 | ][ | |
422 | [`` | |
423 | short_ | |
424 | short_(num) | |
425 | ``] | |
426 | [`short`] | |
427 | ][ | |
428 | [`` | |
429 | int_ | |
430 | int_(num) | |
431 | ``] | |
432 | [`int`] | |
433 | ][ | |
434 | [`` | |
435 | long_ | |
436 | long_(num) | |
437 | ``] | |
438 | [`long`] | |
439 | ][ | |
440 | [`` | |
441 | long_long | |
442 | long_long(num) | |
443 | ``] | |
444 | [`boost::long_long_type`] | |
445 | ][ | |
446 | [`` | |
447 | int_parser< | |
448 | T, Radix, MinDigits, MaxDigits | |
449 | >() | |
450 | int_parser< | |
451 | T, Radix, MinDigits, MaxDigits | |
452 | >()(num) | |
453 | ``] | |
454 | [`T`] | |
455 | ] | |
456 | ] | |
457 | ||
458 | [heading Complexity] | |
459 | ||
460 | [:O(N), where N is the number of digits being parsed plus the sign.] | |
461 | ||
462 | [heading Minimum Expression Requirements for `T`] | |
463 | ||
464 | For the numeric base type, `T`, the expression requirements below must be | |
465 | valid: | |
466 | ||
467 | [table | |
468 | [[Expression] [Semantics]] | |
469 | [[`T()`] [Default construct.]] | |
470 | [[`T(0)`] [Construct from an `int`.]] | |
471 | [[`n + n`] [Addition.]] | |
472 | [[`n - n`] [Subtraction.]] | |
473 | [[`n * n`] [Multiplication.]] | |
474 | [[`std::numeric_limits<T>::is_bounded`] [`true` or `false` if `T` bounded.]] | |
475 | [[`std::numeric_limits<T>::digits`] [Maximum Digits for `T`, radix digits. | |
476 | Required only if `T` is bounded.]] | |
477 | [[`std::numeric_limits<T>::digits10`] [Maximum Digits for `T`, base 10. | |
478 | Required only if `T` is bounded.]] | |
479 | [[`std::numeric_limits<T>::max()`] [Maximum value for `T`. | |
480 | Required only if `T` is bounded.]] | |
481 | [[`std::numeric_limits<T>::min()`] [Minimum value for `T`. | |
482 | Required only if `T` is bounded.]] | |
483 | ] | |
484 | ||
485 | [heading Example] | |
486 | ||
487 | [note The test harness for the example(s) below is presented in the | |
488 | __qi_basics_examples__ section.] | |
489 | ||
490 | Some using declarations: | |
491 | ||
492 | [reference_using_declarations_int] | |
493 | ||
494 | Basic signed integers: | |
495 | ||
496 | [reference_int] | |
497 | ||
498 | [endsect] [/ Signed Integers] | |
499 | ||
500 | [/------------------------------------------------------------------------------] | |
501 | [section:real Real Number Parsers (`float_`, `double_`, etc.)] | |
502 | ||
503 | [heading Description] | |
504 | ||
505 | The `real_parser` can parse real numbers of arbitrary length and size | |
506 | limited by its template parameter, `T`. The numeric base type `T` can be | |
507 | a user defined numeric type such as fixed_point (fixed point reals) and | |
508 | bignum (unlimited precision numbers) as long as the type follows certain | |
509 | expression requirements (documented below). | |
510 | ||
511 | [heading Header] | |
512 | ||
513 | // forwards to <boost/spirit/home/qi/numeric/real.hpp> | |
514 | #include <boost/spirit/include/qi_real.hpp> | |
515 | ||
516 | Also, see __include_structure__. | |
517 | ||
518 | [heading Namespace] | |
519 | ||
520 | [table | |
521 | [[Name]] | |
522 | [[`boost::spirit::lit // alias: boost::spirit::qi::lit`]] | |
523 | [[`boost::spirit::float_ // alias: boost::spirit::qi::float_`]] | |
524 | [[`boost::spirit::double_ // alias: boost::spirit::qi::double_`]] | |
525 | [[`boost::spirit::long_double // alias: boost::spirit::qi::long_double`]] | |
526 | ] | |
527 | ||
528 | [note `lit` is reused by the [qi_lit_char Character Parsers], and the Numeric | |
529 | Parsers. In general, a char parser is created when you pass in a | |
530 | character, and a numeric parser is created when you use a numeric | |
531 | literal.] | |
532 | ||
533 | [heading Synopsis] | |
534 | ||
535 | template <typename T, typename RealPolicies> | |
536 | struct real_parser; | |
537 | ||
538 | [heading Template parameters] | |
539 | ||
540 | [table | |
541 | [[Parameter] [Description] [Default]] | |
542 | [[`T`] [The numeric base type of the | |
543 | numeric parser.] [none]] | |
544 | [[`RealPolicies`] [Policies control the | |
545 | parser's behavior.] [`real_policies<T>`]] | |
546 | ] | |
547 | ||
548 | [heading Model of] | |
549 | ||
550 | [:__primitive_parser_concept__] | |
551 | ||
552 | [variablelist Notation | |
553 | [[`n`] [An object of `T`, the numeric base type.]] | |
554 | [[`num`] [Numeric literal, any real value, or a __qi_lazy_argument__ | |
555 | that evaluates to a real value.]] | |
556 | [[`RP`] [A `RealPolicies` (type).]] | |
557 | [[`exp`] [A `int` exponent.]] | |
558 | [[`b`] [A `bool` flag.]] | |
559 | [[`f`, `l`] [__fwditer__. first/last iterator pair.]] | |
560 | ] | |
561 | ||
562 | [heading Expression Semantics] | |
563 | ||
564 | Semantics of an expression is defined only where it differs from, or is | |
565 | not defined in __primitive_parser_concept__. | |
566 | ||
567 | [table | |
568 | [ | |
569 | [Expression] | |
570 | [Semantics] | |
571 | ][ | |
572 | [`` | |
573 | float_ | |
574 | double_ | |
575 | long_double | |
576 | ``] | |
577 | [Parse a real using the default policies (`real_policies<T>`).] | |
578 | ][ | |
579 | [`` | |
580 | lit(num) | |
581 | float_(num) | |
582 | double_(num) | |
583 | long_double(num) | |
584 | ``] | |
585 | [Match the literal `num` using the default policies (`real_policies<T>`). | |
586 | The parser will fail if the parsed value is not equal to the specified | |
587 | value.] | |
588 | ][ | |
589 | [`` | |
590 | real_parser< | |
591 | T, RealPolicies | |
592 | >() | |
593 | ``] | |
594 | [Parse a real of type `T` using `RealPolicies`.] | |
595 | ][ | |
596 | [`` | |
597 | real_parser< | |
598 | T, RealPolicies | |
599 | >()(num) | |
600 | ``] | |
601 | [Match the literal `num` of type `T` using `RealPolicies`. The parser will fail | |
602 | if the parsed value is not equal to the specified value.] | |
603 | ] | |
604 | ] | |
605 | ||
606 | [heading Attributes] | |
607 | ||
608 | [table | |
609 | [ | |
610 | [Expression] | |
611 | [Attribute] | |
612 | ][ | |
613 | [`` | |
614 | lit(num) | |
615 | ``] | |
616 | [__unused__] | |
617 | ][ | |
618 | [`` | |
619 | float_ | |
620 | float_(num) | |
621 | ``] | |
622 | [`float`] | |
623 | ][ | |
624 | [`` | |
625 | double_ | |
626 | double_(num) | |
627 | ``] | |
628 | [`double`] | |
629 | ][ | |
630 | [`` | |
631 | long_double | |
632 | long_double(num) | |
633 | ``] | |
634 | [`long double`] | |
635 | ][ | |
636 | [`` | |
637 | real_parser< | |
638 | T, RealPolicies | |
639 | >() | |
640 | real_parser< | |
641 | T, RealPolicies | |
642 | >()(num) | |
643 | ``] | |
644 | [`T`] | |
645 | ] | |
646 | ] | |
647 | ||
648 | [heading Complexity] | |
649 | ||
650 | [:O(N), where N is the number of characters (including the digits, | |
651 | exponent, sign, etc.) being parsed.] | |
652 | ||
653 | [heading Minimum Expression Requirements for `T`] | |
654 | ||
655 | The numeric base type, `T`, the minimum expression requirements listed | |
656 | below must be valid. Take note that additional requirements may be | |
657 | imposed by custom policies. | |
658 | ||
659 | [table | |
660 | [[Expression] [Semantics]] | |
661 | [[`T()`] [Default construct.]] | |
662 | [[`T(0)`] [Construct from an `int`.]] | |
663 | [[`n + n`] [Addition.]] | |
664 | [[`n - n`] [Subtraction.]] | |
665 | [[`n * n`] [Multiplication.]] | |
666 | [[`std::numeric_limits<T>::is_bounded`] [`true` or `false` if `T` bounded.]] | |
667 | [[`std::numeric_limits<T>::digits`] [Maximum Digits for `T`, radix digits. | |
668 | Required only if `T` is bounded.]] | |
669 | [[`std::numeric_limits<T>::digits10`] [Maximum Digits for `T`, base 10. | |
670 | Required only if `T` is bounded.]] | |
671 | [[`std::numeric_limits<T>::max()`] [Maximum value for `T`. | |
672 | Required only if `T` is bounded.]] | |
673 | [[`std::numeric_limits<T>::min()`] [Minimum value for `T`. | |
674 | Required only if `T` is bounded.]] | |
675 | ||
676 | ||
677 | [[`boost::spirit::traits::scale(exp, n)`] | |
678 | [Multiply `n` by `10^exp`. Default implementation | |
679 | is provided for `float`, `double` and `long double`.]] | |
680 | ||
681 | [[`boost::spirit::traits::negate(b, n)`] | |
682 | [Negate `n` if `b` is `true`. Default implementation | |
683 | is provided for `float`, `double` and `long double`.]] | |
684 | ||
685 | [[`boost::spirit::traits::is_equal_to_one(n)`] | |
686 | [Return `true` if `n` is equal to `1.0`. Default implementation | |
687 | is provided for `float`, `double` and `long double`.]] | |
688 | ||
689 | ] | |
690 | ||
691 | [note The additional spirit real number traits above are provided to | |
692 | allow custom implementations to implement efficient real number parsers. | |
693 | For example, for certain custom real numbers, scaling to a base 10 | |
694 | exponent is a very cheap operation.] | |
695 | ||
696 | [heading `RealPolicies`] | |
697 | ||
698 | The `RealPolicies` template parameter is a class that groups all the | |
699 | policies that control the parser's behavior. Policies control the real | |
700 | number parsers' behavior. | |
701 | ||
702 | The default is `real_policies<T>`. The default is provided to take care | |
703 | of the most common case (there are many ways to represent, and hence | |
704 | parse, real numbers). In most cases, the default policies are sufficient | |
705 | and can be used straight out of the box. They are designed to parse | |
706 | C/C++ style floating point numbers of the form `nnn.fff.Eeee` where | |
707 | `nnn` is the whole number part, `fff` is the fractional part, `E` is | |
708 | `'e'` or `'E'` and `eee` is the exponent optionally preceded by `'-'` or | |
709 | `'+'` with the additional detection of NaN and Inf as mandated by the | |
710 | C99 Standard and proposed for inclusion into the C++0x Standard: nan, | |
711 | nan(...), inf and infinity (the matching is case-insensitive). This | |
712 | corresponds to the following grammar: | |
713 | ||
714 | sign | |
715 | = lit('+') | '-' | |
716 | ; | |
717 | ||
718 | nan | |
719 | = -lit("1.0#") >> no_case["nan"] | |
720 | >> -('(' >> *(char_ - ')') >> ')') | |
721 | ; | |
722 | ||
723 | inf | |
724 | = no_case[lit("inf") >> -lit("inity")] | |
725 | ; | |
726 | ||
727 | floating_literal | |
728 | = -sign >> | |
729 | ( nan | |
730 | | inf | |
731 | | fractional_constant >> -exponent_part | |
732 | | +digit >> exponent_part | |
733 | ) | |
734 | ; | |
735 | ||
736 | fractional_constant | |
737 | = *digit >> '.' >> +digit | |
738 | | +digit >> -lit('.') | |
739 | ; | |
740 | ||
741 | exponent_part | |
742 | = (lit('e') | 'E') >> -sign >> +digit | |
743 | ; | |
744 | ||
745 | There are four `RealPolicies` predefined for immediate use: | |
746 | ||
747 | [table Predefined Policies | |
748 | ||
749 | [[Policies] [Description]] | |
750 | [[`ureal_policies<double>`] [Without sign.]] | |
751 | [[`real_policies<double>`] [With sign.]] | |
752 | [[`strict_ureal_policies<double>`] [Without sign, dot required.]] | |
753 | [[`strict_real_policies<double>`] [With sign, dot required.]] | |
754 | ] | |
755 | ||
756 | [note Integers are considered a subset of real numbers, so for instance, | |
757 | `double_` recognizes integer numbers (without a dot) just as well. To | |
758 | avoid this ambiguity, `strict_ureal_policies` and `strict_real_policies` | |
759 | require a dot to be present for a number to be considered a successful | |
760 | match.] | |
761 | ||
762 | [heading `RealPolicies` Expression Requirements] | |
763 | ||
764 | For models of `RealPolicies` the following expressions must be valid: | |
765 | ||
766 | [table | |
767 | [[Expression] [Semantics]] | |
768 | [[`RP::allow_leading_dot`] [Allow leading dot.]] | |
769 | [[`RP::allow_trailing_dot`] [Allow trailing dot.]] | |
770 | [[`RP::expect_dot`] [Require a dot.]] | |
771 | [[`RP::parse_sign(f, l)`] [Parse the prefix sign (e.g. '-'). | |
772 | Return `true` if successful, otherwise `false`.]] | |
773 | [[`RP::parse_n(f, l, n)`] [Parse the integer at the left of the decimal point. | |
774 | Return `true` if successful, otherwise `false`. | |
775 | If successful, place the result into `n`.]] | |
776 | [[`RP::parse_dot(f, l)`] [Parse the decimal point. | |
777 | Return `true` if successful, otherwise `false`.]] | |
778 | [[`RP::parse_frac_n(f, l, n)`] [Parse the fraction after the decimal point. | |
779 | Return `true` if successful, otherwise `false`. | |
780 | If successful, place the result into `n`.]] | |
781 | [[`RP::parse_exp(f, l)`] [Parse the exponent prefix (e.g. 'e'). | |
782 | Return `true` if successful, otherwise `false`.]] | |
783 | [[`RP::parse_exp_n(f, l, n)`] [Parse the actual exponent. | |
784 | Return `true` if successful, otherwise `false`. | |
785 | If successful, place the result into `n`.]] | |
786 | [[`RP::parse_nan(f, l, n)`] [Parse a NaN. | |
787 | Return `true` if successful, otherwise `false`. | |
788 | If successful, place the result into `n`.]] | |
789 | [[`RP::parse_inf(f, l, n)`] [Parse an Inf. | |
790 | Return `true` if successful, otherwise `false`. | |
791 | If successful, place the result into `n`.]] | |
792 | ] | |
793 | ||
794 | The `parse_nan` and `parse_inf` functions get called whenever: | |
795 | ||
796 | [:a number to parse does not start with a digit (after having | |
797 | successfully parsed an optional sign)] | |
798 | ||
799 | or | |
800 | ||
801 | [:after a real number of the value 1 (having no exponential | |
802 | part and a fractional part value of 0) has been parsed.] | |
803 | ||
804 | The first call recognizes representations of NaN or Inf starting with a | |
805 | non-digit character (such as NaN, Inf, QNaN etc.). The second call | |
806 | recognizes representation formats starting with a `1.0` (such as | |
807 | `"1.0#NAN"` or `"1.0#INF"` etc.). | |
808 | ||
809 | The functions should return true if a Nan or Inf has been found. In this | |
810 | case the attribute `n` should be set to the matched value (NaN or Inf). | |
811 | The optional sign will be automatically applied afterwards. | |
812 | ||
813 | [heading `RealPolicies` Specializations] | |
814 | ||
815 | The easiest way to implement a proper real parsing policy is to derive a | |
816 | new type from the type `real_policies` while overriding the aspects | |
817 | of the parsing which need to be changed. For example, here's the | |
818 | implementation of the predefined `strict_real_policies`: | |
819 | ||
820 | template <typename T> | |
821 | struct strict_real_policies : real_policies<T> | |
822 | { | |
823 | static bool const expect_dot = true; | |
824 | }; | |
825 | ||
826 | [heading Example] | |
827 | ||
828 | [note The test harness for the example(s) below is presented in the | |
829 | __qi_basics_examples__ section.] | |
830 | ||
831 | Some using declarations: | |
832 | ||
833 | [reference_using_declarations_real] | |
834 | ||
835 | Basic real number parsing: | |
836 | ||
837 | [reference_real] | |
838 | ||
839 | A custom real number policy: | |
840 | ||
841 | [reference_test_real_policy] | |
842 | ||
843 | And its use: | |
844 | ||
845 | [reference_custom_real] | |
846 | ||
847 | [endsect] [/ Real Numbers] | |
848 | ||
849 | [/------------------------------------------------------------------------------] | |
850 | [section:boolean Boolean Parser (`bool_`)] | |
851 | ||
852 | [heading Description] | |
853 | ||
854 | The `bool_parser` can parse booleans of arbitrary type, `B`. The boolean base | |
855 | type `T` can be a user defined boolean type as long as the type follows certain | |
856 | expression requirements (documented below). | |
857 | ||
858 | [heading Header] | |
859 | ||
860 | // forwards to <boost/spirit/home/qi/numeric/bool.hpp> | |
861 | #include <boost/spirit/include/qi_bool.hpp> | |
862 | ||
863 | Also, see __include_structure__. | |
864 | ||
865 | [heading Namespace] | |
866 | ||
867 | [table | |
868 | [[Name]] | |
869 | [[`boost::spirit::bool_ // alias: boost::spirit::qi::bool_`]] | |
870 | [[`boost::spirit::true_ // alias: boost::spirit::qi::true_`]] | |
871 | [[`boost::spirit::false_ // alias: boost::spirit::qi::false_`]] | |
872 | ] | |
873 | ||
874 | [heading Synopsis] | |
875 | ||
876 | template <typename T, typename BooleanPolicies> | |
877 | struct bool_parser; | |
878 | ||
879 | [heading Template parameters] | |
880 | ||
881 | [table | |
882 | [[Parameter] [Description] [Default]] | |
883 | [[`B`] [The boolean type of the | |
884 | boolean parser.] [`bool`]] | |
885 | [[`BooleanPolicies`] [Policies control the | |
886 | parser's behavior.] [`bool_policies<B>`]] | |
887 | ] | |
888 | ||
889 | [heading Model of] | |
890 | ||
891 | [:__primitive_parser_concept__] | |
892 | ||
893 | [variablelist Notation | |
894 | [[`BP`] [A boolean `Policies` (type).]] | |
895 | [[`b`] [An object of `B`, the numeric base type.]] | |
896 | [[`boolean`] [Numeric literal, any boolean value, or a | |
897 | __qi_lazy_argument__ that evaluates to a boolean value.]] | |
898 | [[`f`, `l`] [__fwditer__. first/last iterator pair.]] | |
899 | [[`attr`] [An attribute value.]] | |
900 | [[`Context`] [The type of the parse context of the current invocation of | |
901 | the `bool_` parser.]] | |
902 | [[`ctx`] [An instance of the parse context, `Context`.]] | |
903 | ] | |
904 | ||
905 | [heading Expression Semantics] | |
906 | ||
907 | Semantics of an expression is defined only where it differs from, or is | |
908 | not defined in __primitive_parser_concept__. | |
909 | ||
910 | [table | |
911 | [ | |
912 | [Expression] | |
913 | [Semantics] | |
914 | ][ | |
915 | [`` | |
916 | bool_ | |
917 | ``] | |
918 | [Parse a boolean using the default policies (`bool_policies<T>`).] | |
919 | ][ | |
920 | [`` | |
921 | lit(boolean) | |
922 | bool_(boolean) | |
923 | ``] | |
924 | [Match the literal `boolean` using the default policies (`bool_policies<T>`). | |
925 | The parser will fail if the parsed value is not equal to the specified | |
926 | value.] | |
927 | ][ | |
928 | [`` | |
929 | true_ | |
930 | false_ | |
931 | ``] | |
932 | [Match `"true"` and `"false"`, respectively.] | |
933 | ][ | |
934 | [`` | |
935 | bool_parser< | |
936 | T, BoolPolicies | |
937 | >() | |
938 | ``] | |
939 | [Parse a real of type `T` using `BoolPolicies`.] | |
940 | ][ | |
941 | [`` | |
942 | bool_parser< | |
943 | T, BoolPolicies | |
944 | >()(boolean) | |
945 | ``] | |
946 | [Match the literal `boolean` of type `T` using `BoolPolicies`. The parser will fail | |
947 | if the parsed value is not equal to the specified value.] | |
948 | ] | |
949 | ] | |
950 | ||
951 | [note All boolean parsers properly respect the __qi_no_case__`[]` directive.] | |
952 | ||
953 | [heading Attributes] | |
954 | ||
955 | [table | |
956 | [ | |
957 | [Expression] | |
958 | [Attribute] | |
959 | ][ | |
960 | [`` | |
961 | lit(boolean) | |
962 | ``] | |
963 | [__unused__] | |
964 | ][ | |
965 | [`` | |
966 | true_ | |
967 | false_ | |
968 | bool_ | |
969 | bool_(boolean) | |
970 | ``] | |
971 | [`bool`] | |
972 | ][ | |
973 | [`` | |
974 | bool_parser< | |
975 | T, BoolPolicies | |
976 | >() | |
977 | bool_parser< | |
978 | T, BoolPolicies | |
979 | >()(num) | |
980 | ``] | |
981 | [`T`] | |
982 | ] | |
983 | ] | |
984 | ||
985 | [heading Complexity] | |
986 | ||
987 | [:O(N), where N is the number of characters being parsed.] | |
988 | ||
989 | [heading Minimum Expression Requirements for `B`] | |
990 | ||
991 | The boolean type, `B`, the minimum expression requirements listed | |
992 | below must be valid. Take note that additional requirements may be | |
993 | imposed by custom policies. | |
994 | ||
995 | [table | |
996 | [[Expression] [Semantics]] | |
997 | [[`B(bool)`] [Constructible from a `bool`.]] | |
998 | ] | |
999 | ||
1000 | [heading Boolean `Policies`] | |
1001 | ||
1002 | The boolean `Policies` template parameter is a class that groups all the | |
1003 | policies that control the parser's behavior. Policies control the boolean | |
1004 | parsers' behavior. | |
1005 | ||
1006 | The default is `bool_policies<bool>`. The default is provided to take care | |
1007 | of the most common case (there are many ways to represent, and hence | |
1008 | parse, boolean numbers). In most cases, the default policies are sufficient | |
1009 | and can be used straight out of the box. They are designed to parse | |
1010 | boolean value of the form `"true"` and `"false"`. | |
1011 | ||
1012 | [heading Boolean `Policies` Expression Requirements] | |
1013 | ||
1014 | For models of boolean `Policies` the following expressions must be valid: | |
1015 | ||
1016 | [table | |
1017 | [[Expression] [Semantics]] | |
1018 | [[`BP::parse_true(f, l, attr, ctx)`] [Parse a `true` value.]] | |
1019 | [[`BP::parse_false(f, l, attr, ctx)`] [Parse a `false` value.]] | |
1020 | ] | |
1021 | ||
1022 | The functions should return true if the required representations of `true` or | |
1023 | `false` have been found. In this case the attribute `n` should be set to the | |
1024 | matched value (`true` or `false`). | |
1025 | ||
1026 | [heading Boolean `Policies` Specializations] | |
1027 | ||
1028 | The easiest way to implement a proper boolean parsing policy is to derive a | |
1029 | new type from the type `bool_policies` while overriding the aspects | |
1030 | of the parsing which need to be changed. For example, here's the | |
1031 | implementation of a boolean parsing policy interpreting the string `"eurt"` | |
1032 | (i.e. "true" spelled backwards) as `false`: | |
1033 | ||
1034 | struct backwards_bool_policies : qi::bool_policies<> | |
1035 | { | |
1036 | // we want to interpret a 'true' spelled backwards as 'false' | |
1037 | template <typename Iterator, typename Attribute, typename Context> | |
1038 | static bool | |
1039 | parse_false(Iterator& first, Iterator const& last, Attribute& attr, Context& ctx) | |
1040 | { | |
1041 | namespace qi = boost::spirit::qi; | |
1042 | if (qi::detail::string_parse("eurt", first, last, qi::unused, qi::unused)) | |
1043 | { | |
1044 | spirit::traits::assign_to(false, attr, ctx); // result is false | |
1045 | return true; | |
1046 | } | |
1047 | return false; | |
1048 | } | |
1049 | }; | |
1050 | ||
1051 | [heading Example] | |
1052 | ||
1053 | [note The test harness for the example(s) below is presented in the | |
1054 | __qi_basics_examples__ section.] | |
1055 | ||
1056 | Some using declarations: | |
1057 | ||
1058 | [reference_using_declarations_bool] | |
1059 | ||
1060 | Basic real number parsing: | |
1061 | ||
1062 | [reference_bool] | |
1063 | ||
1064 | A custom real number policy: | |
1065 | ||
1066 | [reference_test_bool_policy] | |
1067 | ||
1068 | And its use: | |
1069 | ||
1070 | [reference_custom_bool] | |
1071 | ||
1072 | [endsect] [/ Real Numbers] | |
1073 | ||
1074 | [endsect] |