NAME¶

std::put_time - std::put_time

Synopsis¶

Defined in header <iomanip>
template< class CharT > (since C++11)
/*unspecified*/ put_time( const std::tm* tmb, const CharT* fmt );

When used in an expression out << put_time(tmb, fmt), converts the date and time
information from a given calendar time tmb to a character string according to format
string fmt, as if by calling std::strftime, std::wcsftime, or analog (depending on
CharT), according to the std::time_put facet of the locale currently imbued in the
output stream out.

Parameters¶

tmb - pointer to the calendar time structure as obtained from std::localtime or
std::gmtime
fmt - pointer to a null-terminated CharT string specifying the format of conversion

Format string

The format string consists of zero or more conversion specifiers and ordinary
characters (except %). All ordinary characters, including the terminating null
character, are copied to the output string without modification. Each conversion
specification begins with % character, optionally followed by E or O modifier
(ignored if unsupported by the locale), followed by the character that determines
the behavior of the specifier. The following format specifiers are available:

Conversion Explanation Used fields
specifier
% writes literal %. The full conversion specification
must be %%.
n writes newline character
(C++11)
t writes horizontal tab character
(C++11)
Year
Y writes year as a decimal number, e.g. 2017 tm_year
EY writes year in the alternative representation, e.g.平
(C++11) 成23年 (year Heisei 23) instead of 2011年 (year 2011) tm_year
in ja_JP locale
y writes last 2 digits of year as a decimal number (range tm_year
[00,99])
Oy writes last 2 digits of year using the alternative tm_year
(C++11) numeric system, e.g. 十一 instead of 11 in ja_JP locale
Ey writes year as offset from locale's alternative tm_year
(C++11) calendar period %EC (locale-dependent)
C writes first 2 digits of year as a decimal number tm_year
(C++11) (range [00,99])
EC writes name of the base year (period) in the locale's
(C++11) alternative representation, e.g. 平成 (Heisei era) in tm_year
ja_JP
writes ISO 8601 week-based year, i.e. the year that
contains the specified week.

G In ISO 8601 weeks begin with Monday and the first week tm_year, tm_wday,
(C++11) of the year must satisfy the following requirements: tm_yday

* Includes January 4
* Includes first Thursday of the year
writes last 2 digits of ISO 8601 week-based year, i.e.
the year that contains the specified week (range
[00,99]).
g tm_year, tm_wday,
(C++11) In ISO 8601 weeks begin with Monday and the first week tm_yday
of the year must satisfy the following requirements:

* Includes January 4
* Includes first Thursday of the year
Month
b writes abbreviated month name, e.g. Oct (locale tm_mon
dependent)
h synonym of b tm_mon
(C++11)
B writes full month name, e.g. October (locale dependent) tm_mon
m writes month as a decimal number (range [01,12]) tm_mon
Om writes month using the alternative numeric system, e.g. tm_mon
(C++11) 十二 instead of 12 in ja_JP locale
Week
U writes week of the year as a decimal number (Sunday is tm_year, tm_wday,
the first day of the week) (range [00,53]) tm_yday
OU writes week of the year, as by %U, using the tm_year, tm_wday,
(C++11) alternative numeric system, e.g. 五十二 instead of 52 tm_yday
in ja_JP locale
W writes week of the year as a decimal number (Monday is tm_year, tm_wday,
the first day of the week) (range [00,53]) tm_yday
OW writes week of the year, as by %W, using the tm_year, tm_wday,
(C++11) alternative numeric system, e.g. 五十二 instead of 52 tm_yday
in ja_JP locale
writes ISO 8601 week of the year (range [01,53]).

V In ISO 8601 weeks begin with Monday and the first week tm_year, tm_wday,
(C++11) of the year must satisfy the following requirements: tm_yday

* Includes January 4
* Includes first Thursday of the year
OV writes week of the year, as by %V, using the tm_year, tm_wday,
(C++11) alternative numeric system, e.g. 五十二 instead of 52 tm_yday
in ja_JP locale
Day of the year/month
j writes day of the year as a decimal number (range tm_yday
[001,366])
d writes day of the month as a decimal number (range tm_mday
[01,31])
writes zero-based day of the month using the
Od alternative numeric system, e.g. 二十七 instead of 27
(C++11) in ja_JP locale tm_mday

Single character is preceded by a space.
writes day of the month as a decimal number (range
e [1,31]). tm_mday
(C++11)
Single digit is preceded by a space.
writes one-based day of the month using the alternative
Oe numeric system, e.g. 二十七 instead of 27 in ja_JP
(C++11) locale tm_mday

Single character is preceded by a space.
Day of the week
a writes abbreviated weekday name, e.g. Fri (locale tm_wday
dependent)
A writes full weekday name, e.g. Friday (locale tm_wday
dependent)
w writes weekday as a decimal number, where Sunday is 0 tm_wday
(range [0-6])
Ow writes weekday, where Sunday is 0, using the
(C++11) alternative numeric system, e.g. 二 instead of 2 in tm_wday
ja_JP locale
u writes weekday as a decimal number, where Monday is 1 tm_wday
(C++11) (ISO 8601 format) (range [1-7])
Ou writes weekday, where Monday is 1, using the
(C++11) alternative numeric system, e.g. 二 instead of 2 in tm_wday
ja_JP locale
Hour, minute, second
H writes hour as a decimal number, 24 hour clock (range tm_hour
[00-23])
OH writes hour from 24-hour clock using the alternative tm_hour
(C++11) numeric system, e.g. 十八 instead of 18 in ja_JP locale
I writes hour as a decimal number, 12 hour clock (range tm_hour
[01,12])
OI writes hour from 12-hour clock using the alternative tm_hour
(C++11) numeric system, e.g. 六 instead of 06 in ja_JP locale
M writes minute as a decimal number (range [00,59]) tm_min
OM writes minute using the alternative numeric system, tm_min
(C++11) e.g. 二十五 instead of 25 in ja_JP locale
S writes second as a decimal number (range [00,60]) tm_sec
OS writes second using the alternative numeric system, tm_sec
(C++11) e.g. 二十四 instead of 24 in ja_JP locale

Other¶

c writes standard date and time string, e.g. Sun Oct 17 all
04:41:13 2010 (locale dependent)
Ec writes alternative date and time string, e.g. using 平
(C++11) 成23年 (year Heisei 23) instead of 2011年 (year 2011) all
in ja_JP locale
x writes localized date representation (locale dependent) all
Ex writes alternative date representation, e.g. using 平
(C++11) 成23年 (year Heisei 23) instead of 2011年 (year 2011) all
in ja_JP locale
X writes localized time representation, e.g. 18:40:20 or all
6:40:20 PM (locale dependent)
EX writes alternative time representation (locale all
(C++11) dependent)
D equivalent to "%m/%d/%y" tm_mon, tm_mday,
(C++11) tm_year
F equivalent to "%Y-%m-%d" (the ISO 8601 date format) tm_mon, tm_mday,
(C++11) tm_year
r writes localized 12-hour clock time (locale dependent) tm_hour, tm_min,
(C++11) tm_sec
R equivalent to "%H:%M" tm_hour, tm_min
(C++11)
T equivalent to "%H:%M:%S" (the ISO 8601 time format) tm_hour, tm_min,
(C++11) tm_sec
p writes localized a.m. or p.m. (locale dependent) tm_hour
z writes offset from UTC in the ISO 8601 format (e.g.
(C++11) -0430), or no characters if the time zone information tm_isdst
is not available
writes locale-dependent time zone name or abbreviation,
Z or no characters if the time zone information is not tm_isdst
available

Return value¶

An object of unspecified type such that

* if out is an object of type std::basic_ostream<CharT, Traits>, the expression
out << put_time(tmb, fmt)
* has type std::basic_ostream<CharT, Traits>&
* has value out
* behaves as if it called f(out, tmb, fmt)

where the function f is defined as:

template<class CharT, class Traits>
void f(std::basic_ios<CharT, Traits>& str, const std::tm* tmb, const CharT* fmt)
{
using Iter = std::ostreambuf_iterator<CharT, Traits>;
using TimePut = std::time_put<CharT, Iter>;

const TimePut& tp = std::use_facet<TimePut>(str.getloc());
const Iter end = tp.put(Iter(str.rdbuf()), str, str.fill(), tmb,
fmt, fmt + Traits::length(fmt));

if (end.failed())
str.setstate(std::ios_base::badbit);
}

Example¶

// Run this code

#include <ctime>
#include <iomanip>
#include <iostream>

int main()
{
std::time_t t = std::time(nullptr);
std::tm tm = *std::localtime(&t);

std::cout.imbue(std::locale("ru_RU.utf8"));
std::cout << "ru_RU: " << std::put_time(&tm, "%c %Z") << '\n';

std::cout.imbue(std::locale("ja_JP.utf8"));
std::cout << "ja_JP: " << std::put_time(&tm, "%c %Z") << '\n';
}

Possible output:¶

ru_RU: Ср. 28 дек. 2011 10:21:16 EST
ja_JP: 2011年12月28日 10時21分16秒 EST

Source file:	std::put_time.3.en.gz (from stdman 2024.07.05-1.1)
Source last updated:	2024-07-08T06:08:56Z
Converted to HTML:	2024-07-26T00:50:57Z