Conversion occurs in three stages:

[edit]Stage 1: conversion specifier selection

• I/O format flags are obtained, as if by

fmtflags basefield=(str.flags()&std::ios_base::basefield);

fmtflags boolalpha=(str.flags()&std::ios_base::boolalpha);

• If the type ofv is an integer type, the first applicable choice of the following five is selected:

Ifbasefield== oct, will use conversion specifier%o

Ifbasefield== hex, will use conversion specifier%X

Ifbasefield==0, will use conversion specifier%i

If the type ofv is signed, will use conversion specifier%d

If the type ofv is unsigned, will use conversion specifier%u

• For integer types, length modifier is added to the conversion specification if necessary:h forshort andunsignedshort,l forlong andunsignedlong,ll forlonglong andunsignedlonglong(since C++11)
• If the type ofv isfloat, will use conversion specifier%g
• If the type ofv isdouble, will use conversion specifier%lg
• If the type ofv islongdouble, will use conversion specifier%Lg
• If the type ofv isvoid*, will use conversion specifier%p
• If the type ofv isbool andboolalpha==0, proceeds as if the type ofv islong, except for the value to be stored inv in stage 3.
• If the type ofv isbool andboolalpha!=0, the following replaces stages 2 and 3:
  • Successive characters obtained from the input iteratorin are matched against the character sequences obtained fromstd::use_facet<std::numpunct<CharT>>(str.getloc()).falsename() andstd::use_facet<std::numpunct<CharT>>(str.getloc()).truename() only as necessary as to identify the unique match. The input iteratorin is compared toend only when necessary to obtain a character.
  • If the target sequence is uniquely matched,v is set to the correspondingbool value. Otherwisefalse is stored inv andstd::ios_base::failbit is assigned toerr. If unique match could not be found before the input ended (in== end),err|=std::ios_base::eofbit is executed.

[edit]Stage 2: character extraction

• Ifin== end, stage 2 is terminated immediately, no further characters are extracted.
• The next character is extracted fromin as if bychar_type ct=*in;:
  • If the character matches one of"0123456789abcdefxABCDEFX+-"(until C++11)"0123456789abcdefpxABCDEFPX+-"(since C++11), widened to the locale's char_type as if bystd::use_facet<std::ctype<CharT>>(str.getloc()).widen(), it is converted to the correspondingchar.
  • If the character matches the decimal point separator (std::use_facet<std::numpunct<CharT>>(str.getloc()).decimal_point())), it is replaced by'.'.
  • If the character matches the thousands separator (std::use_facet<std::numpunct<CharT>>(str.getloc()).thousands_sep()) and the thousands separation is in use (as determined bystd::use_facet<std::numpunct<CharT>>(str.getloc()).grouping().length()!=0), then if the decimal point'.' has not yet been accumulated, the position of the character is remembered, but the character is otherwise ignored. If the decimal point has already been accumulated, the character is discarded and stage 2 terminates.
  • In any case, the check is made whether thechar obtained from the previous steps is allowed in the input field that would be parsed bystd::scanf given the conversion specifier selected in stage 1. If it is allowed, it is accumulated in a temporary buffer and stage 2 repeats. If it is not allowed, stage 2 terminates.

[edit]Stage 3: conversion and storage

• The sequence ofchars accumulated in stage 2 is converted to a numeric value:

• If the conversion function fails to convert the entire field, the value​0​ is stored inv.
• If the type ofv is a signed integer type and the conversion function results in a positive or negative value too large to fit in it, the most positive or negative representable value is stored inv, respectively.
• If the type ofv is an unsigned integer type and the conversion function results in a value that does not fit in it, the most positive representable value is stored inv.
• In any case, if the conversion function failsstd::ios_base::failbit is assigned toerr.
• Otherwise, the numeric result of the conversion is stored inv.
  • If the type ofv isbool and boolalpha is not set, then if the value to be stored is​0​,false is stored, if the value to be stored is1,true is stored, for any other valuestd::ios_base::failbit is assigned toerr andtrue is stored.
• After this, digit grouping is checked. if the position of any of the thousands separators discarded in stage 2 does not match the grouping provided bystd::use_facet<std::numpunct<CharT>>(str.getloc()).grouping(),std::ios_base::failbit is assigned toerr.
• If stage 2 was terminated by the testin== end,err|=std::ios_base::eofbit is executed to set the eof bit.

[edit]Return value

in

[edit]Notes

Before the resolutions ofLWG issue 23 andLWG issue 696,v was left unchanged if an error occurs.

Before the resolution ofLWG issue 221, strings representing hexadecimal integers (e.g."0xA0") were rejected bydo_get(int) even if they are valid input tostrtol because stage 2 filters out characters'X' and'x'.

Before the resolution ofLWG issue 1169, converting a negative number string into an unsigned integer might produce zero (since the value represented by the string is smaller than what the target type can represent).

[edit]Example

#include <iostream>#include <iterator>#include <locale> struct base{long x;}; template<class CharT,class Traits>std::basic_istream<CharT, Traits>&    operator>>(std::basic_istream<CharT, Traits>& is, base& b){std::ios_base::iostate err=std::ios_base::goodbit; try// setting err could throw{typenamestd::basic_istream<CharT, Traits>::sentry s(is); if(s)// if stream is ready for inputstd::use_facet<std::num_get<CharT>>(is.getloc()).get(is,{}, is, err, b.x);}catch(std::ios_base::failure& error){// handle the exception} return is;} int main(){    base b;std::cin>> b;}

[edit]Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

[edit]See also

• In other languages

• Deutsch
• Español
• Français
• Italiano
• 日本語
• Português
• Русский
• 中文