Unsigned Integer Parsers (uint_, etc.)

| Home | Libraries | People | FAQ | More

##### Unsigned Integer Parsers (`uint_`, etc.)

###### 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.

###### Header

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

Also, see Include Structure.

###### Namespace

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 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.

###### Synopsis

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

###### Template parameters

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

###### Model of

> `PrimitiveParser`

Notation

`n`

  An object of `T`, the numeric base type.

`num`

  Numeric literal, any unsigned integer value, or a Lazy Argument that evaluates to a unsigned integer value.

###### Expression Semantics

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

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`.

###### Attributes

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`

###### Complexity

> O(N), where N is the number of digits being parsed.

###### Minimum Expression Requirements for `T`

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

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.

###### Example

| Note
The test harness for the example(s) below is presented in the Basics Examples section.

Some using declarations:

    using boost::phoenix::val;
    using boost::spirit::qi::lit;
    using boost::spirit::qi::uint_;
    using boost::spirit::qi::uint_parser;

Basic unsigned integers:

    // unsigned int
    test_parser("12345", uint_);
    test_parser("12345", uint_(12345));
    test_parser("12345", uint_(val(12345)));

    // literals
    test_parser("12345", lit(12345));
    test_parser("12345", lit(val(12345)));

Thousand separated number parser:

    uint_parser<unsigned, 10, 1, 3> uint3_p;        //  1..3 digits
    uint_parser<unsigned, 10, 3, 3> uint3_3_p;      //  exactly 3 digits
    test_parser("12,345,678", uint3_p >> *(',' >> uint3_3_p));