std::put_time

template <class charT>/*unspecified*/ put_time (const struct tm* tmb, const charT* fmt);

Put date and time

Inserts the representation of the time and date information pointed by tmb, formatting it as specified by argument fmt.

Internally, the function accesses the output sequence by first constructing an object of type basic_ostream::sentry. Then (if evaluating the sentry object is true), it calls time_put::put (using the stream's selected locale) to perform both the formatting and the insertion operations, adjusting the stream's internal state flags accordingly. Finally, it destroys the sentry object before returning.

This manipulator is declared in header <iomanip>.

Parameters

tmb

Pointer to the object of type struct tm with the date and time information to format.
struct tm is a class defined in header <ctime>.

fmt

C-string used by time_put::put as format string. It contains any combination of regular characters and special format specifiers. These format specifiers are replaced by the function to the corresponding values to represent the time specified in tmb. They all begin with a percentage (%) sign, and are:

specifier	Replaced by	Example
`%a`	Abbreviated weekday name *	`Thu`
`%A`	Full weekday name *	`Thursday`
`%b`	Abbreviated month name *	`Aug`
`%B`	Full month name *	`August`
`%c`	Date and time representation *	`Thu Aug 23 14:55:02 2001`
`%C`	Year divided by 100 and truncated to integer (`00-99`)	`20`
`%d`	Day of the month, zero-padded (`01-31`)	`23`
`%D`	Short `MM/DD/YY` date, equivalent to `%m/%d/%y`	`08/23/01`
`%e`	Day of the month, space-padded ( `1-31`)	`23`
`%F`	Short `YYYY-MM-DD` date, equivalent to `%Y-%m-%d`	`2001-08-23`
`%g`	Week-based year, last two digits (`00-99`)	`01`
`%G`	Week-based year	`2001`
`%h`	Abbreviated month name * (same as `%b`)	`Aug`
`%H`	Hour in 24h format (`00-23`)	`14`
`%I`	Hour in 12h format (`01-12`)	`02`
`%j`	Day of the year (`001-366`)	`235`
`%m`	Month as a decimal number (`01-12`)	`08`
`%M`	Minute (`00-59`)	`55`
`%n`	New-line character (`'\n'`)
`%p`	AM or PM designation	`PM`
`%r`	12-hour clock time *	`02:55:02 pm`
`%R`	24-hour `HH:MM` time, equivalent to `%H:%M`	`14:55`
`%S`	Second (`00-61`)	`02`
`%t`	Horizontal-tab character (`'\t'`)
`%T`	ISO 8601 time format (`HH:MM:SS`), equivalent to `%H:%M:%S`	`14:55:02`
`%u`	ISO 8601 weekday as number with Monday as `1` (`1-7`)	`4`
`%U`	Week number with the first Sunday as the first day of week one (`00-53`)	`33`
`%V`	ISO 8601 week number (`00-53`)	`34`
`%w`	Weekday as a decimal number with Sunday as `0` (`0-6`)	`4`
`%W`	Week number with the first Monday as the first day of week one (`00-53`)	`34`
`%x`	Date representation *	`08/23/01`
`%X`	Time representation *	`14:55:02`
`%y`	Year, last two digits (`00-99`)	`01`
`%Y`	Year	`2001`
`%z`	ISO 8601 offset from UTC in timezone (1 minute=1, 1 hour=100) If timezone cannot be termined, no characters	`+100`
`%Z`	Timezone name or abbreviation * If timezone cannot be termined, no characters	`CDT`
`%%`	A `%` sign	`%`

* The specifiers marked with an asterisk (*) are locale-dependent.
Two locale-specific modifiers can also be inserted between the percentage sign (%) and the specifier proper to request an alternative format, where applicable:

Modifier	Meaning	Applies to
`E`	Uses the locale's alternative representation	`%Ec %EC %Ex %EX %Ey %EY`
`O`	Uses the locale's alternative numeric symbols	`%Od %Oe %OH %OI %Om %OM %OS %Ou %OU %OV %Ow %OW %Oy`

charT is the character type in the c-string.

Return Value

Unspecified. This function should only be used as a stream manipulator (see example).

Errors are signaled by modifying the stream's internal state flags:

flag	error
`eofbit`	-
`failbit`	The function failed to format `tmb` as specified by `fmt` (it may also be set if the construction of `sentry` failed).
`badbit`	Either the insertion on the stream failed, or some other error happened (such as when this function catches an exception thrown by an internal operation). When set, the integrity of the stream may have been affected.

Multiple flags may be set by a single operation.

If the operation sets an internal state flag on the stream that was registered using its member exceptions, the function throws an exception of type ios_base::failure.

Example

// put_time example
#include <iostream>     // std::cout
#include <iomanip>      // std::put_time
#include <ctime>        // std::time_t, struct std::tm, std::localtime
#include <chrono>       // std::chrono::system_clock

int main ()
{
  using std::chrono::system_clock;
  std::time_t tt = system_clock::to_time_t (system_clock::now());

  struct std::tm * ptm = std::localtime(&tt);
  std::cout << "Now (local time): " << std::put_time(ptm,"%c") << '\n';

  return 0;
}

Possible output:

Now (local time): 03/07/13 11:41:34

Data races

Accesses the object pointed by tmb and the array pointed by fmt.
Modifies the stream object where it is inserted.
Concurrent access to the same stream object may cause data races, except for the standard stream objects (cout, cerr, clog, wcout, wcerr and wclog) when these are synchronized with stdio (in this case, no data races are initiated, although no guarantees are given on the order in which characters from multiple threads are inserted).

Exception safety

Basic guarantee: if an exception is thrown, the object is in a valid state.
It throws an exception of member type failure if the resulting error state flag is not goodbit and member exceptions was set to throw for that state.
Any exception thrown by an internal operation is caught and handled by the function, setting badbit. If badbit was set on the last call to exceptions, the function rethrows the caught exception.

Note that invalid arguments cause undefined behavior.