| [/============================================================================== |
| Copyright (C) 2001-2010 Joel de Guzman |
| Copyright (C) 2001-2010 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] |
| |
| 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 Integers (`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::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).] |
| |
| [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 |
| either 2: binary, 8: octal, |
| 10: decimal and 16: hexadecimal.] [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 |
| [[`NP`] [An instance of `uint_parser` (type).]] |
| [[`n`] [An object of `T`, the numeric base type.]] |
| ] |
| |
| [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]] |
| [[`NP()`] [Instantiate and (default) construct a `uint_parser`]] |
| [[`bin`] [Create a `uint_parser<unsigned, 2, 1, -1>`]] |
| [[`oct`] [Create a `uint_parser<unsigned, 8, 1, -1>`]] |
| [[`hex`] [Create a `uint_parser<unsigned, 16, 1, -1>`]] |
| [[`ushort_`] [Create a `uint_parser<unsigned short, 10, 1, -1>`]] |
| [[`ulong_`] [Create a `uint_parser<unsigned long, 10, 1, -1>`]] |
| [[`uint_`] [Create a `uint_parser<unsigned int, 10, 1, -1>`]] |
| [[`ulong_long`] [Create a `uint_parser<unsigned long long, 10, 1, -1>`]] |
| ] |
| |
| [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] |
| |
| [:`T`, The numeric base type of the numeric parser.] |
| |
| [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 Integers (`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::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).] |
| |
| [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 |
| either 2: binary, 8: octal, |
| 10: decimal and 16: hexadecimal.] [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 |
| [[`NP`] [An instance of `int_parser` (type).]] |
| [[`n`] [An object of `T`, the numeric base type.]] |
| ] |
| |
| [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]] |
| [[`NP()`] [Instantiate and (default) construct an `int_parser`]] |
| [[`short_`] [Create an `int_parser<short, 10, 1, -1>`]] |
| [[`long_`] [Create an `int_parser<long, 10, 1, -1>`]] |
| [[`int_`] [Create an `int_parser<int, 10, 1, -1>`]] |
| [[`long_long`] [Create an `int_parser<long long, 10, 1, -1>`]] |
| ] |
| |
| [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] |
| |
| [:`T`, The numeric base type of the numeric parser.] |
| |
| [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 Numbers (`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::float_ // alias: boost::spirit::qi::float_`]] |
| [[`boost::spirit::double_ // alias: boost::spirit::qi::double_`]] |
| [[`boost::spirit::long_double // alias: boost::spirit::qi::long_double`]] |
| ] |
| |
| [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 |
| [[`NP`] [An instance of `real_parser` (type).]] |
| [[`RP`] [A `RealPolicies` (type).]] |
| [[`n`] [An object of `T`, the numeric base 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]] |
| [[`NP()`] [Instantiate and (default) construct an `real_parser`]] |
| [[`float_`] [Create an `real_parser<float, real_policies<T> >`]] |
| [[`double_`] [Create an `real_parser<double, real_policies<T> >`]] |
| [[`long_double`] [Create an `real_parser<long double, real_policies<T> >`]] |
| ] |
| |
| [heading Attributes] |
| |
| [:`T`, The numeric base type of the numeric parser.] |
| |
| [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`.]] |
| |
| [[`boost::spirit::traits::is_equal_to_one(n)`] |
| [Return `true` if `n` is equal to `1.0`. 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 |
| = -lit("1.0#") >> 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)] |
| |
| or |
| |
| [:after a real number of the value 1 (having no exponential |
| part and a fractional part value of 0) has been parsed.] |
| |
| The first call recognizes representations of NaN or Inf starting with a |
| non-digit character (such as NaN, Inf, QNaN etc.). The second call |
| recognizes representation formats starting with a `1.0` (such as |
| `"1.0#NAN"` or `"1.0#INF"` etc.). |
| |
| 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 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`] [An instance of `bool_parser` (type).]] |
| [[`BP`] [A boolean `Policies` (type).]] |
| [[`b`] [An object of `B`, the numeric base type.]] |
| [[`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]] |
| [[`BP()`] [Instantiate and (default) construct a `bool_parser`]] |
| [[`bool_`] [Create a `bool_parser<bool, bool_policies<bool> >`]] |
| [[`true_`] [Create a `bool_parser<bool, bool_policies<bool> >` |
| which is succeeding only after matching `"true"`.]] |
| [[`false_`] [Create a `bool_parser<bool, bool_policies<bool> >` |
| which is succeeding only after matching `"false"`.]] |
| ] |
| |
| [note All boolean parsers properly respect the __qi_no_case__`[]` directive.] |
| |
| [heading Attributes] |
| |
| [:`B`, The boolean type of the boolean parser.] |
| |
| [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, ctx)`] [Parse a `true` value.]] |
| [[`BP::parse_false(f, l, attr, ctx)`] [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 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, typename Context> |
| static bool |
| parse_false(Iterator& first, Iterator const& last, Attribute& attr, Context& ctx) |
| { |
| namespace qi = boost::spirit::qi; |
| if (qi::detail::string_parse("eurt", first, last, qi::unused, qi::unused)) |
| { |
| spirit::traits::assign_to(false, attr, ctx); // 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] |
