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

   1 [/==============================================================================
   2     Copyright (C) 2001-2011 Joel de Guzman
   3     Copyright (C) 2001-2011 Hartmut Kaiser
   4
   5     Distributed under the Boost Software License, Version 1.0. (See accompanying
   6     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   7 ===============================================================================/]
   8
   9 [section: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]