std::num_put<CharT,OutputIt>:: put, std::num_put<CharT,OutputIt>:: do_put

Conversion occurs in four stages:

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 of val is bool :
  • If boolalpha == 0 , then converts val to type int and performs integer output.
  • If boolalpha ! = 0 , obtains std:: use_facet < std:: numpunct < CharT >> ( str. getloc ( ) ) . truename ( ) if val == true or std:: use_facet < std:: numpunct < CharT >> ( str. getloc ( ) ) . falsename ( ) if val == false , and outputs each successive character c of that string to out with * out ++ = c . No further processing is done in this case, the function returns out .
• If the type of val is an integer type, the first applicable choice of the following is selected:
  • If basefield == oct , will use conversion specifier % o
  • If basefield == hex && ! uppercase , will use conversion specifier % x
  • If basefield == hex , will use conversion specifier % X
  • If the type of val is signed, will use conversion specifier % d
  • If the type of val is unsigned, will use conversion specifier % u
• For integer types, length modifier is added to the conversion specification if necessary: l for long and unsigned long , ll for long long and unsigned long long (since C++11) .
• If the type of val is a floating-point type, the first applicable choice of the following is selected:
  • If floatfield == std:: ios_base :: fixed , will use conversion specifier % f
  • If floatfield == std:: ios_base :: scientific && ! uppercase , will use conversion specifier % e
  • If floatfield == 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 of val is long double , the length modifier L is added to the conversion specifier.
• If the type of val is a floating-point type and floatfield ! = ( ios_base :: fixed | ios_base :: scientific ) (since C++11) , the precision modifier is added and set to str. precision ( ) . Otherwise, no precision is specified.

• For both integer and floating-point types, if showpos is set, the modifier + is prepended
• For integer types, if showbase is set, the modifier # is prepended.
• For floating-point types, if showpoint is set, the modifier # is prepended.
• If the type of val is void * , will use conversion specifier % p
• A narrow character string is created as if by a call to std:: printf ( spec, val ) in the "C" locale, where spec is the chosen conversion specifier.

Stage 2: locale-specific conversion

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

Stage 3: padding

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

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

Stage 4: output

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

Parameters

Return value

out

Notes

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

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
    {
        return std::num_put<char>::do_put(out, str, fill, val * val);
    }
 
    iter_type do_put(iter_type out, std::ios_base& str,
                     char_type fill, unsigned long val) const
    {
        return std::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.71
36 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, base const& b)
{
    try
    {
        typename std::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

Defect reports

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

See also