|
VMS Help CXXLSTD, locales, time_get *Conan The Librarian |
Standard C++ Library
Copyright 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
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
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
|
|