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

Members

char_type do_get()

get() id

iter_type num_get()

A numeric parsing facet

#include <locale>

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

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.

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.

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;
  };
}

char_type

Type of the first template argument.

iter_type

Type of the second template argument.

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.

static locale::id id;

Unique identifier for this type of facet.

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.

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.

#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

ctype, locale, Facets, numpunct, num_put

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