std::time_get::get,std::time_get::do_get(3)

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)