num_put

public member function
<locale>

std::num_put::put

iter_type put (iter_type out, ios_base& str, char_type fill, bool val) const;
iter_type put (iter_type out, ios_base& str, char_type fill, long val) const;
iter_type put (iter_type out, ios_base& str, char_type fill, unsigned long val) const;
iter_type put (iter_type out, ios_base& str, char_type fill, double val) const;
iter_type put (iter_type out, ios_base& str, char_type fill, long double val) const;
iter_type put (iter_type out, ios_base& str, char_type fill, const void* val) const;
iter_type put (iter_type out, ios_base& str, char_type fill, bool val) const;
iter_type put (iter_type out, ios_base& str, char_type fill, long val) const;
iter_type put (iter_type out, ios_base& str, char_type fill, unsigned long val) const;
iter_type put (iter_type out, ios_base& str, char_type fill, double val) const;
iter_type put (iter_type out, ios_base& str, char_type fill, long double val) const;
iter_type put (iter_type out, ios_base& str, char_type fill, const void* val) const;
iter_type put (iter_type out, ios_base& str, char_type fill, long long val) const;
iter_type put (iter_type out, ios_base& str, char_type fill, unsigned long long val) const;
Put numerical value
Formats val into out as a sequence of characters.
For the process, it uses the formatting options selected in the object passed as str (using its ios_base::fmtflags value and its imbued locale), as well as fill as fill character.

The function writes the characters resulting from the formatting operation into the sequence whose first character is pointed by out.

An iterator to the character right after the last element written to the output sequence is returned by the function.

Internally, this function simply calls the virtual protected member do_put, which by default produces a sequence with the same format as printf does for the format specified that corresponds to the type of argument val taking into account str's format flags and field width. The function uses the locale selected in str to obtain format details (through facet numpunct) and to widen characters (with ctype::widen) when necessary.

Parameters

out
Iterator pointing to the first character where the representation as a sequence of characters is stored.
The sequence shall be long enough to contain the whole expression.
Member type iter_type is the facet's iterator type (defined as an alias of num_put's second template parameter, OutputIterator). By default, this is an ostreambuf_iterator, allowing implicit conversions from basic_ostream objects.
str
Object of a class derived from ios_base (generally an output stream object). It is only used to obtain formatting information.
fill
Fill character: The fill character is used in output insertion operations to fill spaces when results have to be padded to the field width.
Member type char_type is the facet's character type (defined as an alias of num_put's first template parameter, charT).
val
Value to be formatted.

Return value

The next character in the sequence right after the last one written.
Member type iter_type is the facet's iterator type (defined as an alias of num_put's second template parameter, OutputIterator).

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// num_put example
#include <iostream>       // std::cout
#include <locale>         // std::locale, std::num_put, std::use_facet

int main ()
{
  std::cout.width(10);    // set field width to 10 characters

  std::use_facet<std::num_put<char> >(std::cout.getloc()).put
    (std::cout, std::cout, '0', 3.14159265);

  std::cout << '\n';

  return 0;
}


Possible output:

0003.14159

Data races

The object is accessed.
The array pointed by out is modified on success.

Exception safety

If an exception is thrown, there are no changes in the facet object, although some of arguments may be affected.

See also