Apache C++ Standard Library Reference Guide

## 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

### Local Index

#### Members

char_type do_put() | id iter_type | num_put() put() |

### Summary

A numeric formatting facet

### Synopsis

    #include <locale>

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

### Specializations

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.

### Description

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.

### Interface

    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;
      };
    }

### Member Types

    char_type

Type of character upon which the facet is instantiated.

    iter_type

Type of iterator used to scan the character buffer.

### Constructors

    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.

### Facet ID

    static locale::id id;

Unique identifier for this type of facet.

### Public Member Functions

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.

### Protected Member Functions

    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.

### Example

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

    // 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

### See Also

locale, Facets, num_get, numpunct, ctype

### Standards Conformance

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