NAME¶

std::get_time - std::get_time

Synopsis¶

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

When used in an expression in >> get_time(tmb, fmt), parses the character input as a
date/time value according to format string fmt according to the std::time_get facet
of the locale currently imbued in the input stream in. The resultant value is stored
in a std::tm object pointed to by tmb.

Parameters¶

tmb - valid pointer to the std::tm object where the result will be stored
pointer to a null-terminated CharT string specifying the conversion format

The format string consists of zero or more conversion specifiers, whitespace
characters, and ordinary characters (except %). Each ordinary character is
expected to match one character in the input stream in case-insensitive
comparison. Each whitespace character matches arbitrary whitespace in the
input string. 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
format specifiers match the POSIX function strptime():

Conversion Explanation Writes to fields
specifier
% matches a literal %. The full conversion (none)
specification must be %%
t matches any whitespace (none)
n matches any whitespace (none)
Year
Y parses full year as a 4 digit decimal number, tm_year
leading zeroes permitted but not required
parses year in the alternative representation,
EY e.g.平成23年 (year Heisei 23) which writes 2011 tm_year
to tm_year in ja_JP locale
parses last 2 digits of year as a decimal number.
y Range [69,99] results in values 1969 to 1999, tm_year
range [00,68] results in 2000-2068
parses last 2 digits of year using the
Oy alternative numeric system, e.g. 十一 is parsed tm_year
as 11 in ja_JP locale
Ey parses year as offset from locale's alternative tm_year
calendar period %EC
C parses the first 2 digits of year as a decimal tm_year
number (range [00,99])
parses the name of the base year (period) in the
EC locale's alternative representation, e.g. 平成 tm_year
(Heisei era) in ja_JP
Month
b parses the month name, either full or tm_mon
abbreviated, e.g. Oct
h synonym of b tm_mon
B synonym of b tm_mon
parses the month as a decimal number (range
m [01,12]), leading zeroes permitted but not tm_mon
required
Om parses the month using the alternative numeric tm_mon
system, e.g. 十二 parses as 12 in ja_JP locale
Week
parses the week of the year as a decimal number
U (Sunday is the first day of the week) (range tm_year, tm_wday,
[00,53]), leading zeroes permitted but not tm_yday
required
parses the week of the year, as by %U, using the tm_year, tm_wday,
OU alternative numeric system, e.g. 五十二 parses as tm_yday
52 in ja_JP locale
parses the week of the year as a decimal number
W (Monday is the first day of the week) (range tm_year, tm_wday,
[00,53]), leading zeroes permitted but not tm_yday
required
parses the week of the year, as by %W, using the tm_year, tm_wday,
OW alternative numeric system, e.g. 五十二 parses as tm_yday
52 in ja_JP locale
Day of the year/month
parses day of the year as a decimal number (range
j [001,366]), leading zeroes permitted but not tm_yday
required
fmt - parses the day of the month as a decimal number
d (range [01,31]), leading zeroes permitted but not tm_mday
required
parses the day of the month using the alternative
Od numeric system, e.g. 二十七 parses as 27 in ja_JP tm_mday
locale, leading zeroes permitted but not required
e synonym of d tm_mday
Oe synonym of Od tm_mday
Day of the week
a parses the name of the day of the week, either tm_wday
full or abbreviated, e.g. Fri
A synonym of a tm_wday
w parses weekday as a decimal number, where Sunday tm_wday
is 0 (range [0-6])
parses weekday as a decimal number, where Sunday
Ow is 0, using the alternative numeric system, e.g. tm_wday
二 parses as 2 in ja_JP locale
Hour, minute, second
parses the hour as a decimal number, 24 hour
H clock (range [00-23]), leading zeroes permitted tm_hour
but not required
parses hour from 24-hour clock using the
OH alternative numeric system, e.g. 十八 parses as tm_hour
18 in ja_JP locale
parses hour as a decimal number, 12 hour clock
I (range [01,12]), leading zeroes permitted but not tm_hour
required
parses hour from 12-hour clock using the
OI alternative numeric system, e.g. 六 reads as 06 tm_hour
in ja_JP locale
parses minute as a decimal number (range
M [00,59]), leading zeroes permitted but not tm_min
required
OM parses minute using the alternative numeric tm_min
system, e.g. 二十五 parses as 25 in ja_JP locale
parses second as a decimal number (range
S [00,60]), leading zeroes permitted but not tm_sec
required
OS parses second using the alternative numeric tm_sec
system, e.g. 二十四 parses as 24 in ja_JP locale

Other¶

parses the locale's standard date and time string
c format, e.g. Sun Oct 17 04:41:13 2010 (locale all
dependent)
parses the locale's alternative date and time
Ec string format, e.g. expecting 平成23年 (year all
Heisei 23) instead of 2011年 (year 2011) in ja_JP
locale
x parses the locale's standard date representation all
parses the locale's alternative date
Ex representation, e.g. expecting 平成23年 (year all
Heisei 23) instead of 2011年 (year 2011) in ja_JP
locale
X parses the locale's standard time representation all
EX parses the locale's alternative time all
representation
D equivalent to "%m / %d / %y " tm_mon, tm_mday,
tm_year
r parses locale's standard 12-hour clock time (in tm_hour, tm_min,
POSIX, "%I : %M : %S %p") tm_sec
R equivalent to "%H : %M" tm_hour, tm_min
T equivalent to "%H : %M : %S" tm_hour, tm_min,
tm_sec
p parses the locale's equivalent of a.m. or p.m. tm_hour

Note: tm_isdst is not written to, and needs to be set explicitly for use with
functions such as mktime

Return value¶

An object of unspecified type such that

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

where the function f is defined as:

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

std::ios_base::iostate err = std::ios_base::goodbit;
const TimeGet& tg = std::use_facet<TimeGet>(str.getloc());

tg.get(Iter(str.rdbuf()), Iter(), str, err, tmb,
fmt, fmt + Traits::length(fmt));

if (err != std::ios_base::goodbit)
str.setstate(err);
}

Notes¶

As specified in std::time_get::do_get, which this function calls, it's unspecified
if this function zero out the fields in *tmb that are not set directly by the
conversion specifiers that appear in fmt: portable programs should initialize every
field of *tmb to zero before calling std::get_time.

Example¶

Note: choose clang or gcc >= 12.1 to observe the output. libstdc++ before 12.1 does
not correctly implement the %b specifier: bug #78714.

// Run this code

#include <iomanip>
#include <iostream>
#include <locale>
#include <sstream>

int main()
{
std::tm t = {};
std::istringstream ss("2011-Februar-18 23:12:34");
ss.imbue(std::locale("de_DE.utf-8"));
ss >> std::get_time(&t, "%Y-%b-%d %H:%M:%S");

if (ss.fail())
std::cout << "Parse failed\n";
else
std::cout << std::put_time(&t, "%c") << '\n';
}

Possible output:¶

Sun Feb 18 23:12:34 2011

See also¶

time_get parses time/date values from an input character sequence into std::tm
(class template)
put_time formats and outputs a date/time value according to the specified format
(C++11) (function template)
parse parses a chrono object from a stream
(C++20) (function template)