Name

num_put class template — Facet for output of numbers

Synopsis

template <typename charT,
          typename OutputIterator = ostreambuf_iterator<charT> >
class num_put : public locale::facet
{
public:
  typedef charT char_type;
  typedef OutputIterator iter_type;
  explicit num_put(size_t refs = 0);
  iter_type put(iter_type s, ios_base& f, char_type fill, bool v) const;
  iter_type put(iter_type s, ios_base& f, char_type fill, long v) const;
  iter_type put(iter_type s, ios_base& f, char_type fill, unsigned long v) const;
  iter_type put(iter_type s, ios_base& f, char_type fill, double v) const;
  iter_type put(iter_type s, ios_base& f, char_type fill, long double v) const;
  iter_type put(iter_type s, ios_base& f, char_type fill, const void* v) const;
  static locale::id id;
protected:
  virtual ~num_put(  );
  virtual iter_type do_put(iter_type, ios_base&, char_type fill, bool v) const;
  virtual iter_type do_put(iter_type, ios_base&, char_type fill, long v) const;
  virtual iter_type do_put(iter_type, ios_base&, char_type fill, unsigned long)
    const;
  virtual iter_type do_put(iter_type, ios_base&, char_type fill, double v) const;
  virtual iter_type do_put(iter_type, ios_base&, char_type fill, long double v)
    const;
  virtual iter_type do_put(iter_type, ios_base&, char_type fill, const void* v)
    const;
};

The num_put class template is a facet for formatting and outputing a numeric value. The ostream output operators (>>) use num_put. The num_put<char> and num_put<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 put, which calls do_put. 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 put (iter_type out, ios_base& stream, char_type fill, bool v) const

Returns do_put(out, stream, fill, v)

The following are the virtual, protected members of num_put:

virtual iter_type do_put (iter_type out, ios_base& stream, char_type fill, bool v) const

Writes a bool value to out. If the boolalpha flag is clear, that is, stream.flags( ) & stream.boolalpha is 0, the integer value of v is written as a number. If boolalpha is set, v is written as a word: if v is true, truename( ) is written; if v is false, falsename( ) is written using the numpunct facet. For example:

const numpunct<charT>& n = use_facet<numpunct<charT> >;
string_type s = v ? n.truename(  ) : n.falsename(  );
// Write characters of s to out.
virtual iter_type do_put (iter_type out, ios_base& stream, char_type fill, type v) const

Formats v as a string and writes the string contents to out using the flags of stream to control the formatting and the imbued locale of stream to obtain the ctype and numpunct facets for punctuation rules and characters. The format also depends on type:

Integral types (long, unsigned long)

The format depends on the basefield flags (stream.flags( ) & basefield). If oct, the number is formatted as octal; if hex, the number is formatted as hexadecimal (using 'a'-'f' for the digits 10-16, or 'A'-'F' if the uppercase flag is set); or else the number is decimal. If the showbase flag is set, a prefix is used: 0 for octal, or 0x or 0X for hexadecimal (depending on the uppercase flag).

Floating-point types (double, long double)

The format depends on the floatfield flags (stream.flags( ) & floatfield). If fixed, the format is fixed-point: an integer part, a decimal point, and a fractional part. If scientific, the format is exponential.

If the floatfield flags do not indicate fixed or scientific, the general format is used: exponential if the exponent is -4 or less or greater than the precision (number of places after the decimal point), or fixed otherwise. Trailing zeros are dropped, as is the decimal point if would be the last character in the string.

If the uppercase flag is set, the exponent is introduced by 'E', or else by 'e'. If the showpoint flag is set, the decimal point is always present.

See AlsoPointer (void*)

The output format for a pointer is implementation-defined.

If the number is negative, it is prefaced with a minus sign ('-'). If the number is positive, no sign is output unless the showpos flag is set, in which case a positive sign ('+') appears at the start of the string.

If a decimal point character is needed, it is obtained from the numpunct facet's decimal_point( ) function. Integers have thousands separators inserted according to the grouping( ) function. See numpunct later in this section for more information.

If necessary, fill characters are inserted until the formatted width is stream.width( ). The stream's adjustfield flag dictates how fill characters are inserted. That is, stream.flags( ) & stream.adjustfield is tested, and if it is equal to:

Finally, stream.width(0) is called to reset the field width to 0. The return value is an iterator that points to one past the last output character.