EQ2EMu/EQ2/source/depends/boost_1_72_0/libs/spirit/doc/qi/numeric.qbk

[/==============================================================================
    Copyright (C) 2001-2011 Joel de Guzman
    Copyright (C) 2001-2011 Hartmut Kaiser

    Distributed under the Boost Software License, Version 1.0. (See accompanying
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
===============================================================================/]

[section:numeric Numeric Parsers]

The library includes a couple of predefined objects for parsing signed
and unsigned integers and real numbers. These parsers are fully
parametric. Most of the important aspects of numeric parsing can be
finely adjusted to suit. This includes the radix base, the minimum and
maximum number of allowable digits, the exponent, the fraction etc.
Policies control the real number parsers' behavior. There are some
predefined policies covering the most common real number formats but the
user can supply her own when needed.

The numeric parsers are fine tuned (employing loop unrolling and
extensive template metaprogramming) with exceptional performance that
rivals the low level C functions such as `atof`, `strtod`, `atol`,
`strtol`. Benchmarks reveal up to 4X speed over the C counterparts. This
goes to show that you can write extremely tight generic C++ code that
rivals, if not surpasses C.

[heading Module Header]

    // forwards to <boost/spirit/home/qi/numeric.hpp>
    #include <boost/spirit/include/qi_numeric.hpp>

Also, see __include_structure__.

[/------------------------------------------------------------------------------]
[section:uint Unsigned Integer Parsers (`uint_`, etc.)]

[heading Description]

The `uint_parser` class is the simplest among the members of the
numerics package. The `uint_parser` can parse unsigned integers of
arbitrary length and size. The `uint_parser` parser can be used to parse
ordinary primitive C/C++ integers or even user defined scalars such as
bigints (unlimited precision integers) as long as the type follows
certain expression requirements (documented below). The `uint_parser` is
a template class. Template parameters fine tune its behavior.

[heading Header]

    // forwards to <boost/spirit/home/qi/numeric/uint.hpp>
    #include <boost/spirit/include/qi_uint.hpp>

Also, see __include_structure__.

[heading Namespace]

[table
    [[Name]]
    [[`boost::spirit::lit           // alias: boost::spirit::qi::lit`]]
    [[`boost::spirit::bin           // alias: boost::spirit::qi::bin`]]
    [[`boost::spirit::oct           // alias: boost::spirit::qi::oct`]]
    [[`boost::spirit::hex           // alias: boost::spirit::qi::hex`]]
    [[`boost::spirit::ushort_       // alias: boost::spirit::qi::ushort_`]]
    [[`boost::spirit::ulong_        // alias: boost::spirit::qi::ulong_`]]
    [[`boost::spirit::uint_         // alias: boost::spirit::qi::uint_`]]
    [[`boost::spirit::ulong_long    // alias: boost::spirit::qi::ulong_long`]]
]

[note `ulong_long` is only available on platforms where the preprocessor
constant `BOOST_HAS_LONG_LONG` is defined (i.e. on platforms having
native support for `unsigned long long` (64 bit) unsigned integer
types).]

[note `lit` is reused by the [qi_lit_char Character Parsers], and the Numeric
      Parsers. In general, a char parser is created when you pass in a
      character, and a numeric parser is created when you use a numeric
      literal.]

[heading Synopsis]

    template <
        typename T
      , unsigned Radix
      , unsigned MinDigits
      , int MaxDigits>
    struct uint_parser;

[heading Template parameters]

[table
    [[Parameter]    [Description]                       [Default]]
    [[`T`]          [The numeric base type of the
                     numeric parser.]                   [none]]
    [[`Radix`]      [The radix base. This can be
                     any base from 2..10 and 16]        [10]]
    [[`MinDigits`]  [The minimum number of digits
                     allowable.]                        [1]]
    [[`MaxDigits`]  [The maximum number of digits
                     allowable. If this is -1, then the
                     maximum limit becomes unbounded.]  [-1]]
]

[heading Model of]

[:__primitive_parser_concept__]

[variablelist Notation
    [[`n`]          [An object of `T`, the numeric base type.]]
    [[`num`]        [Numeric literal, any unsigned integer value, or a
                     __qi_lazy_argument__ that evaluates to a unsigned integer
                     value.]]
]

[heading Expression Semantics]

Semantics of an expression is defined only where it differs from, or is
not defined in __primitive_parser_concept__.

[table
  [
    [Expression]
    [Semantics]
  ][
    [``
        ushort_
        uint_
        ulong_
        ulong_long
     ``]
    [Parse an unsigned integer using the default radix (10).]
  ][
    [``
        lit(num)
        ushort_(num)
        uint_(num)
        ulong_(num)
        ulong_long(num)
    ``]
    [Match the literal `num` using the default radix (10). The parser will fail
     if the parsed value is not equal to the specified value.]
  ][
    [``
        bin
        oct
        hex
    ``]
    [Parse an unsigned integer using radix 2 for `bin`, radix 8 for `oct`, and
     radix 16 for `hex`.]
  ][
    [``
        bin(num)
        oct(num)
        hex(num)
    ``]
    [Match the literal `num` using radix 2 for `bin`, radix 8 for `oct`, and
     radix 16 for `hex`. The parser will fail
     if the parsed value is not equal to the specified value.]
  ][
    [``
        uint_parser<
            T, Radix, MinDigits, MaxDigits
        >()
    ``]
    [Parse an unsigned integer of type `T` using radix `Radix`, with
     a minimum of `MinDigits` and a maximum of `MaxDigits`.]
  ][
    [``
        uint_parser<
            T, Radix, MinDigits, MaxDigits
        >()(num)
    ``]
    [Match the literal `num` of type `T` using radix `Radix`, with
     a minimum of `MinDigits` and a maximum of `MaxDigits`. The parser will fail
     if the parsed value is not equal to the specified value.]
  ]
]

[important All numeric parsers check for overflow conditions based on the type
      `T` the corresponding `uint_parser<>` has been instantiated with. If the
      parsed number overflows this type the parsing fails. Please be aware
      that the overflow check is not based on the type of the supplied
      attribute but solely depends on the template parameter `T`.]

[heading Attributes]

[table
  [
    [Expression]
    [Attribute]
  ][
    [``
        lit(num)
     ``]
    [__unused__]
  ][
    [``
        ushort_
        ushort_(num)
    ``]
    [`unsigned short`]
  ][
    [``
        uint_
        uint_(num)
        bin
        bin(num)
        oct
        oct(num)
        hex
        hex(num)
    ``]
    [`unsigned int`]
  ][
    [``
        ulong_
        ulong_(num)
    ``]
    [`unsigned long`]
  ][
    [``
        ulong_long
        ulong_long(num)
    ``]
    [`boost::ulong_long_type`]
  ][
    [``
        uint_parser<
            T, Radix, MinDigits, MaxDigits
        >()
        uint_parser<
            T, Radix, MinDigits, MaxDigits
        >()(num)
    ``]
    [`T`]
  ]
]

[heading Complexity]

[:O(N), where N is the number of digits being parsed.]

[heading Minimum Expression Requirements for `T`]

For the numeric base type, `T`, the expression requirements below must be
valid:

[table
    [[Expression]                           [Semantics]]
    [[`T()`]                                [Default construct.]]
    [[`T(0)`]                               [Construct from an `int`.]]
    [[`n + n`]                              [Addition.]]
    [[`n * n`]                              [Multiplication.]]
    [[`std::numeric_limits<T>::is_bounded`] [`true` or `false` if `T` bounded.]]
    [[`std::numeric_limits<T>::digits`]     [Maximum Digits for `T`, radix digits.
                                            Required only if `T` is bounded.]]
    [[`std::numeric_limits<T>::digits10`]   [Maximum Digits for `T`, base 10.
                                            Required only if `T` is bounded.]]
    [[`std::numeric_limits<T>::max()`]      [Maximum value for `T`.
                                            Required only if `T` is bounded.]]
    [[`std::numeric_limits<T>::min()`]      [Minimum value for `T`.
                                            Required only if `T` is bounded.]]
]

[heading Example]

[note The test harness for the example(s) below is presented in the
__qi_basics_examples__ section.]

Some using declarations:

[reference_using_declarations_uint]

Basic unsigned integers:

[reference_uint]

[reference_thousand_separated]

[endsect] [/ Unsigned Integers]

[/------------------------------------------------------------------------------]
[section:int Signed Integer Parsers (`int_`, etc.)]

[heading Description]

The `int_parser` can parse signed integers of arbitrary length and size.
This is almost the same as the `uint_parser`. The only difference is the
additional task of parsing the `'+'` or `'-'` sign preceding the number.
The class interface is the same as that of the `uint_parser`.

The `int_parser` parser can be used to parse ordinary primitive C/C++
integers or even user defined scalars such as bigints (unlimited
precision integers) as long as the type follows certain expression
requirements (documented below).

[heading Header]

    // forwards to <boost/spirit/home/qi/numeric/int.hpp>
    #include <boost/spirit/include/qi_int.hpp>

Also, see __include_structure__.

[heading Namespace]

[table
    [[Name]]
    [[`boost::spirit::lit           // alias: boost::spirit::qi::lit`]]
    [[`boost::spirit::short_        // alias: boost::spirit::qi::short_`]]
    [[`boost::spirit::int_          // alias: boost::spirit::qi::int_`]]
    [[`boost::spirit::long_         // alias: boost::spirit::qi::long_`]]
    [[`boost::spirit::long_long     // alias: boost::spirit::qi::long_long`]]
]

[note `long_long` is only available on platforms where the preprocessor
constant `BOOST_HAS_LONG_LONG` is defined (i.e. on platforms having
native support for `signed long long` (64 bit) unsigned integer types).]

[note `lit` is reused by the [qi_lit_char Character Parsers], and the Numeric
      Parsers. In general, a char parser is created when you pass in a
      character, and a numeric parser is created when you use a numeric
      literal.]

[heading Synopsis]

    template <
        typename T
      , unsigned Radix
      , unsigned MinDigits
      , int MaxDigits>
    struct int_parser;

[heading Template parameters]

[table
    [[Parameter]    [Description]                       [Default]]
    [[`T`]          [The numeric base type of the
                     numeric parser.]                   [none]]
    [[`Radix`]      [The radix base. This can be
                     any base from 2..10 and 16]        [10]]
    [[`MinDigits`]  [The minimum number of digits
                     allowable.]                        [1]]
    [[`MaxDigits`]  [The maximum number of digits
                     allowable. If this is -1, then the
                     maximum limit becomes unbounded.]  [-1]]
]

[heading Model of]

[:__primitive_parser_concept__]

[variablelist Notation
    [[`n`]          [An object of `T`, the numeric base type.]]
    [[`num`]        [Numeric literal, any signed integer value, or a
                     __qi_lazy_argument__ that evaluates to a signed integer
                     value.]]
]

[heading Expression Semantics]

Semantics of an expression is defined only where it differs from, or is
not defined in __primitive_parser_concept__.

[table
  [
    [Expression]
    [Semantics]
  ][
    [``
        short_
        int_
        long_
        long_long
     ``]
    [Parse a signed integer using the default radix (10).]
  ][
    [``
        lit(num)
        short_(num)
        int_(num)
        long_(num)
        long_long(num)
    ``]
    [Match the literal `num` using the default radix (10). The parser will fail
     if the parsed value is not equal to the specified value.]
  ][
    [``
        int_parser<
            T, Radix, MinDigits, MaxDigits
        >()
    ``]
    [Parse a signed integer of type `T` using radix `Radix`, with
     a minimum of `MinDigits` and a maximum of `MaxDigits`.]
  ][
    [``
        int_parser<
            T, Radix, MinDigits, MaxDigits
        >()(num)
    ``]
    [Match the literal `num` of type `T` using radix `Radix`, with
     a minimum of `MinDigits` and a maximum of `MaxDigits`. The parser will fail
     if the parsed value is not equal to the specified value.]
  ]
]

[important All numeric parsers check for overflow conditions based on the type `T`
      the corresponding `int_parser<>` has been instantiated with. If the
      parsed number overflows this type the parsing fails. Please be aware
      that the overflow check is not based on the type of the supplied
      attribute but solely depends on the template parameter `T`.]

[heading Attributes]

[table
  [
    [Expression]
    [Attribute]
  ][
    [``
        lit(num)
     ``]
    [__unused__]
  ][
    [``
        short_
        short_(num)
    ``]
    [`short`]
  ][
    [``
        int_
        int_(num)
    ``]
    [`int`]
  ][
    [``
        long_
        long_(num)
    ``]
    [`long`]
  ][
    [``
        long_long
        long_long(num)
    ``]
    [`boost::long_long_type`]
  ][
    [``
        int_parser<
            T, Radix, MinDigits, MaxDigits
        >()
        int_parser<
            T, Radix, MinDigits, MaxDigits
        >()(num)
    ``]
    [`T`]
  ]
]

[heading Complexity]

[:O(N), where N is the number of digits being parsed plus the sign.]

[heading Minimum Expression Requirements for `T`]

For the numeric base type, `T`, the expression requirements below must be
valid:

[table
    [[Expression]                           [Semantics]]
    [[`T()`]                                [Default construct.]]
    [[`T(0)`]                               [Construct from an `int`.]]
    [[`n + n`]                              [Addition.]]
    [[`n - n`]                              [Subtraction.]]
    [[`n * n`]                              [Multiplication.]]
    [[`std::numeric_limits<T>::is_bounded`] [`true` or `false` if `T` bounded.]]
    [[`std::numeric_limits<T>::digits`]     [Maximum Digits for `T`, radix digits.
                                            Required only if `T` is bounded.]]
    [[`std::numeric_limits<T>::digits10`]   [Maximum Digits for `T`, base 10.
                                            Required only if `T` is bounded.]]
    [[`std::numeric_limits<T>::max()`]      [Maximum value for `T`.
                                            Required only if `T` is bounded.]]
    [[`std::numeric_limits<T>::min()`]      [Minimum value for `T`.
                                            Required only if `T` is bounded.]]
]

[heading Example]

[note The test harness for the example(s) below is presented in the
__qi_basics_examples__ section.]

Some using declarations:

[reference_using_declarations_int]

Basic signed integers:

[reference_int]

[endsect] [/ Signed Integers]

[/------------------------------------------------------------------------------]
[section:real Real Number Parsers (`float_`, `double_`, etc.)]

[heading Description]

The `real_parser` can parse real numbers of arbitrary length and size
limited by its template parameter, `T`. The numeric base type `T` can be
a user defined numeric type such as fixed_point (fixed point reals) and
bignum (unlimited precision numbers) as long as the type follows certain
expression requirements (documented below).

[heading Header]

    // forwards to <boost/spirit/home/qi/numeric/real.hpp>
    #include <boost/spirit/include/qi_real.hpp>

Also, see __include_structure__.

[heading Namespace]

[table
    [[Name]]
    [[`boost::spirit::lit           // alias: boost::spirit::qi::lit`]]
    [[`boost::spirit::float_        // alias: boost::spirit::qi::float_`]]
    [[`boost::spirit::double_       // alias: boost::spirit::qi::double_`]]
    [[`boost::spirit::long_double   // alias: boost::spirit::qi::long_double`]]
]

[note `lit` is reused by the [qi_lit_char Character Parsers], and the Numeric
      Parsers. In general, a char parser is created when you pass in a
      character, and a numeric parser is created when you use a numeric
      literal.]

[heading Synopsis]

    template <typename T, typename RealPolicies>
    struct real_parser;

[heading Template parameters]

[table
    [[Parameter]            [Description]                   [Default]]
    [[`T`]                  [The numeric base type of the
                             numeric parser.]               [none]]
    [[`RealPolicies`]       [Policies control the
                             parser's behavior.]            [`real_policies<T>`]]
]

[heading Model of]

[:__primitive_parser_concept__]

[variablelist Notation
    [[`n`]          [An object of `T`, the numeric base type.]]
    [[`num`]        [Numeric literal, any real value, or a __qi_lazy_argument__
                     that evaluates to a real value.]]
    [[`RP`]         [A `RealPolicies` (type).]]
    [[`exp`]        [A `int` exponent.]]
    [[`b`]          [A `bool` flag.]]
    [[`f`, `l`]     [__fwditer__. first/last iterator pair.]]
]

[heading Expression Semantics]

Semantics of an expression is defined only where it differs from, or is
not defined in __primitive_parser_concept__.

[table
  [
    [Expression]
    [Semantics]
  ][
    [``
        float_
        double_
        long_double
     ``]
    [Parse a real using the default policies (`real_policies<T>`).]
  ][
    [``
        lit(num)
        float_(num)
        double_(num)
        long_double(num)
    ``]
    [Match the literal `num` using the default policies (`real_policies<T>`).
     The parser will fail if the parsed value is not equal to the specified
     value.]
  ][
    [``
        real_parser<
            T, RealPolicies
        >()
    ``]
    [Parse a real of type `T` using `RealPolicies`.]
  ][
    [``
        real_parser<
            T, RealPolicies
        >()(num)
    ``]
    [Match the literal `num` of type `T` using `RealPolicies`. The parser will fail
     if the parsed value is not equal to the specified value.]
  ]
]

[heading Attributes]

[table
  [
    [Expression]
    [Attribute]
  ][
    [``
        lit(num)
     ``]
    [__unused__]
  ][
    [``
        float_
        float_(num)
    ``]
    [`float`]
  ][
    [``
        double_
        double_(num)
    ``]
    [`double`]
  ][
    [``
        long_double
        long_double(num)
    ``]
    [`long double`]
  ][
    [``
        real_parser<
            T, RealPolicies
        >()
        real_parser<
            T, RealPolicies
        >()(num)
    ``]
    [`T`]
  ]
]

[heading Complexity]

[:O(N), where N is the number of characters (including the digits,
exponent, sign, etc.) being parsed.]

[heading Minimum Expression Requirements for `T`]

The numeric base type, `T`, the minimum expression requirements listed
below must be valid. Take note that additional requirements may be
imposed by custom policies.

[table
    [[Expression]                           [Semantics]]
    [[`T()`]                                [Default construct.]]
    [[`T(0)`]                               [Construct from an `int`.]]
    [[`n + n`]                              [Addition.]]
    [[`n - n`]                              [Subtraction.]]
    [[`n * n`]                              [Multiplication.]]
    [[`std::numeric_limits<T>::is_bounded`] [`true` or `false` if `T` bounded.]]
    [[`std::numeric_limits<T>::digits`]     [Maximum Digits for `T`, radix digits.
                                            Required only if `T` is bounded.]]
    [[`std::numeric_limits<T>::digits10`]   [Maximum Digits for `T`, base 10.
                                            Required only if `T` is bounded.]]
    [[`std::numeric_limits<T>::max()`]      [Maximum value for `T`.
                                            Required only if `T` is bounded.]]
    [[`std::numeric_limits<T>::min()`]      [Minimum value for `T`.
                                            Required only if `T` is bounded.]]


    [[`boost::spirit::traits::scale(exp, n)`]
                                            [Multiply `n` by `10^exp`. Default implementation
                                            is provided for `float`, `double` and `long double`.]]

    [[`boost::spirit::traits::negate(b, n)`]
                                            [Negate `n` if `b` is `true`. Default implementation
                                            is provided for `float`, `double` and `long double`.]]

]

[note The additional spirit real number traits above are provided to
allow custom implementations to implement efficient real number parsers.
For example, for certain custom real numbers, scaling to a base 10
exponent is a very cheap operation.]

[heading `RealPolicies`]

The `RealPolicies` template parameter is a class that groups all the
policies that control the parser's behavior. Policies control the real
number parsers' behavior.

The default is `real_policies<T>`. The default is provided to take care
of the most common case (there are many ways to represent, and hence
parse, real numbers). In most cases, the default policies are sufficient
and can be used straight out of the box. They are designed to parse
C/C++ style floating point numbers of the form `nnn.fff.Eeee` where
`nnn` is the whole number part, `fff` is the fractional part, `E` is
`'e'` or `'E'` and `eee` is the exponent optionally preceded by `'-'` or
`'+'` with the additional detection of NaN and Inf as mandated by the
C99 Standard and proposed for inclusion into the C++0x Standard: nan,
nan(...), inf and infinity (the matching is case-insensitive). This
corresponds to the following grammar:

    sign
        =   lit('+') | '-'
        ;

    nan
        =   no_case["nan"]
            >> -('(' >> *(char_ - ')') >> ')')
        ;

    inf
        =   no_case[lit("inf") >> -lit("inity")]
        ;

    floating_literal
        =   -sign >>
            (       nan
                |   inf
                |   fractional_constant >> -exponent_part
                |  +digit >> exponent_part
            )
        ;

    fractional_constant
        =  *digit >> '.' >> +digit
        |  +digit >> -lit('.')
        ;

    exponent_part
        =   (lit('e') | 'E') >> -sign >> +digit
        ;

There are four `RealPolicies` predefined for immediate use:

[table Predefined Policies

    [[Policies]                             [Description]]
    [[`ureal_policies<double>`]             [Without sign.]]
    [[`real_policies<double>`]              [With sign.]]
    [[`strict_ureal_policies<double>`]      [Without sign, dot required.]]
    [[`strict_real_policies<double>`]       [With sign, dot required.]]
]

[note Integers are considered a subset of real numbers, so for instance,
`double_` recognizes integer numbers (without a dot) just as well. To
avoid this ambiguity, `strict_ureal_policies` and `strict_real_policies`
require a dot to be present for a number to be considered a successful
match.]

[heading `RealPolicies` Expression Requirements]

For models of `RealPolicies` the following expressions must be valid:

[table
    [[Expression]                           [Semantics]]
    [[`RP::allow_leading_dot`]              [Allow leading dot.]]
    [[`RP::allow_trailing_dot`]             [Allow trailing dot.]]
    [[`RP::expect_dot`]                     [Require a dot.]]
    [[`RP::parse_sign(f, l)`]               [Parse the prefix sign (e.g. '-').
                                            Return `true` if successful, otherwise `false`.]]
    [[`RP::parse_n(f, l, n)`]               [Parse the integer at the left of the decimal point.
                                            Return `true` if successful, otherwise `false`.
                                            If successful, place the result into `n`.]]
    [[`RP::parse_dot(f, l)`]                [Parse the decimal point.
                                            Return `true` if successful, otherwise `false`.]]
    [[`RP::parse_frac_n(f, l, n)`]          [Parse the fraction after the decimal point.
                                            Return `true` if successful, otherwise `false`.
                                            If successful, place the result into `n`.]]
    [[`RP::parse_exp(f, l)`]                [Parse the exponent prefix (e.g. 'e').
                                            Return `true` if successful, otherwise `false`.]]
    [[`RP::parse_exp_n(f, l, n)`]           [Parse the actual exponent.
                                            Return `true` if successful, otherwise `false`.
                                            If successful, place the result into `n`.]]
    [[`RP::parse_nan(f, l, n)`]             [Parse a NaN.
                                            Return `true` if successful, otherwise `false`.
                                            If successful, place the result into `n`.]]
    [[`RP::parse_inf(f, l, n)`]             [Parse an Inf.
                                            Return `true` if successful, otherwise `false`.
                                            If successful, place the result into `n`.]]
]

The `parse_nan` and `parse_inf` functions get called whenever
a number to parse does not start with a digit (after having
successfully parsed an optional sign).

The functions should return true if a Nan or Inf has been found. In this
case the attribute `n` should be set to the matched value (NaN or Inf).
The optional sign will be automatically applied afterwards.

[heading `RealPolicies` Specializations]

The easiest way to implement a proper real parsing policy is to derive a
new type from the type `real_policies` while overriding the aspects
of the parsing which need to be changed. For example, here's the
implementation of the predefined `strict_real_policies`:

    template <typename T>
    struct strict_real_policies : real_policies<T>
    {
        static bool const expect_dot = true;
    };

[heading Example]

[note The test harness for the example(s) below is presented in the
__qi_basics_examples__ section.]

Some using declarations:

[reference_using_declarations_real]

Basic real number parsing:

[reference_real]

A custom real number policy:

[reference_test_real_policy]

And its use:

[reference_custom_real]

[endsect] [/ Real Numbers]

[/------------------------------------------------------------------------------]
[section:boolean Boolean Parser (`bool_`)]

[heading Description]

The `bool_parser` can parse booleans of arbitrary type, `B`. The boolean base
type `T` can be a user defined boolean type as long as the type follows certain
expression requirements (documented below).

[heading Header]

    // forwards to <boost/spirit/home/qi/numeric/bool.hpp>
    #include <boost/spirit/include/qi_bool.hpp>

Also, see __include_structure__.

[heading Namespace]

[table
    [[Name]]
    [[`boost::spirit::bool_        // alias: boost::spirit::qi::bool_`]]
    [[`boost::spirit::true_        // alias: boost::spirit::qi::true_`]]
    [[`boost::spirit::false_       // alias: boost::spirit::qi::false_`]]
]

[heading Synopsis]

    template <typename T, typename BooleanPolicies>
    struct bool_parser;

[heading Template parameters]

[table
    [[Parameter]            [Description]                   [Default]]
    [[`B`]                  [The boolean type of the
                            boolean parser.]                [`bool`]]
    [[`BooleanPolicies`]    [Policies control the
                            parser's behavior.]             [`bool_policies<B>`]]
]

[heading Model of]

[:__primitive_parser_concept__]

[variablelist Notation
    [[`BP`]         [A boolean `Policies` (type).]]
    [[`b`]          [An object of `B`, the numeric base type.]]
    [[`boolean`]    [Numeric literal, any boolean value, or a
                     __qi_lazy_argument__ that evaluates to a boolean value.]]
    [[`f`, `l`]     [__fwditer__. first/last iterator pair.]]
    [[`attr`]       [An attribute value.]]
    [[`Context`]    [The type of the parse context of the current invocation of
                     the `bool_` parser.]]
    [[`ctx`]        [An instance of the parse context, `Context`.]]
]

[heading Expression Semantics]

Semantics of an expression is defined only where it differs from, or is
not defined in __primitive_parser_concept__.

[table
  [
    [Expression]
    [Semantics]
  ][
    [``
        bool_
     ``]
    [Parse a boolean using the default policies (`bool_policies<T>`).]
  ][
    [``
        lit(boolean)
        bool_(boolean)
    ``]
    [Match the literal `boolean` using the default policies (`bool_policies<T>`).
     The parser will fail if the parsed value is not equal to the specified
     value.]
  ][
    [``
        true_
        false_
    ``]
    [Match `"true"` and `"false"`, respectively.]
  ][
    [``
        bool_parser<
            T, BoolPolicies
        >()
    ``]
    [Parse a real of type `T` using `BoolPolicies`.]
  ][
    [``
        bool_parser<
            T, BoolPolicies
        >()(boolean)
    ``]
    [Match the literal `boolean` of type `T` using `BoolPolicies`. The parser will fail
     if the parsed value is not equal to the specified value.]
  ]
]

[note   All boolean parsers properly respect the __qi_no_case__`[]` directive.]

[heading Attributes]

[table
  [
    [Expression]
    [Attribute]
  ][
    [``
        lit(boolean)
     ``]
    [__unused__]
  ][
    [``
        true_
        false_
        bool_
        bool_(boolean)
    ``]
    [`bool`]
  ][
    [``
        bool_parser<
            T, BoolPolicies
        >()
        bool_parser<
            T, BoolPolicies
        >()(num)
    ``]
    [`T`]
  ]
]

[heading Complexity]

[:O(N), where N is the number of characters being parsed.]

[heading Minimum Expression Requirements for `B`]

The boolean type, `B`, the minimum expression requirements listed
below must be valid. Take note that additional requirements may be
imposed by custom policies.

[table
    [[Expression]                           [Semantics]]
    [[`B(bool)`]                            [Constructible from a `bool`.]]
]

[heading Boolean `Policies`]

The boolean `Policies` template parameter is a class that groups all the
policies that control the parser's behavior. Policies control the boolean
parsers' behavior.

The default is `bool_policies<bool>`. The default is provided to take care
of the most common case (there are many ways to represent, and hence
parse, boolean numbers). In most cases, the default policies are sufficient
and can be used straight out of the box. They are designed to parse
boolean value of the form `"true"` and `"false"`.

[heading Boolean `Policies` Expression Requirements]

For models of boolean `Policies` the following expressions must be valid:

[table
    [[Expression]                      [Semantics]]
    [[`BP::parse_true(f, l, attr)`]    [Parse a `true` value.]]
    [[`BP::parse_false(f, l, attr)`]   [Parse a `false` value.]]
]

The functions should return true if the required representations of `true` or
`false` have been found. In this case the attribute `n` should be set to the
matched value (`true` or `false`).

[heading Boolean `Policies` Specializations]

The easiest way to implement a proper boolean parsing policy is to derive a
new type from the type `bool_policies` while overriding the aspects
of the parsing which need to be changed. For example, here's the
implementation of a boolean parsing policy interpreting the string `"eurt"`
(i.e. "true" spelled backwards) as `false`:

    struct backwards_bool_policies : qi::bool_policies<>
    {
        // we want to interpret a 'true' spelled backwards as 'false'
        template <typename Iterator, typename Attribute>
        static bool
        parse_false(Iterator& first, Iterator const& last, Attribute& attr)
        {
            namespace qi = boost::spirit::qi;
            if (qi::detail::string_parse("eurt", first, last, qi::unused))
            {
                spirit::traits::assign_to(false, attr);    // result is false
                return true;
            }
            return false;
        }
    };

[heading Example]

[note The test harness for the example(s) below is presented in the
__qi_basics_examples__ section.]

Some using declarations:

[reference_using_declarations_bool]

Basic real number parsing:

[reference_bool]

A custom real number policy:

[reference_test_bool_policy]

And its use:

[reference_custom_bool]

[endsect] [/ Real Numbers]

[endsect]