num_get

public member function
<locale>

std::num_get::get

bool (1)
iter_type get (iter_type in, iter_type end, ios_base& str,
               ios_base::iostate& err, bool& val) const;
long (2)
iter_type get (iter_type in, iter_type end, ios_base& str,
               ios_base::iostate& err, long& val) const;
unsigned short (3)
iter_type get (iter_type in, iter_type end, ios_base& str,
               ios_base::iostate& err, unsigned short& val) const;
unsigned int (4)
iter_type get (iter_type in, iter_type end, ios_base& str,
               ios_base::iostate& err, unsigned int& val) const;
unsigned long (5)
iter_type get (iter_type in, iter_type end, ios_base& str,
               ios_base::iostate& err, unsigned long& val) const;
float (6)
iter_type get (iter_type in, iter_type end, ios_base& str,
               ios_base::iostate& err, float& val) const;
double (7)
iter_type get (iter_type in, iter_type end, ios_base& str,
               ios_base::iostate& err, double& val) const;
long double (8)
iter_type get (iter_type in, iter_type end, ios_base& str,
               ios_base::iostate& err, long double& val) const;
pointer (9)
iter_type get (iter_type in, iter_type end, ios_base& str,
               ios_base::iostate& err, void*& val) const;
bool (1)
iter_type get (iter_type in, iter_type end, ios_base& str,
               ios_base::iostate& err, bool& val) const;
long (2)
iter_type get (iter_type in, iter_type end, ios_base& str,
               ios_base::iostate& err, long& val) const;
unsigned short (3)
iter_type get (iter_type in, iter_type end, ios_base& str,
               ios_base::iostate& err, unsigned short& val) const;
unsigned int (4)
iter_type get (iter_type in, iter_type end, ios_base& str,
               ios_base::iostate& err, unsigned int& val) const;
unsigned long (5)
iter_type get (iter_type in, iter_type end, ios_base& str,
               ios_base::iostate& err, unsigned long& val) const;
float (6)
iter_type get (iter_type in, iter_type end, ios_base& str,
               ios_base::iostate& err, float& val) const;
double (7)
iter_type get (iter_type in, iter_type end, ios_base& str,
               ios_base::iostate& err, double& val) const;
long double (8)
iter_type get (iter_type in, iter_type end, ios_base& str,
               ios_base::iostate& err, long double& val) const;
pointer (9)
iter_type get (iter_type in, iter_type end, ios_base& str,
               ios_base::iostate& err, void*& val) const;
long long (10)
iter_type get (iter_type in, iter_type end, ios_base& str,
               ios_base::iostate& err, long long& val) const;
unsigned long long (11)
iter_type get (iter_type in, iter_type end, ios_base& str,
               ios_base::iostate& err, unsigned long long& val) const;
Get numeric value
Parses the sequence of characters between in and end for a numerical value, and stores it into v. For the process, it uses the formatting options selected in str (using its ios_base::fmtflags value), and updates err with the error status when necessary.

The function stops reading characters from the sequence as soon as one character cannot be part of a valid numerical expression (or end is reached). The next character in the sequence is pointed by the iterator returned by the function.

A ios_base::iostate bitmask value is stored in err with the result of the operation:
value in errvalue in valdescription
goodbitthe value readSuccess (without reaching end).
failbitunspecifiedFailure: The sequence of characters did not match the expected format
eofbitone of the aboveend was reached during the operation (this can happen both in case of success or failure).
value in errvalue in valdescription
unchangedthe value readSuccess (without reaching end).
failbitzeroThe sequence did not match the expected format
numeric_limits::max()The sequence represents a value too large for the type of val
numeric_limits::lowest()The sequence represents a value too large negative for the type of val
eofbitone of the aboveend was reached during the operation (this can happen both in case of success or failure)

Internally, this function simply calls the virtual protected member do_get, which by default parses the numerical value following the same format as scanf does for the format specifier that corresponds to the type of argument val taking into account str's format flags. The function uses the locale selected in str to obtain format details (through facet numpunct) and to widen characters (with ctype::widen).

Parameters

in, end
Iterators pointing to the beginning and end characters of the sequence. The range used is [in,end), which contains all the characters between in and end, including the character pointed by in but not the character pointed by end.
Member type iter_type is the facet's iterator type (defined as an alias of num_get's second template parameter, InputIterator). By default, this is an istreambuf_iterator, allowing implicit conversions from basic_istream objects.
str
Object of a class derived from ios_base (generally an input stream object). It is only used to obtain formatting information.
err
Stream error state object, of type ios_base::iostate where the resulting state is stored.
val
Element of a numerical type.
The function stores the value in it if it successfully extracts a number (i.e. if err's failbit flag is not set).

Return value

The next character in the sequence right after where the extraction operation ended.
Member type iter_type is the facet's iterator type (defined as an alias of num_get's second template parameter, InputIterator).

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// num_get example
#include <iostream>       // std::cin, std::cout, std::ios
#include <locale>         // std::locale, std::num_get, std::use_facet
#include <iterator>       // std::istreambuf_iterator
#include <string>         // std::string

int main ()
{
  std::locale loc;
  std::ios::iostate state;
  float mypi,yourpi;

  std::string number ("3.14159");
  // get from string:
  std::use_facet<std::num_get<char,std::string::iterator> > (loc).get
    (number.begin(), number.end(), std::cin, state, mypi);

  std::cout << "Please, enter PI: ";
  // get from istream:
  std::use_facet<std::num_get<char> >(loc).get
    (std::cin, std::istreambuf_iterator<char>(), std::cin, state, yourpi);

  if ( (mypi-yourpi>0.01) || (mypi-yourpi<-0.01) )
    std::cout << "Wrong!\n";
  else
    std::cout << "Right!\n";

  return 0;
}


Possible output:

Please, enter PI: 3.14
Right!

Data races

The object, and up to the entire range between in and end, are accessed.
Arguments str, err and val may be modified.

Exception safety

If an exception is thrown, there are no changes in the facet object, although some of arguments may have been affected.

See also