std::time_get<CharT,InputIt>::get, std::time_get<CharT,InputIt>::do_get
Defined in header <locale>
|
||
public: iter_type get( iter_type beg, iter_type end, std::ios_base& str, |
(1) | (since C++11) |
protected: virtual iter_type do_get( iter_type beg, iter_type end, std::ios_base& str, |
(2) | (since C++11) |
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):eofbit
and failbit
in err.- In the body of the loop, the following steps take place:
%
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.failbit
in err.- 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, setseofbit
in err. If the input string was parsed successfully, updates the corresponding fields of *t.
- 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
- 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.
- 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
Contents |
[edit] Parameters
beg | - | iterator designating the start of the sequence to parse |
end | - | one past the end iterator for the sequence to parse |
str | - | a stream object that this function uses to obtain locale facets when 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 specifier |
Explanation | Writes to fields |
---|---|---|
%
|
matches a literal % . The full conversion specification must be %%
|
(none) |
t
|
matches any whitespace | (none) |
n
|
matches any whitespace | (none) |
Year | ||
Y
|
parses full year as a 4 digit decimal number, leading zeroes permitted but not required | tm_year
|
EY
|
parses year in the alternative representation, e.g.平成23年 (year Heisei 23) which writes 2011 to tm_year in ja_JP locale | tm_year
|
y
|
parses last 2 digits of year as a decimal number. Range [69,99] results in values 1969 to 1999, range [00,68] results in 2000-2068
|
tm_year
|
Oy
|
parses last 2 digits of year using the alternative numeric system, e.g. 十一 is parsed as 11 in ja_JP locale | tm_year
|
Ey
|
parses year as offset from locale's alternative calendar period %EC
|
tm_year
|
C
|
parses the first 2 digits of year as a decimal number (range [00,99] )
|
tm_year
|
EC
|
parses the name of the base year (period) in the locale's alternative representation, e.g. 平成 (Heisei era) in ja_JP | tm_year
|
Month | ||
b
|
parses the month name, either full or abbreviated, e.g. Oct
|
tm_mon
|
h
|
synonym of b
|
tm_mon
|
B
|
synonym of b
|
tm_mon
|
m
|
parses the month as a decimal number (range [01,12] ), leading zeroes permitted but not required
|
tm_mon
|
Om
|
parses the month using the alternative numeric system, e.g. 十二 parses as 12 in ja_JP locale | tm_mon
|
Week | ||
U
|
parses the week of the year as a decimal number (Sunday is the first day of the week) (range [00,53] ), leading zeroes permitted but not required
|
tm_year , tm_wday , tm_yday
|
OU
|
parses the week of the year, as by %U , using the alternative numeric system, e.g. 五十二 parses as 52 in ja_JP locale
|
tm_year , tm_wday , tm_yday
|
W
|
parses the week of the year as a decimal number (Monday is the first day of the week) (range [00,53] ), leading zeroes permitted but not required
|
tm_year , tm_wday , tm_yday
|
OW
|
parses the week of the year, as by %W , using the alternative numeric system, e.g. 五十二 parses as 52 in ja_JP locale
|
tm_year , tm_wday , tm_yday
|
Day of the year/month | ||
j
|
parses day of the year as a decimal number (range [001,366] ), leading zeroes permitted but not required
|
tm_yday
|
d
|
parses the day of the month as a decimal number (range [01,31] ), leading zeroes permitted but not required
|
tm_mday
|
Od
|
parses the day of the month using the alternative numeric system, e.g. 二十七 parses as 27 in ja_JP locale, leading zeroes permitted but not required | tm_mday
|
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 abbreviated, e.g. Fri
|
tm_wday
|
A
|
synonym of a
|
tm_wday
|
w
|
parses weekday as a decimal number, where Sunday is 0 (range [0-6] )
|
tm_wday
|
Ow
|
parses weekday as a decimal number, where Sunday is 0 , using the alternative numeric system, e.g. 二 parses as 2 in ja_JP locale
|
tm_wday
|
Hour, minute, second | ||
H
|
parses the hour as a decimal number, 24 hour clock (range [00-23] ), leading zeroes permitted but not required
|
tm_hour
|
OH
|
parses hour from 24-hour clock using the alternative numeric system, e.g. 十八 parses as 18 in ja_JP locale | tm_hour
|
I
|
parses hour as a decimal number, 12 hour clock (range [01,12] ), leading zeroes permitted but not required
|
tm_hour
|
OI
|
parses hour from 12-hour clock using the alternative numeric system, e.g. 六 reads as 06 in ja_JP locale | tm_hour
|
M
|
parses minute as a decimal number (range [00,59] ), leading zeroes permitted but not required
|
tm_min
|
OM
|
parses minute using the alternative numeric system, e.g. 二十五 parses as 25 in ja_JP locale | tm_min
|
S
|
parses second as a decimal number (range [00,60] ), leading zeroes permitted but not required
|
tm_sec
|
OS
|
parses second using the alternative numeric system, e.g. 二十四 parses as 24 in ja_JP locale | tm_sec
|
Other | ||
c
|
parses the locale's standard date and time string format, e.g. Sun Oct 17 04:41:13 2010 (locale dependent)
|
all |
Ec
|
parses the locale's alternative date and time string format, e.g. expecting 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale | all |
x
|
parses the locale's standard date representation | all |
Ex
|
parses the locale's alternative date representation, e.g. expecting 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale | all |
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, "%I : %M : %S %p") | tm_hour , tm_min , 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
[edit] Return value
Iterator pointing one past the last character in [beg, end) that was parsed successfully.
[edit] 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()
.
[edit] Example
#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.
[edit] See also
(C++11) |
parses a date/time value of specified format (function template) |