Name

time_get class template — Facet for input of dates and times

Synopsis

template <typename charT, typename InputIterator = istreambuf_iterator<charT> >
class time_get : public locale::facet, public time_base
{
public:
  typedef charT char_type;
  typedef InputIterator iter_type;
  explicit time_get(size_t refs = 0);
  dateorder date_order(  ) const;
  iter_type get_time(iter_type s, iter_type end, ios_base& f,
                     ios_base::iostate& err, tm* t) const;
  iter_type get_date(iter_type s, iter_type end, ios_base& f,
                     ios_base::iostate& err, tm* t) const;
  iter_type get_weekday(iter_type s, iter_type end,
                        ios_base& f, ios_base::iostate& err, tm* t) const;
  iter_type get_monthname(iter_type s, iter_type end,
                        ios_base& f, ios_base::iostate& err, tm* t) const;
  iter_type get_year(iter_type s, iter_type end, ios_base& f,
                    ios_base::iostate& err, tm* t) const;
  static locale::id id;
protected:
  virtual ~time_get(  );
  virtual dateorder do_date_order(  ) const;
  virtual iter_type do_get_time(iter_type s, iter_type end, ios_base&, 
                                ios_base::iostate& err, tm* t) const;
  virtual iter_type do_get_date(iter_type s, iter_type end, ios_base&, 
                                ios_base::iostate& err, tm* t) const;
  virtual iter_type do_get_weekday(iter_type s, iter_type end, ios_base&,
                                   ios_base::iostate& err, tm* t) const;
  virtual iter_type do_get_monthname(iter_type s, iter_type end, ios_base&,
                                     ios_base::iostate& err, tm* t) const;
  virtual iter_type do_get_year(iter_type s, iter_type end, ios_base&, 
                                ios_base::iostate& err, tm* t) const;
};

The time_get class template is a facet for parsing and reading dates and times from an input stream. The components of the date and time value are stored in a tm structure. (See <ctime> for more information about tm.) The time_get<char> and time_get<wchar_t> instantiations are standard.

Most of the time_get functions take an err parameter in much the same way other facets and their functions do. Unlike other facets, however, the time_get functions do not set err to goodbit upon success. Instead, they only set failbit for an error. They do not set eofbit if the end of the input sequence is reached.

Most of the time_get functions take a t parameter, which is a pointer to a tm object, which is filled in with the relevant parts of the date and time. If a function fails, the state of the tm object is undefined.

As with other facets, the public members call virtual, protected members with the same name prefaced by do_. Thus, to use the facet, call the public functions, such as get_date, which calls do_get_date. The descriptions below are for the virtual functions because they do the real work. Imagine that for each virtual-function description, there is a corresponding description for a public, nonvirtual function, such as:

dateorder date_order ( ) const

Returns do_date_order( )

The following are the virtual, protected members of time_get:

virtual dateorder do_date_order ( ) const

Returns the order in which the day, month, and year appear in a locale-specific date. If the formatted date includes additional elements, the return value is no_order. See the time_base class for the declaration of the dateorder type.

See Also virtual iter_type do_get_time (iter_type begin, iter_type end, ios_base& stream, ios_base::iostate& err, tm* t) const

Reads characters from [begin, end) and interprets them as a time, according to the format of time_put<>::put, using the 'X' format. The time elements are stored in *t. If the input is invalid, the state of t's members is undefined, and err is set to failbit. The return value is an iterator that points to one past where the input stopped.

virtual iter_type do_get_date (iter_type begin, iter_type end, ios_base& stream, ios_base::iostate& err, tm* t) const

Reads characters from [begin, end) and interprets them as a date, according to the format of time_put<>::put, using the 'x' format. The date elements are stored in *t. If the input is invalid, the state of t's members is undefined, and err is set to failbit. The return value is an iterator that points to one past where the input stopped.

virtual iter_type do_get_weekday (iter_type begin, iter_type end, ios_base& stream, ios_base::iostate& err, tm* t) const

Reads characters from [begin, end) until it reads the name of a day of the week, either abbreviated or spelled out. The appropriate date elements are stored in *t. If the input is invalid, the state of t's members is undefined, and err is set to failbit. The return value is an iterator that points to one past where the input stopped.

virtual iter_type do_get_monthname (iter_type begin, iter_type end, ios_base& stream, ios_base::iostate& err, tm* t) const

Reads characters from [begin, end) until it reads the name of a month, either abbreviated or spelled out. The appropriate date elements are stored in *t. If the input is invalid, the state of t's members is undefined, and err is set to failbit. The return value is an iterator that points to one past where the input stopped.

virtual iter_type do_get_year (iter_type begin, iter_type end, ios_base& stream, ios_base::iostate& err, tm* t) const

Reads characters from [begin, end) until it reads a year. It is up to the implementation to determine whether two-digit years are accepted, and if so, which century to apply to the abbreviated year. The t->tm_year member is set appropriately. If the input is invalid, the state of t's members is undefined, and err is set to failbit. The return value is an iterator that points to one past where the input stopped.