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 11The library includes a couple of predefined objects for parsing signed 12and unsigned integers and real numbers. These parsers are fully 13parametric. Most of the important aspects of numeric parsing can be 14finely adjusted to suit. This includes the radix base, the minimum and 15maximum number of allowable digits, the exponent, the fraction etc. 16Policies control the real number parsers' behavior. There are some 17predefined policies covering the most common real number formats but the 18user can supply her own when needed. 19 20The numeric parsers are fine tuned (employing loop unrolling and 21extensive template metaprogramming) with exceptional performance that 22rivals the low level C functions such as `atof`, `strtod`, `atol`, 23`strtol`. Benchmarks reveal up to 4X speed over the C counterparts. This 24goes to show that you can write extremely tight generic C++ code that 25rivals, 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 32Also, see __include_structure__. 33 34[/------------------------------------------------------------------------------] 35[section:uint Unsigned Integer Parsers (`uint_`, etc.)] 36 37[heading Description] 38 39The `uint_parser` class is the simplest among the members of the 40numerics package. The `uint_parser` can parse unsigned integers of 41arbitrary length and size. The `uint_parser` parser can be used to parse 42ordinary primitive C/C++ integers or even user defined scalars such as 43bigints (unlimited precision integers) as long as the type follows 44certain expression requirements (documented below). The `uint_parser` is 45a 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 52Also, 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 69constant `BOOST_HAS_LONG_LONG` is defined (i.e. on platforms having 70native support for `unsigned long long` (64 bit) unsigned integer 71types).] 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 115Semantics of an expression is defined only where it differs from, or is 116not 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 243For the numeric base type, `T`, the expression requirements below must be 244valid: 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 268Some using declarations: 269 270[reference_using_declarations_uint] 271 272Basic 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 285The `int_parser` can parse signed integers of arbitrary length and size. 286This is almost the same as the `uint_parser`. The only difference is the 287additional task of parsing the `'+'` or `'-'` sign preceding the number. 288The class interface is the same as that of the `uint_parser`. 289 290The `int_parser` parser can be used to parse ordinary primitive C/C++ 291integers or even user defined scalars such as bigints (unlimited 292precision integers) as long as the type follows certain expression 293requirements (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 300Also, 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 314constant `BOOST_HAS_LONG_LONG` is defined (i.e. on platforms having 315native 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 359Semantics of an expression is defined only where it differs from, or is 360not 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 464For the numeric base type, `T`, the expression requirements below must be 465valid: 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 490Some using declarations: 491 492[reference_using_declarations_int] 493 494Basic 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 505The `real_parser` can parse real numbers of arbitrary length and size 506limited by its template parameter, `T`. The numeric base type `T` can be 507a user defined numeric type such as fixed_point (fixed point reals) and 508bignum (unlimited precision numbers) as long as the type follows certain 509expression 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 516Also, 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 564Semantics of an expression is defined only where it differs from, or is 565not 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, 651exponent, sign, etc.) being parsed.] 652 653[heading Minimum Expression Requirements for `T`] 654 655The numeric base type, `T`, the minimum expression requirements listed 656below must be valid. Take note that additional requirements may be 657imposed 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] 686 687[note The additional spirit real number traits above are provided to 688allow custom implementations to implement efficient real number parsers. 689For example, for certain custom real numbers, scaling to a base 10 690exponent is a very cheap operation.] 691 692[heading `RealPolicies`] 693 694The `RealPolicies` template parameter is a class that groups all the 695policies that control the parser's behavior. Policies control the real 696number parsers' behavior. 697 698The default is `real_policies<T>`. The default is provided to take care 699of the most common case (there are many ways to represent, and hence 700parse, real numbers). In most cases, the default policies are sufficient 701and can be used straight out of the box. They are designed to parse 702C/C++ style floating point numbers of the form `nnn.fff.Eeee` where 703`nnn` is the whole number part, `fff` is the fractional part, `E` is 704`'e'` or `'E'` and `eee` is the exponent optionally preceded by `'-'` or 705`'+'` with the additional detection of NaN and Inf as mandated by the 706C99 Standard and proposed for inclusion into the C++0x Standard: nan, 707nan(...), inf and infinity (the matching is case-insensitive). This 708corresponds to the following grammar: 709 710 sign 711 = lit('+') | '-' 712 ; 713 714 nan 715 = no_case["nan"] 716 >> -('(' >> *(char_ - ')') >> ')') 717 ; 718 719 inf 720 = no_case[lit("inf") >> -lit("inity")] 721 ; 722 723 floating_literal 724 = -sign >> 725 ( nan 726 | inf 727 | fractional_constant >> -exponent_part 728 | +digit >> exponent_part 729 ) 730 ; 731 732 fractional_constant 733 = *digit >> '.' >> +digit 734 | +digit >> -lit('.') 735 ; 736 737 exponent_part 738 = (lit('e') | 'E') >> -sign >> +digit 739 ; 740 741There are four `RealPolicies` predefined for immediate use: 742 743[table Predefined Policies 744 745 [[Policies] [Description]] 746 [[`ureal_policies<double>`] [Without sign.]] 747 [[`real_policies<double>`] [With sign.]] 748 [[`strict_ureal_policies<double>`] [Without sign, dot required.]] 749 [[`strict_real_policies<double>`] [With sign, dot required.]] 750] 751 752[note Integers are considered a subset of real numbers, so for instance, 753`double_` recognizes integer numbers (without a dot) just as well. To 754avoid this ambiguity, `strict_ureal_policies` and `strict_real_policies` 755require a dot to be present for a number to be considered a successful 756match.] 757 758[heading `RealPolicies` Expression Requirements] 759 760For models of `RealPolicies` the following expressions must be valid: 761 762[table 763 [[Expression] [Semantics]] 764 [[`RP::allow_leading_dot`] [Allow leading dot.]] 765 [[`RP::allow_trailing_dot`] [Allow trailing dot.]] 766 [[`RP::expect_dot`] [Require a dot.]] 767 [[`RP::parse_sign(f, l)`] [Parse the prefix sign (e.g. '-'). 768 Return `true` if successful, otherwise `false`.]] 769 [[`RP::parse_n(f, l, n)`] [Parse the integer at the left of the decimal point. 770 Return `true` if successful, otherwise `false`. 771 If successful, place the result into `n`.]] 772 [[`RP::parse_dot(f, l)`] [Parse the decimal point. 773 Return `true` if successful, otherwise `false`.]] 774 [[`RP::parse_frac_n(f, l, n)`] [Parse the fraction after the decimal point. 775 Return `true` if successful, otherwise `false`. 776 If successful, place the result into `n`.]] 777 [[`RP::parse_exp(f, l)`] [Parse the exponent prefix (e.g. 'e'). 778 Return `true` if successful, otherwise `false`.]] 779 [[`RP::parse_exp_n(f, l, n)`] [Parse the actual exponent. 780 Return `true` if successful, otherwise `false`. 781 If successful, place the result into `n`.]] 782 [[`RP::parse_nan(f, l, n)`] [Parse a NaN. 783 Return `true` if successful, otherwise `false`. 784 If successful, place the result into `n`.]] 785 [[`RP::parse_inf(f, l, n)`] [Parse an Inf. 786 Return `true` if successful, otherwise `false`. 787 If successful, place the result into `n`.]] 788] 789 790The `parse_nan` and `parse_inf` functions get called whenever 791a number to parse does not start with a digit (after having 792successfully parsed an optional sign). 793 794The functions should return true if a Nan or Inf has been found. In this 795case the attribute `n` should be set to the matched value (NaN or Inf). 796The optional sign will be automatically applied afterwards. 797 798[heading `RealPolicies` Specializations] 799 800The easiest way to implement a proper real parsing policy is to derive a 801new type from the type `real_policies` while overriding the aspects 802of the parsing which need to be changed. For example, here's the 803implementation of the predefined `strict_real_policies`: 804 805 template <typename T> 806 struct strict_real_policies : real_policies<T> 807 { 808 static bool const expect_dot = true; 809 }; 810 811[heading Example] 812 813[note The test harness for the example(s) below is presented in the 814__qi_basics_examples__ section.] 815 816Some using declarations: 817 818[reference_using_declarations_real] 819 820Basic real number parsing: 821 822[reference_real] 823 824A custom real number policy: 825 826[reference_test_real_policy] 827 828And its use: 829 830[reference_custom_real] 831 832[endsect] [/ Real Numbers] 833 834[/------------------------------------------------------------------------------] 835[section:boolean Boolean Parser (`bool_`)] 836 837[heading Description] 838 839The `bool_parser` can parse booleans of arbitrary type, `B`. The boolean base 840type `T` can be a user defined boolean type as long as the type follows certain 841expression requirements (documented below). 842 843[heading Header] 844 845 // forwards to <boost/spirit/home/qi/numeric/bool.hpp> 846 #include <boost/spirit/include/qi_bool.hpp> 847 848Also, see __include_structure__. 849 850[heading Namespace] 851 852[table 853 [[Name]] 854 [[`boost::spirit::bool_ // alias: boost::spirit::qi::bool_`]] 855 [[`boost::spirit::true_ // alias: boost::spirit::qi::true_`]] 856 [[`boost::spirit::false_ // alias: boost::spirit::qi::false_`]] 857] 858 859[heading Synopsis] 860 861 template <typename T, typename BooleanPolicies> 862 struct bool_parser; 863 864[heading Template parameters] 865 866[table 867 [[Parameter] [Description] [Default]] 868 [[`B`] [The boolean type of the 869 boolean parser.] [`bool`]] 870 [[`BooleanPolicies`] [Policies control the 871 parser's behavior.] [`bool_policies<B>`]] 872] 873 874[heading Model of] 875 876[:__primitive_parser_concept__] 877 878[variablelist Notation 879 [[`BP`] [A boolean `Policies` (type).]] 880 [[`b`] [An object of `B`, the numeric base type.]] 881 [[`boolean`] [Numeric literal, any boolean value, or a 882 __qi_lazy_argument__ that evaluates to a boolean value.]] 883 [[`f`, `l`] [__fwditer__. first/last iterator pair.]] 884 [[`attr`] [An attribute value.]] 885 [[`Context`] [The type of the parse context of the current invocation of 886 the `bool_` parser.]] 887 [[`ctx`] [An instance of the parse context, `Context`.]] 888] 889 890[heading Expression Semantics] 891 892Semantics of an expression is defined only where it differs from, or is 893not defined in __primitive_parser_concept__. 894 895[table 896 [ 897 [Expression] 898 [Semantics] 899 ][ 900 [`` 901 bool_ 902 ``] 903 [Parse a boolean using the default policies (`bool_policies<T>`).] 904 ][ 905 [`` 906 lit(boolean) 907 bool_(boolean) 908 ``] 909 [Match the literal `boolean` using the default policies (`bool_policies<T>`). 910 The parser will fail if the parsed value is not equal to the specified 911 value.] 912 ][ 913 [`` 914 true_ 915 false_ 916 ``] 917 [Match `"true"` and `"false"`, respectively.] 918 ][ 919 [`` 920 bool_parser< 921 T, BoolPolicies 922 >() 923 ``] 924 [Parse a real of type `T` using `BoolPolicies`.] 925 ][ 926 [`` 927 bool_parser< 928 T, BoolPolicies 929 >()(boolean) 930 ``] 931 [Match the literal `boolean` of type `T` using `BoolPolicies`. The parser will fail 932 if the parsed value is not equal to the specified value.] 933 ] 934] 935 936[note All boolean parsers properly respect the __qi_no_case__`[]` directive.] 937 938[heading Attributes] 939 940[table 941 [ 942 [Expression] 943 [Attribute] 944 ][ 945 [`` 946 lit(boolean) 947 ``] 948 [__unused__] 949 ][ 950 [`` 951 true_ 952 false_ 953 bool_ 954 bool_(boolean) 955 ``] 956 [`bool`] 957 ][ 958 [`` 959 bool_parser< 960 T, BoolPolicies 961 >() 962 bool_parser< 963 T, BoolPolicies 964 >()(num) 965 ``] 966 [`T`] 967 ] 968] 969 970[heading Complexity] 971 972[:O(N), where N is the number of characters being parsed.] 973 974[heading Minimum Expression Requirements for `B`] 975 976The boolean type, `B`, the minimum expression requirements listed 977below must be valid. Take note that additional requirements may be 978imposed by custom policies. 979 980[table 981 [[Expression] [Semantics]] 982 [[`B(bool)`] [Constructible from a `bool`.]] 983] 984 985[heading Boolean `Policies`] 986 987The boolean `Policies` template parameter is a class that groups all the 988policies that control the parser's behavior. Policies control the boolean 989parsers' behavior. 990 991The default is `bool_policies<bool>`. The default is provided to take care 992of the most common case (there are many ways to represent, and hence 993parse, boolean numbers). In most cases, the default policies are sufficient 994and can be used straight out of the box. They are designed to parse 995boolean value of the form `"true"` and `"false"`. 996 997[heading Boolean `Policies` Expression Requirements] 998 999For models of boolean `Policies` the following expressions must be valid: 1000 1001[table 1002 [[Expression] [Semantics]] 1003 [[`BP::parse_true(f, l, attr)`] [Parse a `true` value.]] 1004 [[`BP::parse_false(f, l, attr)`] [Parse a `false` value.]] 1005] 1006 1007The functions should return true if the required representations of `true` or 1008`false` have been found. In this case the attribute `n` should be set to the 1009matched value (`true` or `false`). 1010 1011[heading Boolean `Policies` Specializations] 1012 1013The easiest way to implement a proper boolean parsing policy is to derive a 1014new type from the type `bool_policies` while overriding the aspects 1015of the parsing which need to be changed. For example, here's the 1016implementation of a boolean parsing policy interpreting the string `"eurt"` 1017(i.e. "true" spelled backwards) as `false`: 1018 1019 struct backwards_bool_policies : qi::bool_policies<> 1020 { 1021 // we want to interpret a 'true' spelled backwards as 'false' 1022 template <typename Iterator, typename Attribute> 1023 static bool 1024 parse_false(Iterator& first, Iterator const& last, Attribute& attr) 1025 { 1026 namespace qi = boost::spirit::qi; 1027 if (qi::detail::string_parse("eurt", first, last, qi::unused)) 1028 { 1029 spirit::traits::assign_to(false, attr); // result is false 1030 return true; 1031 } 1032 return false; 1033 } 1034 }; 1035 1036[heading Example] 1037 1038[note The test harness for the example(s) below is presented in the 1039__qi_basics_examples__ section.] 1040 1041Some using declarations: 1042 1043[reference_using_declarations_bool] 1044 1045Basic real number parsing: 1046 1047[reference_bool] 1048 1049A custom real number policy: 1050 1051[reference_test_bool_policy] 1052 1053And its use: 1054 1055[reference_custom_bool] 1056 1057[endsect] [/ Real Numbers] 1058 1059[endsect] 1060