< cpp‎ | locale
Localizations library
Locales and facets
Facet category base classes
ctype facets
numeric facets
collate facets
time facets
monetary facets
messages facets
Character classification and conversion
Character classification
Code conversion facets
C locale
Defined in header <locale>

    class CharT,
    class OutputIt = std::ostreambuf_iterator<CharT>

> class num_put;

Class std::num_put encapsulates the rules for formatting numeric values as strings. Specifically, the types bool, long, unsigned long, long long, unsigned long long (since C++11), double, long double, void*, and of all types implicitly convertible to these (such as int or float) are supported. The standard formatting output operators (such as cout << n;) use the std::num_put facet of the I/O stream's locale to generate text representation of numbers.

cpp/locale/locale/facetstd-num put-inheritance.svg

Inheritance diagram

If a std::num_put specialization is not guaranteed to be provided by the standard library (see below), the behaviors of its put() and do_put() are not guaranteed as specified.


[edit] Specializations

The standard library is guaranteed to provide the following specializations (they are required to be implemented by any locale object):

Defined in header <locale>
std::num_put<char> creates narrow string representations of numbers
std::num_put<wchar_t> creates wide string representations of numbers

In addition, the standard library is also guaranteed to provide every specialization that satisfies the following type requirements:

  • CharT is one of
    • char,
    • wchar_t, and
    • any other implementation-defined character type that meets the requirements for a character on which any of the iostream components can be instantiated; and
  • OutputIt must meet the requirements of LegacyOutputIterator.

[edit] Member types

Member type Definition
char_type CharT
iter_type OutputIt

[edit] Member functions

constructs a new num_put facet
(public member function)
destructs a num_put facet
(protected member function)
invokes do_put
(public member function)

[edit] Protected member functions

formats a number and writes to output stream
(virtual protected member function)

[edit] Member objects

static std::locale::id id
id of the locale
(public member object)

[edit] Example

#include <iostream>
#include <locale>
#include <string>
#include <iterator>
int main()
    double n = 1234567.89;
    std::cout << "Direct conversion to string:\n"
              << std::to_string(n) << '\n'
              << "Output using a german locale:\n"
              << std::fixed << n << '\n'
              << "Output using an american locale:\n";
    // use the facet directly
    auto& f = std::use_facet<std::num_put<char>>(std::cout.getloc());
    f.put(std::ostreambuf_iterator<char>(std::cout), std::cout, ' ', n);
    std::cout << '\n';

Possible output:

Direct conversion to string:
Output using a german locale:
Output using an american locale:

[edit] Defect reports

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

DR Applied to Behavior as published Correct behavior
LWG 427 C++98 num_put could accept any CharT that meets the
requirements for a character on which any of
the iostream components can be instantiated
only guarantees to accept
char and wchar_t, other types
are implementation-defined

[edit] See also

defines numeric punctuation rules
(class template) [edit]
parses numeric values from an input character sequence
(class template) [edit]
converts an integral or floating point value to string
(function) [edit]
converts an integral or floating point value to wstring
(function) [edit]