.\" ident @(#)time_get.3
.\" Standard Template Library
.\" $$RW_INSERT_HEADER "slyrs.man"
.TH time_get 3C++ "02 Apr 1998" "Rogue Wave Software" "-"
.ce2
Standard C++ Library   
Copyright 1998, Rogue Wave Software, Inc.   

.SH NAME

\f2time_get\fP

\ - A time formatting facet for input. 



.SH  SYNOPSIS


.br
#include <locale>
.br
class time_base;
.br
template <class charT, class InputIterator = 
.RE
.RS 9
istreambuf_iterator<charT> >
.RE
.RS 0
class time_get;



.SH  DESCRIPTION


The_time_get facet extracts time and date components from a character string and stores the resulting values in a \f2struct tm\fP 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 \f2err\fP argument in the public member functions to \f2iosbase::failbit\fP. 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 \f2dateorder\fP function returns one of these five possible values:

ORDER		MEANING
  

\f2noorder\fP		\f2Date format has no set ordering\fP

\f2dmy\fP			\f2Date order is day, month, year\fP

\f2mdy\fP			\f2Date order is month, day, year\fP

\f2ymd\fP			\f2Date order is year, month, day\fP

\f2ydm\fP			\f2Date order is year, day, month\fP


.SH  INTERFACE



.br
class time_base {
.br
public:
.RE
.RS 1
enum dateorder { no_order, dmy, mdy, ymd, ydm };
.RE
.RS 0
};
.br

.br
template <class charT, class InputIterator = 
.RE
.RS 9
istreambuf_iterator<charT> >
.RE
.RS 0
class time_get : public locale::facet, public time_base {
.br
public:
.RE
.RS 1
typedef charT            char_type;
.br
typedef InputIterator    iter_type;
.br
explicit time_get(size_t = 0);
.br
dateorder date_order()  const;
.br
iter_type get_time(iter_type, iter_type, ios_base&,
.RE
.RS 20
ios_base::iostate&, tm*)  const;
.RE
.RS 1
iter_type get_date(iter_type, iter_type, ios_base&,
.RE
.RS 20
ios_base::iostate&, tm*)  const;
.RE
.RS 1
iter_type get_weekday(iter_type, iter_type, ios_base&,
.RE
.RS 23
ios_base::iostate&, tm*) const;
.RE
.RS 1
iter_type get_monthname(iter_type, iter_type, ios_base&,
.RE
.RS 25
ios_base::iostate&, tm*) const;
.RE
.RS 1
iter_type get_year(iter_type, iter_type, ios_base&,
.RE
.RS 20
ios_base::iostate&, tm*) const;
.RE
.RS 1
static locale::id id;
.RE
.RS 0
protected:
.RE
.RS 2
~time_get();  // virtual
.RE
.RS 1
virtual dateorder do_date_order()  const;
.br
virtual iter_type do_get_time(iter_type, iter_type,
.RE
.RS 9
os_base&, ios_base::iostate&, tm*) const;
.RE
.RS 1
virtual iter_type do_get_date(iter_type, iter_type,
.RE
.RS 9
ios_base&, ios_base::iostate&, tm*) const;
.RE
.RS 1
virtual iter_type do_get_weekday(iter_type, iter_type,
.RE
.RS 9
os_base&, ios_base::iostate&, tm*) const;
.RE
.RS 1
virtual iter_type do_get_monthname(iter_type, ios_base&,
.RE
.RS 9
ios_base::iostate&, tm*) const;
.RE
.RS 1
virtual iter_type do_get_year(iter_type, iter_type,
.RE
.RS 9
ios_base&, ios_base::iostate&, tm*) const;
.RE
.RS 0
};



.SH  TYPES



.br
char_type
.RE
.RS 3


Type of character the facet is instantiated on.

.RE


.br
iter_type
.RE
.RS 3


Type of iterator used to scan the character buffer.

.RE



.SH  CONSTRUCTORS 



.br
explicit time_get(size_t refs = 0) 
.RE
.RS 3


Constructs a time_get facet. If the \f2refs\fP argument is \f20\fP, 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 \f2refs\fP is \f21\fP, 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.

.RE



.SH  DESTRUCTORS



.br
~time_get();  // virtual and protected
.RE
.RS 3


Destroys the facet.

.RE



.SH  FACET ID



.br
static locale::id id;
.RE
.RS 3


Unique identifier for this type of facet. 

.RE



.SH  PUBLIC MEMBER FUNCTIONS


.RE
.RS 3


The public members of the time_get facet include an interface to protected members. Each public member \f2xxx\fP has a corresponding virtual protected member \f2do_xxx\fP. All work is delegated to these protected members.   For instance, the long version of the public \f2get_time\fP function simply calls its protected cousin \f2do_get_time\fP.

.RE


.br
dateorder 
.br
date_order()  const; 
.br
iter_type 
.br
get_date(iter_type s, iter_type end, ios_base& f,
.RE
.RS 8
ios_base::iostate& err, tm* t)  const; 
.RE
.RS 0
iter_type 
.br
get_monthname(iter_type s, iter_type end, ios_base& f,
.RE
.RS 13
ios_base::iostate& err, tm* t) const; 
.RE
.RS 0
iter_type 
.br
get_time(iter_type s, iter_type end, ios_base& f,
.RE
.RS 8
ios_base::iostate& err, tm* t)  const; 
.RE
.RS 0
iter_type 
.br
get_weekday(iter_type s, iter_type end, ios_base& f,
.RE
.RS 11
ios_base::iostate& err, tm* t) const; 
.RE
.RS 0
iter_type 
.br
get_year(iter_type s, iter_type end, ios_base& f,
.RE
.RS 8
ios_base::iostate& err, tm* t) const; 
.RE
.RS 3


Each of these public functions simply calls a corresponding protected virtual \f2do_\fP function.

.RE



.SH  PROTECTED MEMBER FUNCTIONS



.RE
.RS 0
virtual dateorder 
.br
do_date_order()  const; 
.RE
.RS 3


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

.RS .5i


.HP .5i
-	\f2noorder\fP, 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. \f2noorder\fP is never returned by the default time_put, but may be used by derived classes.
.HP .5i
-	One of \f2dmy, mdy, ymd, ydm\fP, indicating the relative ordering of Day, Month, and Year.
.RE
.RE


.br
virtual iter_type 
.br
do_get_date(iter_type s, iter_type end, ios_base&,
.RE
.RS 11
ios_base::iostate& err, tm* t) const; 
.RE
.RS 3


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

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

.RE


.RE
.RS 0
virtual iter_type 
.br
do_get_monthname(iter_type s, ios_base&,
.RE
.RS 16
ios_base::iostate& err, tm* t) const; 
.RE
.RS 3


Fills out the \f2tm_mon\fP member of the \f2t\fP argument with a month name parsed from the character buffer specified by the range \f2(s,end]\fP. As with \f2do_get_weekday\fP, 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 \f2err\fP argument is set to \f2iosbase::failbit\fP. 

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

.RE


.RE
.RS 0
virtual iter_type 
.br
do_get_time(iter_type s, iter_type end, os_base&,
.RE
.RS 11
ios_base::iostate& err, tm* t) const; 
.RE
.RS 3


Fills out the \f2t\fP argument with time values parsed from the character buffer specified by the range \f2(s,end]\fP. 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. 

.RE


.RE
.RS 0
virtual iter_type 
.br
do_get_weekday(iter_type s, iter_type end, os_base&, 
.RE
.RS 14
ios_base::iostate& err, tm* t) const; 
.RE
.RS 3


Fills out the \f2tm_wday\fP member of the \f2t\fP argument with a weekday name parsed from the character buffer specified by the range \f2(s,end]\fP. 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 \f2err\fP argument is set to \f2iosbase::failbit\fP. 

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

.RE


.RE
.RS 0
virtual iter_type 
.br
do_get_year(iter_type s, iter_type end, ios_base&, 
.RE
.RS 11
ios_base::iostate& err, tm* t) const; 
.RE
.RS 3


Fills in the \f2tm_year\fP member of the \f2t\fP argument with a year parsed from the character buffer specified by the range \f2(s,end]\fP. If an error occurs, then the \f2err\fP argument is set to \f2iosbase::failbit\fP. 

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

.RE



.SH  EXAMPLE



.RE
.RS 0
//
.br
// timeget.cpp
.br
//
.br
#include <locale>
.br
#include <sstream>
.br
#include <time.h>
.br

.RE
.RS 1
using namespace std;
.RE
.RS 0

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

.br
int main ()
.br
{
.RE
.RS 1
typedef istreambuf_iterator<char,char_traits<char> >
.RE
.RS 3
iter_type;
.RE
.RS 2

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

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

.RE
.RS 1
cout << timeb << endl;
.RE
.RS 2
{
.RE
.RS 4
// Build an istringstream from the buffer and construct
.br
// beginning and ending iterators on it.
.RE
.RS 3
istringstream ins("12:46:32");
.br
iter_type begin(ins);
.RE
.RS 0

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



.SH  SEE ALSO


locale, facets, time_put