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 [[`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 692allow custom implementations to implement efficient real number parsers. 693For example, for certain custom real numbers, scaling to a base 10 694exponent is a very cheap operation.] 695 696[heading `RealPolicies`] 697 698The `RealPolicies` template parameter is a class that groups all the 699policies that control the parser's behavior. Policies control the real 700number parsers' behavior. 701 702The default is `real_policies<T>`. The default is provided to take care 703of the most common case (there are many ways to represent, and hence 704parse, real numbers). In most cases, the default policies are sufficient 705and can be used straight out of the box. They are designed to parse 706C/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 710C99 Standard and proposed for inclusion into the C++0x Standard: nan, 711nan(...), inf and infinity (the matching is case-insensitive). This 712corresponds 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 745There 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 758avoid this ambiguity, `strict_ureal_policies` and `strict_real_policies` 759require a dot to be present for a number to be considered a successful 760match.] 761 762[heading `RealPolicies` Expression Requirements] 763 764For 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 794The `parse_nan` and `parse_inf` functions get called whenever: 795 796[:a number to parse does not start with a digit (after having 797successfully parsed an optional sign)] 798 799or 800 801[:after a real number of the value 1 (having no exponential 802part and a fractional part value of 0) has been parsed.] 803 804The first call recognizes representations of NaN or Inf starting with a 805non-digit character (such as NaN, Inf, QNaN etc.). The second call 806recognizes representation formats starting with a `1.0` (such as 807`"1.0#NAN"` or `"1.0#INF"` etc.). 808 809The functions should return true if a Nan or Inf has been found. In this 810case the attribute `n` should be set to the matched value (NaN or Inf). 811The optional sign will be automatically applied afterwards. 812 813[heading `RealPolicies` Specializations] 814 815The easiest way to implement a proper real parsing policy is to derive a 816new type from the type `real_policies` while overriding the aspects 817of the parsing which need to be changed. For example, here's the 818implementation 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 831Some using declarations: 832 833[reference_using_declarations_real] 834 835Basic real number parsing: 836 837[reference_real] 838 839A custom real number policy: 840 841[reference_test_real_policy] 842 843And 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 854The `bool_parser` can parse booleans of arbitrary type, `B`. The boolean base 855type `T` can be a user defined boolean type as long as the type follows certain 856expression 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 863Also, 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 907Semantics of an expression is defined only where it differs from, or is 908not 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 991The boolean type, `B`, the minimum expression requirements listed 992below must be valid. Take note that additional requirements may be 993imposed by custom policies. 994 995[table 996 [[Expression] [Semantics]] 997 [[`B(bool)`] [Constructible from a `bool`.]] 998] 999 1000[heading Boolean `Policies`] 1001 1002The boolean `Policies` template parameter is a class that groups all the 1003policies that control the parser's behavior. Policies control the boolean 1004parsers' behavior. 1005 1006The default is `bool_policies<bool>`. The default is provided to take care 1007of the most common case (there are many ways to represent, and hence 1008parse, boolean numbers). In most cases, the default policies are sufficient 1009and can be used straight out of the box. They are designed to parse 1010boolean value of the form `"true"` and `"false"`. 1011 1012[heading Boolean `Policies` Expression Requirements] 1013 1014For 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 1022The 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 1024matched value (`true` or `false`). 1025 1026[heading Boolean `Policies` Specializations] 1027 1028The easiest way to implement a proper boolean parsing policy is to derive a 1029new type from the type `bool_policies` while overriding the aspects 1030of the parsing which need to be changed. For example, here's the 1031implementation 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 1056Some using declarations: 1057 1058[reference_using_declarations_bool] 1059 1060Basic real number parsing: 1061 1062[reference_bool] 1063 1064A custom real number policy: 1065 1066[reference_test_bool_policy] 1067 1068And its use: 1069 1070[reference_custom_bool] 1071 1072[endsect] [/ Real Numbers] 1073 1074[endsect] 1075