Name

num_get class template — Facet for input of numbers

Synopsis

template <typename charT,
          typename 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 in, iter_type end, ios_base&, 
                ios_base::iostate& err, bool& v) const;
  iter_type get(iter_type in, iter_type end, ios_base&,
                ios_base::iostate& err, long& v) const;
  iter_type get(iter_type in, iter_type end, ios_base&,
                ios_base::iostate& err, unsigned short& v) const;
  iter_type get(iter_type in, iter_type end, ios_base&,
                ios_base::iostate& err, unsigned int& v) const;
  iter_type get(iter_type in, iter_type end, ios_base&,
                ios_base::iostate& err, unsigned long& v) const;
  iter_type get(iter_type in, iter_type end, ios_base&,
                ios_base::iostate& err, float& v) const;
  iter_type get(iter_type in, iter_type end, ios_base&,
                ios_base::iostate& err, double& v) const;
  iter_type get(iter_type in, iter_type end, ios_base&,
                ios_base::iostate& err, long double& v) const;
  iter_type get(iter_type in, iter_type end, ios_base&,
                ios_base::iostate& err, void*& v) const;
  static locale::id id;
protected:
  virtual ~num_get(  );
  virtual iter_type do_get(iter_type, iter_type, ios_base&,
                           ios_base::iostate& err, bool& v) const;
  virtual iter_type do_get(iter_type, iter_type, ios_base&,
                           ios_base::iostate& err, long& v) const;
  virtual iter_type do_get(iter_type, iter_type, ios_base&,
                           ios_base::iostate& err, unsigned short& v) const;
  virtual iter_type do_get(iter_type, iter_type, ios_base&,
                            ios_base::iostate& err, unsigned int& v) const;
  virtual iter_type do_get(iter_type, iter_type, ios_base&,
                           ios_base::iostate& err, unsigned long& v) const;
  virtual iter_type do_get(iter_type, iter_type, ios_base&,
                           ios_base::iostate& err, float& v) const;
  virtual iter_type do_get(iter_type, iter_type, ios_base&,
                           ios_base::iostate& err, double& v) const;
  virtual iter_type do_get(iter_type, iter_type, ios_base&,
                           ios_base::iostate& err, long double& v) const;
  virtual iter_type do_get(iter_type, iter_type, ios_base&,
                           ios_base::iostate& err, void*& v) const;
};

The num_get class template is a facet for parsing and reading numeric values from an input stream. The istream extraction operators (>>) use num_get. The num_get<char> and num_get<wchar_t> instantiations are standard.

As with other facets, the public members call virtual, protected members with the same name prefaced by do_. Thus, to use the facet, call the public functions, such as get, which calls do_get. The descriptions below are for the virtual functions because they do the real work. Imagine that for each virtual function description, there is a corresponding description for a public, nonvirtual function, such as:

iter_type get (iter_type begin, iter_type end, ios_base& stream, ios_base::iostate& err, bool& v) const

Returns do_get(begin, end, stream, err, v)

The following are the virtual, protected members of num_get:

virtual iter_type do_get (iter_type begin, iter_type end, ios_base& stream, ios_base::iostate& err, bool& v) const

Reads a bool value, which can be represented as a number or as a character string. The function first tests the boolalpha flag, that is, stream.flags( ) & stream.boolalpha. If the flag is 0, a numeric value is read; if the flag is 1, a string is read from [begin, end).

If boolalpha is false, the input is interpreted as a long int. If the numeric value is 1, v is assigned true; if the value is 0, v is assigned false; otherwise, failbit is set in err, and v is not modified.

If boolalpha is true, characters are read from begin until one of the following happens:

virtual iter_type do_get (iter_type begin, iter_type end, ios_base& stream, ios_base::iostate& err, type & v) const

Reads a single value. The do_get function is overloaded for most of the fundamental types. The behavior of each function is essentially the same (except for the bool version described earlier) and depends on stream.flags( ), the ctype facet, and the numpunct facet. Both facets are obtained for the locale stream.getloc( ).

First, input characters are collected from the range [begin, end) or until the input character is not part of a valid number according to the flags and numpunct facet. A locale-dependent decimal point is replaced with the character '.'. Thousands separators are read but not checked for valid positions until after the entire number has been read. The set of valid characters depends on the type of v and the flags, in particular the basefield flags. If stream.flags( ) & basefield is hex, hexadecimal characters are read; if it is oct, only octal characters are read ('0'-'7'). If the basefield is 0, the prefix determines the radix: 0x or 0X for hexadecimal, 0 for octal, and anything else for decimal. Floating-point numbers can use fixed or exponential notation, regardless of the flags.

See Also

If v is of type void*, the format is implementation-defined in the same manner as the %p format for scanf (in <cstdio>).

After all the valid characters have been read, they are interpreted as a numeric value. If the string is invalid, or if the thousands groupings are incorrect, failbit is set in err and v is not changed. If the string is valid, its numeric value is stored in v and err is set to goodbit. If the entire input stream is read (up to end), eofbit is set in err.