time_put::put


public member function
iter_type put ( iter_type s, ios_base& str, char_type fill, const tm* t,
                const charT* pattern, const charT* 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

Formats the time value in the tm structure pointed by t into an output sequence of characters.

The first version takes the sequence of characters in the the range from pattern to pat_end, and interprets it as the C function strftime would do, by expanding any format tag (begining with a percentage sign, %) found.

The second version formats a single character (as if it was a specifier preceeded by a percentage sign in the previous version). Because some implementations allow for a format modifier in an strftime specifier before the format character itself, the function has an additional parameter, modifier, to process this.

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

During its operation, the second version of this function in the generic template simply calls the virtual protected member do_put, which implements its functionality. On the other hand, the first version decomposes the sequence of characters pointed by pattern into regular characters, which are directly written, and format tags, which are individually exapanded by calling member do_put for each.

Parameters

s
Iterator pointing to the first character of the output sequence.
The sequence shall be large enough to accommodate for the whole expression.
iter_type is a member alias of the second template parameter of time_put (i.e., the facet's iterator type). This can be any output iterator. By default, this is an ostreambuf_iterator, allowing implicit conversions from ostream objects such as cout.
str
Object of a class derived from ios_base (generally an output stream object). It is used to obtain formatting information.
fill
Fill character. The fill character is used in output insertion operations to fill spaces when the format requires some character padding.
char_type is a member alias of the first template parameter of time_put (i.e., the facet's character type).
t
Pointer to an object of type struct tm (see ctime), whose data is formatted.
pattern, pat_end
Pointers to the beginning and ending characters of the pattern sequence. These characters are written to s without change, except the format tags, which are expanded into 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.
charT is the first template parameter of time_put (i.e., the facet's character type).
format
Individual format character. The function will format some of the information pointed by t into a sequence of characters as specified by this character, just as if it was preceded by a percentage sign in a format string passed to strftime.
modifier
Some implementations allow for a format modifier in an strftime specifier before the format character itself.
A value of 0 ('\0') is interpreted as no modifier.


Return value

The next character in the sequence right after the last one written.
iter_type is a member alias of time_put's second template parameter (i.e., the facet's iterator type).

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
// time_put example
#include <iostream>
#include <locale>
#include <ctime>
using namespace std;

int main ()
{
  locale loc;    // "C" locale

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

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

  char pattern[]="Now it's: %I:%M%p\n";
  tmput.put ( cout, cout, ' ', now, pattern, pattern+sizeof(pattern)-1 );

  cout << "Now it's: ";
  tmput.put ( cout, cout, ' ', now, 'X');
  cout << endl;
  return 0;
}


Output:

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


See also