public member function


iter_type get (iter_type s, iter_type end, ios_base& str,
    ios_base::iostate& err, tm* t, char format, char modifier=0) const;
iter_type get (iter_type s, iter_type end, ios_base& str,
    ios_base::iostate& err, tm* t, const char_type* fmt_begin, const char_type* fmt_end) const;
Read time and date
Parses the sequence of characters between s and end for a sequence with the format of time and/or date specified by format (or by the sequence between fmt_begin and fmt_end), and stores the obtained values into the tm object pointed by t.

The function reads characters until the character read cannot be part of a valid sequence in the format or end is reached. The next character after the last one processed by the function is pointed by the iterator returned by the function.

If successful, the function sets the relevant members of the tm structure t. The remaining members are left unchanged.

(1) single format specifier
This version simply calls the virtual protected member do_get, which by default parses the sequence following the same format produced by strftime using a string formed by a percentage sign ('%') followed by argument format, with modifier optionally inserted in between (when not equal to zero).
(2) format string
This version reads the characters in the range [fmt_begin,fmt_end) sequentially and interprets them in the same way scanf treats its format string, except that the format specifiers recognized by the function are those used by strftime instead. For each sequence of characters that would be recognized as an specifier for strftime, the virtual protected member do_get is called with the proper arguments.
The function uses the ctype facet of str's locale to determine whitespace characters.

A ios_base::iostate bitmask value is stored in err with the result of the operation:
value in errdescription
goodbitSuccess: The entire sequence [fmt_begin,fmt_end) was processed without reaching end.
failbitFailure: The sequence did not match the expected format.
eofbitend was reached:
Note: If this happen before the character preceding fmt_end has been processed, the function sets both failbit and eofbit.


s, end
Iterators pointing to the beginning and end characters of the sequence. The range used is [s,end), which contains all the characters between s and end, including the character pointed by s but not the character pointed by end.
Member type iter_type is the facet's iterator type (defined as an alias of time_get's second template parameter, InputIterator). By default, this is an istreambuf_iterator, allowing implicit conversions from basic_istream objects.
Object of a class derived from ios_base (generally an input stream object). It is only used to obtain formatting information.
Stream error state object, of type ios_base::iostate where the error states are stored.
Pointer to an object of type struct tm (defined in header <ctime>), whose members are set by a successful call to this member function.
Format specifier indicating the valid format for the sequence; For the default implementation of do_get, this shall be one of the specifiers accepted by strftime.
Some implementations allow for a format modifier to the specifier.
A value of 0 ('\0') is interpreted as no modifier.
fmt_begin, fmt_end
Pointers to the beginning and end characters of the sequence that forms the format string for the function.
Member type char_type is the facet's character type (defined as an alias of time_get's first template parameter, charT).
Note that, for both ranges, null characters (if any) are also considered valid, and the function proceeds beyond them, until a failure happens or either range is exhausted.

Return value

The next character in the sequence [s,end) right after the last character used by the operation.
Member type iter_type is the facet's iterator type (defined as an alias of time_get's second template parameter, InputIterator).


// time_get::get example
#include <iostream>       // std::cout, std::ios
#include <string>         // std::string
#include <sstream>        // std::istringstream
#include <ctime>          // std::tm
#include <locale>         // std::locale, std::time_get, std::use_facet

int main ()
  std::locale loc;        // classic "C" locale

  // get time_get facet:
  auto& tmget = std::use_facet <std::time_get<char> > (loc);

  std::ios::iostate state;
  std::istringstream iss ("year:2013 month:09 day:10");
  std::string format ("year:%Y month:%m day:%d");
  std::tm when;

  tmget.get (iss, std::time_get<char>::iter_type(), iss, state, &when,
   , );

  std::cout << "year: " << when.tm_year << '\n';
  std::cout << "mon: " << when.tm_mon << '\n';
  std::cout << "mday: " << when.tm_mday << '\n';
  return 0;


year: 113
mon: 8
mday: 10

Data races

The object, and up to the entire ranges between s and end and between fmt_begin and fmt_end, are accessed.
Arguments str, err and t may be modified.

Exception safety

If an exception is thrown, there are no changes in the facet object, although some of the arguments may have been affected.

See also