Conversion occurs in four 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 uppercase=(str.flags()&std::ios_base::uppercase);

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

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

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

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

• If the type ofval isbool:
  • Ifboolalpha==0, then convertsval to typeint and performs integer output.
  • Ifboolalpha!=0, obtainsstd::use_facet<std::numpunct<CharT>>(str.getloc()).truename() ifval==true orstd::use_facet<std::numpunct<CharT>>(str.getloc()).falsename() ifval==false, and outputs each successive characterc of that string toout with*out++= c. No further processing is done in this case, the function returnsout.
• If the type ofval is an integer type, the first applicable choice of the following is selected:
  • Ifbasefield== oct, will use conversion specifier%o.
  • Ifbasefield== hex&&!uppercase, will use conversion specifier%x.
  • Ifbasefield== hex, will use conversion specifier%X.
  • If the type ofval is signed, will use conversion specifier%d.
  • If the type ofval is unsigned, will use conversion specifier%u.
• For integer types, length modifier is added to the conversion specification if necessary:l forlong andunsignedlong,ll forlonglong andunsignedlonglong(since C++11).
• If the type ofval is a floating-point type, the first applicable choice of the following is selected:

• Iffloatfield==std::ios_base::scientific&&!uppercase, will use conversion specifier%e.
• Iffloatfield==std::ios_base::scientific, will use conversion specifier%E.

• If!uppercase, will use conversion specifier%g.
• Otherwise, will use conversion specifier%G.

Also:

• If the type ofval islongdouble, the length modifierL is added to the conversion specifier.
• If the type ofval is a floating-point typeandfloatfield!=(ios_base::fixed| ios_base::scientific)(since C++11), the precision modifier is added and set tostr.precision(). Otherwise, no precision is specified.

• For both integer and floating-point types, ifshowpos is set, the modifier+ is prepended.
• For integer types, ifshowbase is set, the modifier# is prepended.
• For floating-point types, ifshowpoint is set, the modifier# is prepended.
• If the type ofval isvoid*, will use conversion specifier%p
• A narrow character string is created as if by a call tostd::printf(spec, val) in the "C" locale, wherespec is the chosen conversion specifier.

[edit]Stage 2: locale-specific conversion

• Every characterc obtained in Stage 1, other than the decimal point'.', is converted toCharT by callingstd::use_facet<std::ctype<CharT>>(str.getloc()).widen(c).
• For arithmetic types, the thousands separator character, obtained fromstd::use_facet<std::numpunct<CharT>>(str.getloc()).thousands_sep(), is inserted into the sequence according to the grouping rules provided bystd::use_facet<std::numpunct<CharT>>(str.getloc()).grouping().
• Decimal point characters ('.') are replaced bystd::use_facet<std::numpunct<CharT>>(str.getloc()).decimal_point().

[edit]Stage 3: padding

• The adjustment flag is obtained as if bystd::fmtflags adjustfield=(flags&(std::ios_base::adjustfield)) and examined to identify padding location, as follows:
  • Ifadjustfield==std::ios_base::left, will pad after.
  • Ifadjustfield==std::ios_base::right, will pad before.
  • Ifadjustfield==std::ios_base::internal and a sign character occurs in the representation, will pad after the sign.
  • Ifadjustfield==std::ios_base::internal and Stage 1 representation began with 0x or 0X, will pad after the x or X.
  • Otherwise, will pad before.
• Ifstr.width() is non-zero (e.g.std::setw was just used) and the number ofCharT's after Stage 2 is less thanstr.width(), then copies of thefill character are inserted at the position indicated by padding to bring the length of the sequence tostr.width().

In any case,str.width(0) is called to cancel the effects ofstd::setw.

[edit]Stage 4: output

Every successive characterc from the sequence ofCharT's from Stage 3 is output as if by*out++= c.

[edit]Parameters

[edit]Return value

out

[edit]Notes

The leading zero generated by the conversion specification#o (resulting from the combination ofstd::showbase andstd::oct for example) is not counted as a padding character.

[edit]Example

#include <iostream>#include <locale> // this custom num_put outputs squares of all integers (except long long)struct squaring_num_put:std::num_put<char>{    iter_type do_put(iter_type out,std::ios_base& str,                     char_type fill,long val)const{returnstd::num_put<char>::do_put(out, str, fill, val* val);}     iter_type do_put(iter_type out,std::ios_base& str,                     char_type fill,unsignedlong val)const{returnstd::num_put<char>::do_put(out, str, fill, val* val);}}; int main(){auto& facet=std::use_facet<std::num_put<char>>(std::locale());    facet.put(std::cout,std::cout,'0',2.71);std::cout<<'\n'; std::cout.imbue(std::locale(std::cout.getloc(), new squaring_num_put));std::cout<<6<<' '<<-12<<'\n';}

2.7136 144

#include <iostream>#include <iterator>#include <locale> struct base{long x=10;}; template<class CharT,class Traits>std::basic_ostream<CharT, Traits>&    operator<<(std::basic_ostream<CharT, Traits>& os,const base& b){try{typenamestd::basic_ostream<CharT, Traits>::sentry s(os); if(s){std::ostreambuf_iterator<CharT, Traits> it(os);std::use_facet<std::num_put<CharT>>(os.getloc())                .put(it, os, os.fill(), b.x);}}catch(...){// set badbit on os and rethrow if required} return os;} int main(){    base b;std::cout<< b;}

10

[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
• Русский
• 中文