num_put

Library:  Localization

num_put  locale::facet

• Local Index
• Summary
• Synopsis
• Specializations
• Description
• Interface
• Member Types
• Constructors
• Facet ID
• Public Member Functions
• Protected Member Functions
• Example
• See Also
• Standards Conformance

Members

char_type do_put()

id iter_type

num_put() put()

A numeric formatting facet

#include <locale>

namespace std {
  template <class charT, class OutputIterator> class num_put;
}

The primary template can be implicitly or explicitly specialized on any character type that satisfies the requirements on the type of the character used by iostream class templates, and on any iterator type that satisfies the requirements of Output Iterator.

The num_put facet includes facilities for formatted output of numeric values. basic_ostream and all other output-oriented streams use this facet to implement formatted numeric output.

namespace std {

  template <class charT, class OutputIterator =
    ostreambuf_iterator<charT> >
  class num_put : public locale::facet {

    public:
    typedef charT            char_type;
    typedef OutputIterator   iter_type;
    explicit num_put(size_t = 0);

    iter_type put(iter_type, ios_base&, char_type, bool)
              const;
    iter_type put(iter_type, ios_base&, char_type, long)
              const;
    iter_type put(iter_type, ios_base&, char_type,
                  unsigned long) const;
    iter_type put(iter_type, ios_base&, char_type,
                  double) const;
    iter_type put(iter_type, ios_base&, char_type,
                  long double) const;
    iter_type put(iter_type, ios_base&, char_type, 
                  const void* v) const; 

    static locale::id id;

    protected:
    virtual iter_type do_put(iter_type, ios_base&, char_type,
                             bool) const;
    virtual iter_type do_put(iter_type, ios_base&, char_type,
                             long) const;
    virtual iter_type do_put(iter_type, ios_base&, char_type,
                             unsigned long) const;
   virtual iter_type do_put(iter_type, ios_base&, char_type,
                             double) const;
   virtual iter_type do_put(iter_type, ios_base&, char_type,
                             long double) const;
   virtual iter_type do_put(iter_type, ios_base&, char_type,
                            const void*&) const; 
  };
}

char_type

Type of character upon which the facet is instantiated.

iter_type

Type of iterator used to scan the character buffer.

explicit num_put(size_t refs = 0) 

Constructs a num_put object. Calls locale::facet (refs).

The refs argument is set to the initial value of the num_put object's reference count. A num_put object f constructed with (refs == 0) that is installed in one or more locale objects will be destroyed and the storage it occupies will be deallocated when the last locale object containing the facet is destroyed, as if by calling delete static_cast<locale::facet*>(&f). A num_put object constructed with (refs != 0) will not be destroyed by any locale objects in which it may have been installed.

static locale::id id;

Unique identifier for this type of facet.

The public members of the num_put facet include an interface to protected members. Each public member function put() calls the corresponding protected virtual protected member do_put().

iter_type 
put(iter_type s, ios_base& io, char_type fill, bool v)
    const; 
iter_type 
put(iter_type s, ios_base& io, char_type fill, long v)
    const; 
iter_type 
put(iter_type s, ios_base& io, char_type fill,
    unsigned long v) const; 
iter_type 
put(iter_type s, ios_base& io, char_type fill, double v)
    const; 
iter_type
put(iter_type s, ios_base& io, char_type fill, 
    long double v) const; 
iter_type 
put(iter_type s, ios_base& io, char_type fill, 
    const void* v) const;

Each of the six overloads of the put() function simply call the corresponding do_put() function.

virtual iter_type 
do_put(iter_type s, ios_base& io, 
       char_type fill, bool v) const; 
virtual iter_type 
do_put(iter_type s, ios_base& io, 
       char_type fill, long v) const; 
virtual iter_type 
do_put(iter_type s, ios_base& io, 
       char_type fill,unsigned long) const; 
virtual iter_type 
do_put(iter_type s, ios_base& io, 
       char_type fill, double v) const; 
virtual iter_type 
do_put(iter_type s, ios_base& io, 
       char_type fill,long double v) const; 
virtual iter_type 
do_put(iter_type s, ios_base& io, 
       char_type fill,const void* v) const;

The six overloads of the do_put() member function all take a value v of the respective type and output a formatted character string representing that value into the output sequence starting at s.

The io argument is used to obtain formatting parameters such that justification, field width, numeric base, and grouping, and the fill argument determines the character to use in padding.

The functions use the numpunct<char_type> facet installed in the locale object imbued in io to determine the grouping and the thousands separator to be used, if any.

The following table shows how the various flags obtained by the functions from io by calling io.flags() are interpreted to format the values.

The setting of the ios_base::adjustfield bits along with the value of io.width() determine the justification of output. If the return value of io.width(), w, is greater than the number of characters, n, that would otherwise be produced, (w - n) copies of the fill character will be inserted at the position denoted `*' in Table 29.

Table 29: ios_base::adjustfield formats 

adjustfield	Format
internal	-***####
left	-###****
right	****-###

For integral types, the setting of the ios_base::basefield bits determines the base in which the numbers will be represented. For octal and hexadecimal output, the ios_base::showbase bit determines whether the `0' or "0x" prefix will be output before the sequence of octal or hexadecimal digits.

The ios_base::uppercase bit determines whether uppercase or lowercase of alphabetic characters will be used in the output.

The ios_base::showpos bit determines whether the plus sign (`+') will precede positive values. Negative values output in base 10 are always preceded by the minus sign (`-'). See Table 30 for details.

Table 30: os_base::basefield formats 

basefield		uppercase	showbase	showpos
0	dddd	dddd	dddd	dddd
bin(*)	bbbb	bbbb	bbbb	bbbb
oct	oooo	oooo	oooo	oooo
dec	dddd	dddd	dddd	+ddd
hex	hhhh	HHHH	0xhh	0xhh
other(*)	####	####	####	####

(*) denotes an extension of this implementation. Output in base 1 (roman numerals for integral numbers 1 through 4999), and base 2 through 36 is supported. Use the setbase() manipulator declared in <iomanip> to set base other than 2, 8, 10, and 16.

For floating point types, the setting of the ios_base::floatfield bits determines the format of the output as shown in Table 31.

Table 31: ios_base::floatfield formats

floatfield		uppercase	showpos	showpoint
0	d[.d|.de]	d[.d|.dE]	+d[.d|.dE]	+d.[d|de]
fixed	d[.ddd]	d[.ddd]	+d[.ddd]	d.[ddd]
scientific	d.de	d.dE	+d.de	d.de

For floating point types, the value of io.precision() determines the number of digits after the decimal point.

As an extension of this implementation, when the (io.flags () & ios_base::fixed) is non-zero, and (io.precision() < 0) is true, the negative precision value, prec, will result in the decimal point character being moved (or inserted in the case of integers) by prec positions to the left of the least significant integral digit. For example, with (io.precision() == -3), the integer value 1234 will produce 1.234 on output, the floating point value 1234.5678 will produce 1.235. If the magnitude of prec is larger than the number of digits in the integer part of the value, the decimal point will be immediately preceded by a single digit 0 and followed by as many zeros as necessary so that there are exactly -prec digits after the decimal point. For example, the value 12 will produce 0.012 on output.

Table 32 provides a legend for Table 29, Table 30 and Table 31.

Table 32: Legend for Table 1, Table 2 and Table 3

Letter	Description
+	Sign: one of { +, - }
-	Sign: one of { +, - }, with the + sign being optional for non-negative values
.	Decimal point as determined by numpunct<char_type>::decimal_point()
*	The fill character.
#	Any digit
b	Binary digit(*): one of { 0, 1 }
o	Octal digit: one of { <binary digit>, 2, 3, 4, 5, 6, 7 }
d	Decimal digit: one of { <octal digit>, 8, 9 }
h	Hexadecimal digit: one of { <decimal digit>, a, b, c, d, e, f }
H	Uppercase hex digit: one of { <decimal digit>, A, B, C, D, E, F }
e	Floating point exponent in the format e-dd[d[d]]
E	Uppercase floating point exponent in the format E-dd[d[d]]
[]	Brackets enclose optional components
()	Parentheses enclose groups of one or more components
|	Vertical bar separates two possible alternatives

(*) denotes an extension of this implementation.

#include <iostream>   // for cout, endl
#include <iterator>   // for ostreambuf_iterator
#include <locale>     // for time_put

#include <examples.h>

// custom numeric punctuation facet
struct Punct: std::numpunct<char>
{
    char do_decimal_point () const {
        return ';';
    }

    string_type do_truename () const {
        return "numeric formatting";
    }

    char do_thousands_sep () const {
        return ':';
    }

    std::string do_grouping () const {
        return "\1\2\3";
    }
};

int main ()
{
    // construct a custom punctuation facet
    std::numpunct<char> *punct = new Punct;

    // construct a locale containing the custom facet
    const std::locale loc (std::cout.getloc (), punct);

    // imbue combined locale in cout
    std::cout.imbue (loc);

    // retrieve the standard numeric formatting facet
    const std::num_put<char> &nput =
        std::use_facet<std::num_put<char> >(std::cout.getloc ());
 
    // obtain a stream buffer iterator operating on cout's buffer
    std::ostreambuf_iterator<char> it = std::cout.rdbuf ();

    // write out bool values as strings
    std::cout.setf (std::ios::boolalpha);
    *nput.put (it, std::cout, ' ', true) = '\n';

    // set the field width and justification for the next operation
    std::cout.width (18);
    std::cout.setf (std::ios::fixed | std::ios::right);

    const double Pi = 3.14159265358979323846;

    // truncate Pi to an integer and write it out, padded on the left with periods
    *nput.put (it, std::cout, '.', long (Pi)) = '\n';

    // write out a number in hex notation using capital letters
    std::cerr.width (13);
    std::cerr.setf (std::ios::right | std::ios::uppercase);
    std::cerr.setf (std::ios::hex, std::ios::basefield);
    *nput.put (it, std::cerr, ' ', 3735928559UL) = '\n';

    std::cout.width (18);
    std::cout.setf (std::ios::internal, std::ios::adjustfield);
    std::cout.setf (std::ios::showpos);
    
    // write Pi out padded after the sign with spaces
    *nput.put (it, std::cout, ' ', Pi) = '\n';

    // write Pi out again, multiplied by a large number (to see grouping)
    *nput.put (it, std::cout, ' ', Pi * 1000000) = '\n';

    // and again, in scientific notation
    std::cout.precision (11);
    std::cout.setf (std::ios::scientific, std::ios::floatfield);
    *nput.put (it, std::cout, ' ', Pi * 1000000) = '\n';

    return 0;
}


Program Output:
numeric formatting
.................3
     DEADBEEF
+         3;141593
+3:141:59:2;653590
+3;14159265359e+06

locale, Facets, num_get, numpunct, ctype

ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 22.2.2.2