Apache C++ Standard Library Reference Guide

## num_get

Library: Localization

    num_get  locale::facet

- Local Index
- Summary
- Synopsis
- Specializations
- Description
- Interface
- Member Types
- Constructors
- Facet ID
- Public Member Functions
- Protected Member Functions
- Example
- See Also
- Standards Conformance

### Local Index

#### Members

char_type do_get() | get() id | iter_type num_get() |

### Summary

A numeric parsing facet

### Synopsis

    #include <locale>

    namespace std {
      template <class charT, class InputIterator> class num_get;
    }

### Specializations

The primary template can be implicitly or explicitly specialized on any character type that satisfies the requirements on the type of the character used by iostream class templates, and on any iterator type that satisfies the requirements of Input Iterator.

### Description

The num_get facet includes facilities for the parsing of sequences of characters and interpreting them as numeric values. basic_istream and all other input-oriented streams use this facet to implement formatted numeric input.

### Interface

    namespace std {

      template <class charT, class InputIterator =
        istreambuf_iterator<charT> >
      class num_get : public locale::facet {

        public:
        typedef charT char_type;
        typedef InputIterator iter_type;
        explicit num_get(size_t refs = 0);
        iter_type get(iter_type, iter_type, ios_base&,
                      ios_base::iostate&, bool&) const;
        iter_type get(iter_type, iter_type, ios_base&,
                      ios_base::iostate&, long&) const;
        iter_type get(iter_type, iter_type, ios_base&,
                      ios_base::iostate&, unsigned short&) const;
        iter_type get(iter_type, iter_type, ios_base&,
                      ios_base::iostate&, unsigned int&) const;
        iter_type get(iter_type, iter_type, ios_base&,
                      ios_base::iostate&, unsigned long&) const;
        iter_type get(iter_type, iter_type, ios_base&,
                      ios_base::iostate&, float&) const;
        iter_type get(iter_type, iter_type, ios_base&,
                      ios_base::iostate&, double&) const;
        iter_type get(iter_type, iter_type, ios_base&,
                      ios_base::iostate&, long double&) const;
        iter_type get(iter_type in, iter_type end, ios_base&,
                      ios_base::iostate&, void*&) const;

        static locale::id id;

        protected:
        virtual iter_type do_get(iter_type, iter_type, ios_base&,
                                 ios_base::iostate&, bool&) const;
        virtual iter_type do_get(iter_type, iter_type, ios_base&,
                                 ios_base::iostate&, long&) const;
        virtual iter_type do_get(iter_type, iter_type, ios_base&,
                                 ios_base::iostate&,
                                 unsigned short&) const;
        virtual iter_type do_get(iter_type, iter_type, ios_base&,
                                 ios_base::iostate&,
                                 unsigned int&) const;
        virtual iter_type do_get(iter_type, iter_type, ios_base&,
                                 ios_base::iostate&,
                                 unsigned long&) const;
        virtual iter_type do_get(iter_type, iter_type, ios_base&,
                                 ios_base::iostate&, float&)
                                 const;
        virtual iter_type do_get(iter_type, iter_type, ios_base&,
                                 ios_base::iostate&, double&)
                                 const;
        virtual iter_type do_get(iter_type, iter_type, ios_base&,
                                 ios_base::iostate&,
                                 long double&) const;
        virtual iter_type do_get(iter_type, iter_type, ios_base&,
                                 ios_base::iostate&, void*&) const;
      };
    }

### Member Types

    char_type

Type of the first template argument.

    iter_type

Type of the second template argument.

### Constructors

    explicit num_get(size_t refs = 0)

Constructs a num_get object. Calls `locale::facet (refs)`.

The `refs` argument is set to the initial value of the num_get object's reference count. A num_get object `f` constructed with `(refs == 0)` that is installed in one or more locale objects will be destroyed and the storage it occupies will be deallocated when the last locale object containing the facet is destroyed, as if by calling `delete static_cast<locale::facet*>(&f)`. A num_get object constructed with `(refs != 0)` will not be destroyed by any locale objects in which it may have been installed.

### Facet ID

    static locale::id id;

Unique identifier for this type of facet.

### Public Member Functions

The public members of the num_get facet include an interface to protected members. Each public member `get()` calls the corresponding protected virtual member function `do_get()`.

    iter_type
    get(iter_type in, iter_type end, ios_base& io,
        ios_base::iostate& err, bool& v) const;
    iter_type
    get(iter_type in, iter_type end, ios_base& io,
        ios_base::iostate& err, long& v) const;
    iter_type
    get(iter_type in, iter_type end, ios_base& io,
        ios_base::iostate& err, unsigned short& v) const;
    iter_type
    get(iter_type in, iter_type end, ios_base& io,
        ios_base::iostate& err, unsigned int& v) const;
    iter_type
    get(iter_type in, iter_type end, ios_base& io,
        ios_base::iostate& err, unsigned long& v) const;
    iter_type
    get(iter_type in, iter_type end, ios_base& io,
        ios_base::iostate& err, float& v) const;
    iter_type
    get(iter_type in, iter_type end, ios_base& io,
        ios_base::iostate& err, double& v) const;
    iter_type
    get(iter_type in, iter_type end, ios_base& io,
        ios_base::iostate& err, long double& v) const;
    iter_type
    get(iter_type in, iter_type end, ios_base& io,
        ios_base::iostate& err, void*& v) const;

Each overload of the `get()` function calls the corresponding protected virtual `do_get()` function.

### Protected Member Functions

    virtual iter_type
    do_get(iter_type in, iter_type end, ios_base& io,
           ios_base::iostate& err, long& v) const;
    virtual iter_type
    do_get(iter_type in, iter_type end, ios_base& io,
           ios_base::iostate& err,
           unsigned short& v) const;
    virtual iter_type
    do_get(iter_type in, iter_type end, ios_base& io,
           ios_base::iostate& err,
           unsigned int& v) const;
    virtual iter_type
    do_get(iter_type in, iter_type end, ios_base& io,
           ios_base::iostate& err,
           unsigned long& v) const;
    virtual iter_type
    do_get(iter_type in, iter_type end, ios_base& io,
           ios_base::iostate& err, float& v) const;
    virtual iter_type
    do_get(iter_type in, iter_type end, ios_base& io,
           ios_base::iostate& err, double& v) const;
    virtual iter_type
    do_get(iter_type in, iter_type end, ios_base& io,
           ios_base::iostate& err, long double& v) const;
    virtual iter_type
    do_get(iter_type in, iter_type end, ios_base& io,
           ios_base::iostate& err, void*& v) const;

All overloads of the `do_get()` member function take a sequence of characters `[in,end)`, and attempt to extract a numeric value. On success, the numeric value is returned in `v`, and `err` is set to `ios_base::goodbit`; otherwise `v` is left unchanged and `err` is set to `ios_base::failbit`. The functions return an iterator pointing just past the last extracted character.

The `io` argument is used to obtain a reference to the numpunct<char_type> facet installed in the object's locale and containing locale-specific punctuation data (grouping, if any, the character used as the thousands separator, and the character used as the decimal point), to obtain a reference to the ctype<char_type> facet installed in the same locale needed to interpret the parsed characters, and to obtain information necessary to determine which base to use to interpret the parsed digits. Input in base 1 through 36 is accepted. Base of 1 accepts Roman numerals between 1 and 4999, inclusive. Use `ios_base::oct`, `dec`, `hex`, and the extension of this implementation, `ios_base::bin`, to set the base to 8, 10, 16, and 2, respectively. Use the `std::setbase()` manipulator declared in `<iomanip>` to set base other than 2, 8, 10, and 16. If the functions reach the end of the input sequence while attempting to extract additional characters, they set `ios_base::eofbit in err`.

If `use_facet<numpunct<char_type> >(io.getloc()).grouping()` returns a non-empty string, the positions of any characters found in the input sequence prior to the character returned by `use_facet<numpunct<char_type> >(io.getloc()).decimal_point()`, if any, which match that returned by `use_facet<numpunct<char_type> >(io.getloc()).thousands_sep()` are checked for consistency with the grouping string. The functions indicate inconsistencies in the placement of thousands separators by setting `err` to `ios_base::failbit`. If the grouping is empty, the first thousands separator terminates input.

Except for the optional grouping, the format of interpreted sequences is the same as that accepted by the scanf() function declared in <cstdio>.

If after a successful extraction of a numeric value the function determines that the value is not representable in the type `T` of the argument `v`, (i.e., the function detects an arithmetic overflow), it stores numeric_limits<T>`::min()` or `max()` in `v`, for positive and negative integer overflow, respectively, and `+/-numeric_limits<T>::infinity()` for positive and negative floating point overflow, respectively, and sets `ios_base::failbit` in `err`.

If the function determines that the value is too small to be accurately represented in the type `T` of the argument `v`, (i.e., the function detects a floating point underflow) the function stores `+/-numeric_limits<T>::min()` in `v` without setting `ios_base::eofbit` in `err`.

    virtual iter_type
    do_get(iter_type in, iter_type end, ios_base& io,
           ios_base::iostate& err, bool& v) const;

If `(io.flags() & ios_base::boolalpha)` evaluates to non-zero, the function attempts to match characters extracted from the input sequence against consecutive characters of the strings returned from `use_facet<numpunct<char_type> >(io.getloc()).falsename()` and `truename()`. Upon a successful match the function stores in `v` the value `false` or `true`, respectively. In the case of ambiguity, the function stores `false`.

If `(io.flags() & ios_base::boolalpha)` evaluates to zero, the function behaves the same as the long overload of `do_get()`, except that if the extracted value is `0`, it stores `false`; if the extracted value is `1`, it stores `true`; otherwise the function set `ios_base::eofbit` in `err` and leaves `v` unmodified.

### Example

    #include <iostream>   // for cout, endl
    #include <sstream>    // for istringstream
    #include <string>     // for string

    int main ()
    {
        typedef std::istreambuf_iterator<char, std::char_traits<char> > Iter;

        std::ios::iostate state;
        Iter              end;

        bool        bval  = false;
        long        lval  = 0L;
        long double ldval = 0.0;

        const std::locale loc;

        // Get a num_get facet
        const std::num_get<char, Iter> &ng =
            std::use_facet<std::num_get<char, Iter> >(loc);

    #ifndef _RWSTD_NO_BOOL
        {
            // Build an istringstream from the buffer and construct
            // beginning and ending iterators on it.
            std::istringstream ins ("true");
            Iter begin (ins);

            // Set stream flags to recognize boolalpha input.
            ins.setf (std::ios::boolalpha);

            // Get the boolean value from the stream.
            ng.get (begin, end, ins, state, bval);
        }
    #endif

        std::cout << bval << std::endl;

        {
            // Get the date
            std::istringstream ins ("2422235");
            Iter begin (ins);
            ng.get (begin, end, ins, state, lval);
        }

        std::cout << lval << std::endl;

        {
            // Get the weekday
            std::istringstream ins ("32324342.98908");
            Iter begin (ins);
            ng.get (begin, end, ins, state, ldval);
        }

        std::cout.setf (std::ios::fixed, std::ios::floatfield);
        std::cout << ldval << std::endl;

        return 0;
    }

    Program Output:
    1
    2422235
    32324342.989080

### See Also

ctype, locale, Facets, numpunct, num_put

### Standards Conformance

ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 22.2.2.1