## time_get

            time_get_base
    time_get
            locale::facet

- Summary
- Data Type and Member Function Indexes
- Synopsis
- Description
- Interface
- Types
- Constructors
- Destructors
- Facet ID
- Public Member Functions
- Protected Member Functions
- Example
- See Also

### Summary

A time formatting facet for input.

### Data Type and Member Function Indexes
(exclusive of constructors and destructors)

Data Types
char_type id iter_type

Member Functions
date_order() do_date_order() do_get_date() do_get_monthname() do_get_time() do_get_weekday() | do_get_year() get_date() get_monthname() get_time() get_weekday() get_year() |

### Synopsis

    #include <locale>
    class time_base;
    template <class charT, class InputIterator =
              istreambuf_iterator<charT> >
    class time_get;

### Description

The time_get facet extracts time and date components from a character string and stores the resulting values in a `struct tm` argument. The facet parses the string using a specific format as a guide. If the string does not fit the format, then the facet indicates an error by setting the `err` argument in the public member functions to `iosbase::failbit`. See member function descriptions for details.

The time_base class includes a set of values for specifying the order in which the three parts of a date appear. The `dateorder` function returns one of these five possible values:

####

Order | Meaning
--- | ---
`noorder` | `Date format has no set ordering`
`dmy` | `Date order is day, month, year`
`mdy` | `Date order is month, day, year`
`ymd` | `Date order is year, month, day`
`ydm` | `Date order is year, day, month`

### Interface

    class time_base {
    public:
      enum dateorder { no_order, dmy, mdy, ymd, ydm };
    };

    template <class charT, class 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 = 0);
      dateorder date_order()  const;
      iter_type get_time(iter_type, iter_type, ios_base&,
                         ios_base::iostate&, tm*)  const;
      iter_type get_date(iter_type, iter_type, ios_base&,
                         ios_base::iostate&, tm*)  const;
      iter_type get_weekday(iter_type, iter_type, ios_base&,
                            ios_base::iostate&, tm*) const;
      iter_type get_monthname(iter_type, iter_type, ios_base&,
                              ios_base::iostate&, tm*) const;
      iter_type get_year(iter_type, iter_type, ios_base&,
                         ios_base::iostate&, tm*) const;
      static locale::id id;
    protected:
      ~time_get();  // virtual
      virtual dateorder do_date_order()  const;
      virtual iter_type do_get_time(iter_type, iter_type,
              os_base&, ios_base::iostate&, tm*) const;
      virtual iter_type do_get_date(iter_type, iter_type,
              ios_base&, ios_base::iostate&, tm*) const;
      virtual iter_type do_get_weekday(iter_type, iter_type,
              os_base&, ios_base::iostate&, tm*) const;
      virtual iter_type do_get_monthname(iter_type, ios_base&,
              ios_base::iostate&, tm*) const;
      virtual iter_type do_get_year(iter_type, iter_type,
              ios_base&, ios_base::iostate&, tm*) const;
    };

### Types

    char_type

Type of character the facet is instantiated on.

    iter_type

Type of iterator used to scan the character buffer.

### Constructors

    explicit time_get(size_t refs = 0)

Constructs a time_get facet. If the `refs` argument is `0`, then destruction of the object is delegated to the locale, or locales, containing it. This allows the user to ignore lifetime management issues. On the other hand, if `refs` is `1`, then the object must be explicitly deleted; the locale does not do so. In this case, the object can be maintained across the lifetime of multiple locales.

### Destructors

    ~time_get();  // virtual and protected

Destroys the facet.

### Facet ID

    static locale::id id;

Unique identifier for this type of facet.

### Public Member Functions

The public members of the time_get facet include an interface to protected members. Each public member `xxx` has a corresponding virtual protected member `do_xxx`. All work is delegated to these protected members. For instance, the long version of the public `get_time` function simply calls its protected cousin `do_get_time`.

    dateorder
    date_order()  const;
    iter_type
    get_date(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_time(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_year(iter_type s, iter_type end, ios_base& f,
             ios_base::iostate& err, tm* t) const;

Each of these public functions simply calls a corresponding protected virtual `do_` function.

### Protected Member Functions

    virtual dateorder
    do_date_order()  const;

Returns the a value indicating the relative ordering of the three basic parts of a date. Possible return values are:

- `noorder`, indicating that the date format has no ordering, an ordering cannot be determined, or the date format contains variable components other than Month, Day and Year. `noorder` is never returned by the default time_put, but may be used by derived classes.

- One of `dmy, mdy, ymd, ydm`, indicating the relative ordering of Day, Month, and Year.

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

Fills out the `t` argument with date values parsed from the character buffer specified by the range `(s,end]`. If the buffer does not contain a valid date representation, then the err argument is set to `iosbase::failbit`.

Returns an iterator pointing just beyond the last character that can be determined to be part of a valid date.

    virtual iter_type
    do_get_monthname(iter_type s, ios_base&,
                     ios_base::iostate& err, tm* t) const;

Fills out the `tm_mon` member of the `t` argument with a month name parsed from the character buffer specified by the range `(s,end]`. As with `do_get_weekday`, this name may be an abbreviation, but the function attempts to read a full name if valid characters are found after an abbreviation. For example, if a full name is "December", and an abbreviation is "Dec", then the string "Dece" causes an error. If an error occurs, then the `err` argument is set to `iosbase::failbit`.

Returns an iterator pointing just beyond the last character that can be determined to be part of a valid name.

    virtual iter_type
    do_get_time(iter_type s, iter_type end, os_base&,
                ios_base::iostate& err, tm* t) const;

Fills out the `t` argument with time values parsed from the character buffer specified by the range `(s,end]`. The buffer must contain a valid time representation. Returns an iterator pointing just beyond the last character that can be determined to be part of a valid time.

    virtual iter_type
    do_get_weekday(iter_type s, iter_type end, os_base&,
                   ios_base::iostate& err, tm* t) const;

Fills out the `tm_wday` member of the `t` argument with a weekday name parsed from the character buffer specified by the range `(s,end]`. This name may be an abbreviation, but the function attempts to read a full name if valid characters are found after an abbreviation. For instance, if a full name is "Monday", and an abbreviation is "Mon", then the string "Mond" causes an error. If an error occurs, then the `err` argument is set to `iosbase::failbit`.

Returns an iterator pointing just beyond the last character that can be determined to be part of a valid name.

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

Fills in the `tm_year` member of the `t` argument with a year parsed from the character buffer specified by the range `(s,end]`. If an error occurs, then the `err` argument is set to `iosbase::failbit`.

Returns an iterator pointing just beyond the last character that can be determined to be part of a valid year.

### Example

    //
    // timeget.cpp
    //
    #include <locale>
    #include <sstream>
    #include <time.h>

      using namespace std;

    // Print out a tm struct
    ostream& operator<< (ostream& os, const struct tm& t)
    {
      os << "Daylight Savings = " << t.tm_isdst << endl;
      os << "Day of year      = " << t.tm_yday << endl;
      os << "Day of week      = " << t.tm_wday << endl;
      os << "Year             = " << t.tm_year << endl;
      os << "Month            = " << t.tm_mon << endl;
      os << "Day of month     = " << t.tm_mday << endl;
      os << "Hour             = " << t.tm_hour << endl;
      os << "Minute           = " << t.tm_min << endl;
      os << "Second           = " << t.tm_sec << endl;
      return os;
    }

    int main ()
    {
      typedef istreambuf_iterator<char,char_traits<char> >
        iter_type;

      locale loc;
      time_t tm = time(NULL);
      struct tm* tmb = localtime(&tm);
      struct tm timeb;
      memcpy(&timeb,tmb,sizeof(struct tm));
      ios_base::iostate state;
      iter_type end;

      // Get a time_get facet
      const time_get<char,iter_type>& tg =
    #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
      use_facet<time_get<char,iter_type> >(loc);
    #else
      use_facet(loc,(time_get<char,iter_type>*)0);
    #endif

      cout << timeb << endl;
      {
        // Build an istringstream from the buffer and construct
        // beginning and ending iterators on it.
        istringstream ins("12:46:32");
        iter_type begin(ins);

        // Get the time
        tg.get_time(begin,end,ins,state,&timeb);
      }
      cout << timeb << endl;
      {
        // Get the date
        istringstream ins("Dec 6 1996");
        iter_type begin(ins);
        tg.get_date(begin,end,ins,state,&timeb);
      }
      cout << timeb << endl;
      {
        // Get the weekday
        istringstream ins("Tuesday");
        iter_type begin(ins);
        tg.get_weekday(begin,end,ins,state,&timeb);
      }
      cout << timeb << endl;
      return 0;
    }

### See Also

locale, facets, time_put

Copyright (c) 1998, Rogue Wave Software, Inc.
Send mail to report errors or comment on the documentation.
OEM Release, June 1998