NAME¶

std::time_get::get,std::time_get::do_get - std::time_get::get,std::time_get::do_get

Synopsis¶

Defined in header <locale>
public:

iter_type get( iter_type beg, iter_type end, std::ios_base& str,
std::ios_base::iostate& err, std::tm* t, (1) (since C++11)

const char_type* fmtbeg, const char_type* fmtend )
const;
protected:

virtual iter_type do_get( iter_type beg, iter_type end,
std::ios_base& str, (2) (since C++11)
std::ios_base::iostate& err, std::tm *t,

char format, char modifier ) const;

1) Parses the date and time from the input character sequence [beg, end) according
to the format provided in the character sequence [fmtbeg, fmtend). The format is
expected to follow the format described below, although actual processing of each
format specifier can be customized by overriding do_get. The get function performs
the following: First, clears the error bits in err by executing err =
std::ios_base::goodbit. Then enters a loop, which terminates whenever any of the
following conditions becomes true (checked in this order):
a) All characters have been read from the format string (fmtbeg == fmtend).
b) There was a parsing error (err != std::ios_base::goodbit).
c) All characters have been read from the input sequence (beg == end. If this
condition terminates the loop, the function sets both eofbit and failbit in err.

In the body of the loop, the following steps take place:
a) If the next character in the format string is '%', followed by one or two
characters that form a valid std::get_time conversion specifier (see below), these
characters are used in the call do_get(beg, end, str, err, t, format, modifier),
where format is the primary conversion specifier character, and modifier is the
optional modifier (which appears between % and the format character, if present). If
there is no modifier, the value '\0' is used. If the format string is ambiguous or
ends too early to determine the conversion specifier after '%', eofbit is set in err
and the loop is terminated. If, after the call to do_get, no error bits are set in
err, the function increments fmtbeg to point right after the conversion specifier
and continues the loop.
b) If the next character is whitespace, as indicated by the locale provided in the
stream str (i.e. std::isspace(*fmtbeg, str.getloc()) == true, the function keeps
incrementing fmtbeg until it either becomes equal to fmtend or points to a
non-whitespace character.
c) If the next character in the format string is equivalent to the next character in
the input stream according to case-insensitive comparison, the function advances
both sequences by one character ++fmtbeg, ++beg; and continues the loop, Otherwise,
it sets the failbit in err.
2) Parses one conversion specifier from the input sequence [beg, end) and updates
the std::tm structure pointed to by t accordingly.

First, clears the error bits in err by executing err = std::ios_base::goodbit. Then
reads characters from the input sequence [beg, end) that are expected by the
std::time_get format specifier formed by combining '%', modifier (if not '\0'), and
format. If the characters do not combine to form a valid conversion specifier, sets
failbit in err. If the end of the input stream is reached after reading a character,
sets eofbit in err. If the input string was parsed successfully, updates the
corresponding fields of *t.

For complex conversion specifiers, such as '%x' or '%c', or the directives that use
the modifiers 'E' and 'O', the function may fail to determine some of the values to
store in *t. In such case, it sets eofbit in err and leaves these fields in
unspecified state.

Parameters¶

beg - iterator designating the start of the sequence to parse
end - one past the end iterator for the sequence to parse
a stream object that this function uses to obtain locale facets when
str - needed, e.g. std::ctype to skip whitespace or std::collate to compare
strings
err - stream error flags object that is modified by this function to indicate
errors
t - pointer to the std::tm object that will hold the result of this function
call
fmtbeg - pointer to the first character of a sequence of char_type characters
specifying the conversion format (see below)
fmtend - pointer one past the last character of a sequence of char_type characters
specifying the conversion format
format - the character that names a conversion specifier
modifier - the optional modifier that may appear between % and the conversion
specifier

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 specification (none)
must be %%
t matches any whitespace (none)
n matches any whitespace (none)
Year
Y parses full year as a 4 digit decimal number, leading tm_year
zeroes permitted but not required
parses year in the alternative representation, e.g.平
EY 成23年 (year Heisei 23) which writes 2011 to tm_year in tm_year
ja_JP locale
parses last 2 digits of year as a decimal number. Range
y [69,99] results in values 1969 to 1999, range [00,68] tm_year
results in 2000-2068
parses last 2 digits of year using the alternative
Oy numeric system, e.g. 十一 is parsed as 11 in ja_JP tm_year
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 number tm_year
(range [00,99])
parses the name of the base year (period) in the
EC locale's alternative representation, e.g. 平成 (Heisei tm_year
era) in ja_JP
Month
b parses the month name, either full or abbreviated, e.g. tm_mon
Oct
h synonym of b tm_mon
B synonym of b tm_mon
m parses the month as a decimal number (range [01,12]), tm_mon
leading zeroes permitted but not required
Om parses the month using the alternative numeric system, tm_mon
e.g. 十二 parses as 12 in ja_JP locale
Week
parses the week of the year as a decimal number (Sunday tm_year, tm_wday,
U is the first day of the week) (range [00,53]), leading tm_yday
zeroes permitted but not required
parses the week of the year, as by %U, using the tm_year, tm_wday,
OU alternative numeric system, e.g. 五十二 parses as 52 in tm_yday
ja_JP locale
parses the week of the year as a decimal number (Monday tm_year, tm_wday,
W is the first day of the week) (range [00,53]), leading tm_yday
zeroes permitted but not required
parses the week of the year, as by %W, using the tm_year, tm_wday,
OW alternative numeric system, e.g. 五十二 parses as 52 in tm_yday
ja_JP locale
Day of the year/month
j parses day of the year as a decimal number (range tm_yday
[001,366]), leading zeroes permitted but not required
d parses the day of the month as a decimal number (range tm_mday
[01,31]), leading zeroes permitted but not 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 full or tm_wday
abbreviated, e.g. Fri
A synonym of a tm_wday
w parses weekday as a decimal number, where Sunday is 0 tm_wday
(range [0-6])
parses weekday as a decimal number, where Sunday is 0,
Ow using the alternative numeric system, e.g. 二 parses as tm_wday
2 in ja_JP locale
Hour, minute, second
parses the hour as a decimal number, 24 hour clock
H (range [00-23]), leading zeroes permitted but not tm_hour
required
OH parses hour from 24-hour clock using the alternative tm_hour
numeric system, e.g. 十八 parses as 18 in ja_JP locale
I parses hour as a decimal number, 12 hour clock (range tm_hour
[01,12]), leading zeroes permitted but not required
OI parses hour from 12-hour clock using the alternative tm_hour
numeric system, e.g. 六 reads as 06 in ja_JP locale
M parses minute as a decimal number (range [00,59]), tm_min
leading zeroes permitted but not required
OM parses minute using the alternative numeric system, tm_min
e.g. 二十五 parses as 25 in ja_JP locale
S parses second as a decimal number (range [00,60]), tm_sec
leading zeroes permitted but not required
OS parses second using the alternative numeric system, tm_sec
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 string
Ec format, e.g. expecting 平成23年 (year Heisei 23) all
instead of 2011年 (year 2011) in ja_JP locale
x parses the locale's standard date representation all
parses the locale's alternative date representation,
Ex e.g. expecting 平成23年 (year Heisei 23) instead of all
2011年 (year 2011) in ja_JP locale
X parses the locale's standard time representation all
EX parses the locale's alternative time representation all
D equivalent to "%m / %d / %y " tm_mon, tm_mday,
tm_year
r parses locale's standard 12-hour clock time (in POSIX, tm_hour, tm_min,
"%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¶

Iterator pointing one past the last character in [beg, end) that was parsed
successfully.

Notes¶

The case-insensitive comparison for the non-whitespace non-'%' characters in the
format string, the std::collate facet of the locale provided by str is typically,
but not necessarily, used.

If a parsing error is encountered, many implementations of this function leave *t
completely untouched.

It's unspecified if these functions zero out the fields in *t that they do not set
directly: portable programs should initialize every field to zero before calling
get().

Example¶

// Run this code

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

int main()
{
std::istringstream ss("2026-März-12 23:45:56");
ss.imbue(std::locale("de_DE.utf8"));

auto& f = std::use_facet<std::time_get<char>>(ss.getloc());
std::tm t{};
std::string s = "%Y-%b-%d %H:%M:%S";
std::ios_base::iostate err = std::ios_base::goodbit;
auto ret = f.get({ss}, {}, ss, err, &t, &s[0], &s[0] + s.size());
ss.setstate(err);
std::istreambuf_iterator<char> last{};

if (ss)
{
std::cout << "Successfully parsed as " << std::put_time(&t, "%c") << '\n';
if (ret != last)
{
std::cout << "Remaining content: ";
std::copy(ret, last, std::ostreambuf_iterator<char>(std::cout));
}
else
std::cout << "The input was fully consumed.";
}
else
{
std::cout << "Parse failed.\nUnparsed string: ";
std::copy(ret, last, std::ostreambuf_iterator<char>(std::cout));
}
std::cout << '\n';
}

Output:¶

Successfully parsed as Sun Mar 12 23:45:56 2026
The input was fully consumed.

See also¶

get_time parses a date/time value of specified format
(C++11) (function template)