Standard C++ LibraryCopyright 1996, Rogue Wave Software, Inc.

NAME

  time_get - Time formatting facet for input.

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 will indicate 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 provides 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 AND DESTRUCTORS

  explicit time_get(size_t refs = 0)
     Construct 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
     had, if refs  is 1 then the object must be explicitly deleted; the
     locale will not do so.  In this case, the object can be maintained
     across the lifetime of multiple locales.

  ~time_get();  // virtual and protected
     Destroy 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 provide an interface to protected
  members.  Each public member xxx has a corresponding virtual protected
  member do_xxx.  All work is delagated 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;

     Return 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 will be 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 will
     attempt 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" will cause an error. If an
     error occurs then the  err argument will be 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 <DESC><LITERALLAYOUT>

  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 will attempt 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" will cause an error. If an error occurs then the  err
     argument will be 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 <DESC><LITERALLAYOUT>

  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 will be 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

STANDARDS CONFORMANCE

  ANSI X3J16/ISO WG21 Joint C++ Committee



privacy and legal statement