Library: Localization
time_base time_get
A time formatting facet for input, and for parsing of date and time values
#include <locale>
namespace std {
class time_base;
template <class charT, class InputIterator =
istreambuf_iterator<charT> >
class time_get;
}
The primary template can be implicitly or explicitly specialized on any character type that satisfies the requirements on the type of character used by iostream class templates, and on any iterator type that satisfies the requirements of Input Iterator.
Members of the time_get facet extract time and date components from a sequence of characters and store the resulting values in one or more members of a struct tm argument. The functions parse the input sequence according to the same locale-specific format as the one used by the time_put facet to format time and date values. If the sequence does not match the format, the facet indicates an error by setting ios_base::failbit in err. 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, as illustrated in Table 33:
| Order | Meaning |
no_order |
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 |
namespace std {
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;
// extension of this implementation
iter_type
get (iter_type, iter_type, ios_base&, ios_base::iostate&,
tm*, const char_type*, const char_type*) const;
// extension of this implementation
iter_type
get (iter_type, iter_type, ios_base&, ios_base::iostate&,
tm*, char, char) const;
static locale::id id;
protected:
virtual dateorder do_date_order() const;
virtual iter_type do_get_time(iter_type, iter_type,
ios_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,
ios_base&, ios_base::iostate&, tm*) const;
virtual iter_type do_get_monthname(iter_type, 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;
// extension of this implementation
virtual iter_type
do_get (iter_type, iter_type, ios_base&, ios_base::iostate&,
tm*, char, char) const;
};
}
char_type
Type of the first template argument, charT.
iter_type
Type of the second template argument, InputIterator.
explicit time_get(size_t refs = 0)
Constructs a time_get object. Calls locale::facet (refs).
The refs argument is set to the initial value of the time_get object's reference count. A time_get object f constructed with (refs == 0) that is installed in one or more locale objects will be destroyed and the storage it occupies will be deallocated when the last locale object containing the facet is destroyed, as if by calling delete static_cast<locale::facet*>(&f).
A time_get object constructed with (refs != 0) will not be destroyed by any locale objects in which it may have been installed.
virtual ~time_get();
Destroys the facet.
static locale::id id;
Unique identifier for this type of facet.
The public members of the time_get facet include an interface to protected members. Each public member function get_xxx() calls the corresponding protected virtual member function do_get_xxx(). For instance, the public function get_time() calls its protected cousin do_get_time(). The result of the call may be cached. Subsequent calls to the public function with the same arguments may return the cached result to avoid the expense of repeatedly calling the virtual function.
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 calls the corresponding protected virtual do_xxx() function.
iter_type get (iter_type s, iter_type end, ios_base &io,
ios_base::iostate &err,tm *t, const char_type *pat, const
char_type *pat_end) const;
The function iterates over characters in the range [pat, pat_end) that is composed of zero or more directives. Each directive is composed as follows: either a non-empty sequence of white-space characters (as determined by isspace(io.getloc(), c)); or an ordinary character other than '%' or white-space; or a conversion specification. Each conversion specification is composed of a leading '%' character followed by an optional conversion modifier, mod, and then by a conversion specifier, fmt, which determines the interpretation of the input character(s). The modifier and specifier characters are obtained by converting the (possibly wide) characters following the leading '%' character extracted from the input sequence as if by use_facet<ctype<char_type> >(io.getloc()).narrow(c, '\0').
For each ordinary character other than white-space, the function extracts a character from the input sequence and compares the two. If they are not equal, the function indicates an error by setting ios_base::failbit in err and the algorithm terminates. If the function reaches the end of the input sequence, it sets ios_base::eofbit in err and the algorithm terminates.
For each white-space character, the function extracts any white-space characters from the input sequence until it encounters a character other than white-space. If the function reaches the end of the input sequence, it sets ios_base::eofbit in err and the algorithm terminates.
For each conversion specification given by the characters fmt and mod, the function performs s = get (s, end, io, errtmp, t, fmt, mod) with a errtmp argument of type ios_base::iostate initialized to ios_base::good. If (errtmp != ios_base::good) evaluates to true after the call, the function performs err |= errtmp and the algorithm terminates.
Returns an iterator pointing just beyond the last extracted character.
iter_type get (iter_type s, iter_type end, ios_base &io,
ios_base::iostate &err, tm *t, char fmt, char mod = '\0')
const;
Returns do_get (s, end, io, err, t, fmt, mod).
The facet functions parse the string input sequence according to the same locale-specific format as the one used by the time_put facet to format time and date values. If the input sequence does not match the expected format, the functions indicate an error by setting ios_base::failbit in err. If the functions reach the end of the input sequence while attempting to extract additional characters, they set ios_base::eofbit in err. The io argument is used to obtain a reference to the ctype<char_type> facet installed in the object's locale.
The behavior of the functions is undefined if the t pointer does not point to a valid object of type tm.
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:
no_order, indicating that the date format has no ordering, an ordering cannot be determined, or the date format contains components other than Month, Day and Year. no_order is never returned by the primary template, but may be used by derived classes. In the C locale, the function returns mdy.
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 &io,
ios_base::iostate& err, tm* t) const;
Fills the appropriate members of the object pointed to by the t argument with values parsed from the character buffer specified by the range [s,end). Alphabetic characters are compared without regard to case. If the input sequence does not contain a valid date representation corresponding to the "%x" time_put specifier, then the object pointed to by t is not modified and ios_base::failbit is set in the err argument.
Returns an iterator pointing just beyond the last extracted character.
virtual iter_type
do_get_monthname(iter_type s, ios_base &io,
ios_base::iostate& err, tm* t) const;
Fills the t->tm_mon member with a month number (0 for January) 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 example, if a full name is "December", and an abbreviation is "Dec", then the string "Dece" causes an error. Characters are compared without regard to case. If an error occurs, then the object pointed to by t is not modified and ios_base::failbit is set in the err argument.
Returns an iterator pointing just beyond the last extracted character.
virtual iter_type
do_get_time(iter_type s, iter_type end, os_base &io,
ios_base::iostate& err, tm* t) const;
Fills out the appropriate members of the object pointed to by the t argument with time values parsed from the character buffer specified by the range [s,end). Alphabetic characters are compared without regard to case. If the input sequence does not contain a valid date representation corresponding to the "%X" time_put specifier, then the object pointed to by t is not modified and ios_base::failbit is set in the err argument.
Returns an iterator pointing just beyond the last extracted character.
virtual iter_type
do_get_weekday(iter_type s, iter_type end, ios_base &io,
ios_base::iostate& err, tm* t) const;
Fills the t->tm_wday member of the t argument with a weekday number (0 for Sunday) 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. Alphabetic characters are compared without regard to case. If an error occurs, then the object pointed to by t is not modified and ios_base::failbit is set in the err argument.
Returns an iterator pointing just beyond the last extracted character.
virtual iter_type
do_get_year(iter_type s, iter_type end, ios_base &io,
ios_base::iostate& err, tm* t) const;
Fills in the t->tm_year member of the t argument with a year parsed from the character buffer specified by the range [s,end). Values in the range [69,99] are assumed to refer to years 1969 through 1999, and values in the range [0, 68] are assumed to refer to years 2000 through 2068; all other values are assumed to include the century. This behavior follows the requirement on the strptime() function of IEEE Std 1003.1-2001. If an error occurs, then ios_base::failbit is set in the err argument.
Returns an iterator pointing just beyond the last extracted character.
iter_type
do_get (iter_type s, iter_type end, ios_base &io,
ios_base::iostate &err, tm *t, char fmt, char mod)
const;
Fills the appropriate members of the object pointed to by the t argument with values parsed from the character sequence in the range [s,end) according to the corresponding format specifier and, optionally, modifier (when (mod != '\0') evaluates to true). Alphabetic characters are compared without regard to case. If the input sequence does not match the format of the corresponding specifier and modifier, then the object pointed to by t is not modified and ios_base::failbit is set in the err argument.
The following format specifiers and modifiers are recognized, as illustrated in Table 34 and Table 35.
| Conversion Specifier | Description |
%a |
Represents the day of the week. %a uses the locale's weekday names, specifiying either the abbreviated or full name. |
%A |
Same as or equivalent to %a. |
%b |
Represents the month. %b uses the locale's month names, specifiying either the abbreviated or full name. |
%B |
Same as or equivalent to %b. |
%c |
Represents date and time formatted appropriate to the locale. |
%d |
Represents the day of the month as [01,31]. Leading zeros are optional. |
%D |
Represents the date, expressed as %m / %d / %y. |
%e |
Same as or equivalent to %d. |
%h |
Same as or equivalent to %b. |
%H |
Represents the hour in 24-hour clock form as [00,23]. Leading zeros are optional. |
%I |
Represents the hour in 12-hour clock form as [01,12]. Leading zeros are optional. |
%j |
Represents the day number of the year as [001,366]. Leading zeros are optional. |
%m |
Represents the month number as [01,12]. Leading zeros are optional. |
%M |
Expresses the minute as [00,59]. Leading zeros are optional. |
%n |
Represents blank (white) space. |
%p |
Represents "a.m "or "p.m" formatted as appropriate to the locale. |
%r |
Represents the 12-hour clock time using the AM/PM notation. In the classic C locale, equivalent to %I : %M : %S %p. |
%R |
Represents the time as %H : %M. |
%S |
Represents the seconds as [00,60]. Leading zeros are optional. |
%t |
Represents blank (white) space. |
%T |
Represents the time as %H : %M : %S. |
%U |
Represents the week number of the year as a decimal number ([00,53]) with Sunday representing as the first day of the week . Leading zeros are optional. |
%w |
Expresses the weekday as a decimal number [0,6]. 0 represents Sunday. Leading zeros are optional. |
%W |
The week number of the year (Monday as the first day of the week) as a decimal number [00,53]. Leading zeros are optional. |
%x |
Represents the date in the locale's date format. |
%X |
Represents the time in the locale's time format. |
%y |
Represents the year within the century. If a century is not specified, values in the range [59,99] will refer to years 1959 to 1999 inclusive, and values in the range [00,58] will refer to years 2000 to 2058 inclusive. Leading zeros are optional. |
%Y |
Represents the year and includes the century (e.g. 1988). |
%% |
Represents a literal % character. |
Table 35 describes the recognized modified conversion specifiers.
| Name | Description |
%Ec |
Represents the locale's alternative appropriate date and time conversion. |
%EC |
Represents the locale's alternative name of the base year (period) conversion. |
%Ex |
Represents the locale's alternative date conversion. |
%EX |
Represents the locale's alternative time conversion. |
%Ey |
Represents the offset from %EC (year only) in an alternate locale conversion. |
%EY |
Represents the full alternative year conversion. |
%Od |
Represents the day of the month by using alternate locale numeric symbols. Note, leading zeros are permitted but not required. |
%Oe |
Same as or equivalent to %Od. |
%OH |
Represents the hour in 24-hour clock form using alternate numeric symbols for the locale. |
%OI |
Represents the hour in 12-hour clock form using alternate numeric symbols for the locale. |
%Om |
Represents the month using alternate numeric symbols for the locale. |
%OM |
Represents the minutes using alternate numeric symbols for the locale. |
%OS |
Represents the seconds using alternate numeric symbols for the locale. |
%OU |
Represents the week number of the year, with Sunday as the first day of the week, using alternate numeric symbols for the locale. |
%Ow |
Represents the number of the weekday (Sunday=0) using alternative numeric symbols for the locale. |
%OW |
Represents the week number of the year, with Monday as the first day of the week, using alternate numeric symbols for the locale. |
%Oy |
Represents the year (offset from %C) using alternate numeric symbols for the locale. |
Returns an iterator pointing just beyond the last extracted character.
#include <ctime> // for struct tm
#include <locale> // for locale, time_get
#include <sstream> // for stringstream
#include <iostream> // for cout, endl
// Print out a tm struct value in one atomic operation
std::ostream& operator<< (std::ostream &os, const std::tm &t)
{
std::stringstream strm;
strm << "Daylight Savings = " << t.tm_isdst
<< "\nDay of year = " << t.tm_yday
<< "\nDay of week = " << t.tm_wday
<< "\nYear = " << t.tm_year
<< "\nMonth = " << t.tm_mon
<< "\nDay of month = " << t.tm_mday
<< "\nHour = " << t.tm_hour
<< "\nMinute = " << t.tm_min
<< "\nSecond = " << t.tm_sec
<< '\n';
// guard for thread safety and output synchronization
const std::ostream::sentry guard (os);
if (guard)
os.rdbuf ()->sputn (strm.str ().c_str (), strm.str ().size ());
else
os.setstate (os.failbit);
return os;
}
int main ()
{
typedef std::istreambuf_iterator<char, std::char_traits<char> > Iter;
// time struct to parse date into
static std::tm timeb; // zero initialized
// Unused, required by time_get
std::ios_base::iostate state;
// Stream object to read from
std::istringstream ins ("");
// Iterators into the stream object
Iter begin (ins);
Iter end;
const std::locale loc ("C");
// Get a reference to the time_get facet in locale loc.
const std::time_get<char, Iter> &tg =
std::use_facet<std::time_get<char, Iter> >(loc);
// Display time_base::dateorder value.
std::cout << "time_base::dateorder == " << tg.date_order () << ".\n";
// Insert date string into stream.
ins.str ("04/07/69");
// get_date from the stream and output tm contents.
tg.get_date (begin, end, ins, state, &timeb);
std::cout << "Date: Apr 7 1969\n" << timeb << std::endl;
// Insert weekday string into stream.
ins.str ("Monday");
// get_weekday from the stream and output tm contents.
tg.get_weekday (begin, end, ins, state, &timeb);
std::cout << "Weekday: Monday\n" << timeb << std::endl;
// Insert time string into stream.
ins.str ("06:47:32");
// get_time from the stream and output tm contents.
tg.get_time (begin, end, ins, state, &timeb);
std::cout << "Time: 06:47:32\n" << timeb << std::endl;
return 0;
}
Program Output:
time_base::dateorder == 2.
Date: Apr 7 1969
Daylight Savings = 0
Day of year = 0
Day of week = 0
Year = 69
Month = 3
Day of month = 7
Hour = 0
Minute = 0
Second = 0
Weekday: Monday
Daylight Savings = 0
Day of year = 0
Day of week = 1
Year = 69
Month = 3
Day of month = 7
Hour = 0
Minute = 0
Second = 0
Time: 06:47:32
Daylight Savings = 0
Day of year = 0
Day of week = 1
Year = 69
Month = 3
Day of month = 7
Hour = 6
Minute = 47
Second = 32
ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 22.2.5.1
IEEE Std 1003.1-2001 -- The Open Group Base Specifications Issue 6, strptime