public member function
<locale>

std::time_put::put

iter_type put (iter_type s, ios_base& str, char_type fill, const tm* t,               const char_type* pattern, const char_type* pat_end) const;iter_type put (iter_type s, ios_base& str, char_type fill, const tm* t,               char format, char modifier = 0) const;
Write time and date
Formats the time value in the tm structure pointed by t into a sequence of characters.

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

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

(1) single format specifier
This version simply calls the virtual protected member do_put, which by default produces the same sequence as produced by strftime using a string formed by a percentage sign ('%') followed by argument format, with modifier optionally inserted in between (when not equal to zero).
(2) format string
This version writes the characters in the range [fmt_begin,fmt_end) sequentially replacing any format specifier (as if recognized by the C function strftime) by the result of calling the virtual protected member do_put with the proper arguments (with the specifier being replaced and, optionally, its modifier, as final arguments).

See the reference for strftime for more details on the specifiers.

The function uses the ctype facet of str's locale to narrow the characters in the sequence to char when necessary.

Parameters

s
Iterator pointing to the first character of the output sequence.
The sequence shall be large enough to accommodate for the whole expression.
Member type iter_type is the facet's iterator type (defined as an alias of time_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 (nothing is written to this stream by this function).
fill
Fill character. The fill character is used in output insertion operations to fill spaces when the format requires some character padding.
Member type char_type is the facet's character type (defined as an alias of time_put's first template parameter, charT).
t
Pointer to an object of type struct tm (defined in header <ctime>), whose data is formatted.
pattern, pat_end
Pointers to the beginning and end characters of the pattern sequence (format string).
These characters are written to s, except the format tags (as recognized by strftime, which are replaced by their corresponding time expressions before being written.
The range used is [pattern,pat_end), which contains all the characters between pattern and pat_end, including the character pointed by pattern but not the character pointed by pat_end.
Note that null characters (if any) are also written, and the function does not stop when they are found, proceeding beyond them.
Member type char_type is the facet's character type (defined as an alias of time_put's first template parameter, charT).
format
Individual format specifier; For the default implementation of do_put, this shall be one of the specifiers accepted by strftime.
modifier
Some implementations allow for a format modifier to the specifier.
A value of 0 ('\0') is interpreted as no modifier.

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 time_put's second template parameter, OutputIterator).

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// time_put example
// time_put::put example
#include <iostream>       // std::cout
#include <string>         // std::string
#include <ctime>          // std::time, std::localtime, std::tm, std::time_t
#include <locale>         // std::locale, std::time_put, std::use_facet

int main ()
{
  std::locale loc;              // classic "C" locale

  // get time_put facet:
  const std::time_put<char>& tmput = std::use_facet <std::time_put<char> > (loc);

  std::time_t timestamp;
  std::time ( &timestamp );
  std::tm * now = std::localtime ( &timestamp );

  // using pattern string:
  std::string pattern ("Now it's: %I:%M%p\n");
  tmput.put (std::cout, std::cout, ' ', now, pattern.data(), pattern.data()+pattern.length());

  // using single specifier:
  std::cout << "Now it's: ";
  tmput.put (std::cout, std::cout, ' ', now, 'X');
  std::cout << '\n';
  return 0;
}

Output:

Now it's: 12:29PM
Now it's: 12:29:08


Data races

The facet object, the object pointed by t and the range between pattern and pat_end, are accessed.
The sequence pointed by s is modified.

Exception safety

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

See also