Share via

num_put::do_put

  • Article

A virtual function that is called to convert a number into a sequence of CharTypes that represents the number formatted for a given locale.

virtual iter_type do_put(
    iter_type _Dest,
    ios_base& _Iosbase,
    _Elem _Fill,
    bool _Val
) const;
virtual iter_type do_put(
    iter_type _Dest,
    ios_base& _Iosbase,
    _Elem _Fill,
    long _Val
) const;
virtual iter_type do_put(
    iter_type _Dest,
    ios_base& _Iosbase,
    _Elem _Fill,
    unsigned long _Val
) const;
virtual iter_type do_put(
    iter_type _Dest,
    ios_base& _Iosbase,
    _Elem _Fill,
    double _Val
) const;
virtual iter_type do_put(
    iter_type _Dest,
    ios_base& _Iosbase,
    _Elem _Fill,
    long double _Val
) const;
virtual iter_type do_put(
    iter_type _Dest,
    ios_base& _Iosbase,
    _Elem _Fill,
    const void * _Val
) const;
virtual iter_type do_put(
    iter_type _Dest,
    ios_base& _Iosbase,
    _Elem _Fill,
    const long long _Val
) const; virtual iter_type do_put(
    iter_type _Dest,
    ios_base& _Iosbase,
    _Elem _Fill,
    const unsigned long long _Val
) const;

Parameters

  • _Next
    An iterator addressing the first element of the inserted string.

  • _Iosbase
    Specified the stream which contains locale with the numpunct facet used to punctuate the output and flags for formatting the output.

  • _Fill
    A character that is used for spacing.

  • _Val
    The number or Boolean type that is to be output.

Return Value

An output iterator the addresses the position one beyond the last element produced.

Remarks

The first virtual protected member function generates sequential elements beginning at _Next to produce an integer output field from the value of _Val. The function returns an iterator designating the next place to insert an element beyond the generated integer output field.

The integer output field is generated by the same rules used by the print functions for generating a series of char elements to a file. Each such char element is assumed to map to an equivalent element of type CharType by a simple, one-to-one mapping. Where a print function pads a field with either spaces or the digit 0, however, do_put instead uses fill. The equivalent print conversion specification is determined as follows:

  • If iosbase.flags & ios_base::basefield == ios_base::oct, the conversion specification is lo.

  • If iosbase.flags & ios_base::basefield == ios_base::hex, the conversion specification is lx.

  • Otherwise, the conversion specification is ld.

If iosbase.width is nonzero, a field width of this value is prepended. The function then calls iosbase.width(0) to reset the field width to zero.

Padding occurs only if the minimum number of elements N required to specify the output field is less than iosbase.width. Such padding consists of a sequence of N – width copies of fill. Padding then occurs as follows:

  • If iosbase.flags & ios_base::adjustfield == ios_base::left, the flag – is prepended. (Padding occurs after the generated text.)

  • If iosbase.flags & ios_base::adjustfield == ios_base::internal, the flag 0 is prepended. (For a numeric output field, padding occurs where the print functions pad with 0.)

  • Otherwise, no additional flag is prepended. (Padding occurs before the generated sequence.)

Finally:

  • If iosbase.flags & ios_base::showpos is nonzero, the flag + is prepended to the conversion specification.

  • If iosbase.flags & ios_base::showbase is nonzero, the flag # is prepended to the conversion specification.

The format of an integer output field is further determined by the locale facet fac returned by the call use_facet <numpunct<Elem>(iosbase.getloc). Specifically:

  • fac.grouping determines how digits are grouped to the left of any decimal point

  • fac.thousands_sep determines the sequence that separates groups of digits to the left of any decimal point

If no grouping constraints are imposed by fac.grouping (its first element has the value CHAR_MAX), then no instances of fac.thousands_sep are generated in the output field. Otherwise, separators are inserted after the print conversion occurs.

The second virtual protected member function:

virtual iter_type do_put(iter_type _Next, ios_base& _Iosbase,
    CharType _Fill, unsigned long _Val) const;

behaves the same as the first, except that it replaces a conversion specification of ld with lu.

The third virtual protected member function:

virtual iter_type do_put(iter_type _Next, ios_base& _Iosbase,
    CharType _Fill, double _Val) const;

behaves the same as the first, except that it produces a floating-point output field from the value of val.fac.decimal_point determines the sequence that separates the integer digits from the fraction digits. The equivalent print conversion specification is determined as follows:

  • If iosbase.flags & ios_base::floatfield == ios_base::fixed, the conversion specification is lf.

  • If iosbase.flags & ios_base::floatfield == ios_base::scientific, the conversion specification is le. If iosbase.flags & ios_base::uppercase is nonzero, e is replaced with E.

  • Otherwise, the conversion specification is lg. If iosbase.flags & ios_base::uppercase is nonzero, g is replaced with G.

If iosbase.flags & ios_base::fixed is nonzero or if iosbase.precision is greater than zero, a precision with the value iosbase.precision is prepended to the conversion specification. Any padding behaves the same as for an integer output field. The padding character is fill. Finally:

  • If iosbase.flags & ios_base::showpos is nonzero, the flag + is prepended to the conversion specification.

  • If iosbase.flags & ios_base::showpoint is nonzero, the flag # is prepended to the conversion specification.

The fourth virtual protected member function:

virtual iter_type do_put(iter_type _Next, ios_base& _Iosbase,
    CharType _Fill, long double _Val) const;

behaves the same the third, except that the qualifier l in the conversion specification is replaced with L.

The fifth virtual protected member function:

virtual iter_type do_put(iter_type _Next, ios_base& _Iosbase,
    CharType _Fill, const void *_Val) const;

behaves the same the first, except that the conversion specification is p**,** plus any qualifier needed to specify padding.

The sixth virtual protected member function:

virtual iter_type do_put(iter_type _Next, ios_base& _Iosbase,
    CharType _Fill, bool _Val) const;

behaves the same as the first, except that it generates a Boolean output field from _Val.

A Boolean output field takes one of two forms. If iosbase.flags & ios_base::boolalpha is false, the member function returns do_put(_Next, _Iosbase, _Fill, (long)_Val), which typically produces a generated sequence of either 0 (for false) or 1 (for true). Otherwise, the generated sequence is either fac.falsename) (for false), or fac.truename (for true).

The seventh virtual protected member function:

virtual iter_type do_put(iter_type next, ios_base& iosbase,
    Elem fill, long long val) const;

behaves the same as the first, except that it replaces a conversion specification of ld with lld.

The eighth virtual protected member function:

virtual iter_type do_put(iter_type next, ios_base& iosbase,
    Elem fill, unsigned long long val) const;

behaves the same as the first, except that it replaces a conversion specification of ld with llu.

Example

See the example for put, which calls do_put.

Requirements

Header: <locale>

Namespace: std

See Also

Reference

num_put Class