Previous fileTop of DocumentContentsIndex pageNext file
Apache C++ Standard Library Reference Guide

time_get

Library:  Localization


time_base time_get locale::facet

Local Index

Members

Summary

A time formatting facet for input, and for parsing of date and time values

Synopsis

#include <locale>

namespace std {
  class time_base;
  template <class charT, class InputIterator = 
              istreambuf_iterator<charT> >
  class time_get;
}

Specializations

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.

Description

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:

Table 33: Possible values of the dateorder function of the time_base class 

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

Interface

Member Types

char_type
iter_type

Constructors

explicit time_get(size_t refs = 0) 

Destructor

virtual ~time_get();

Facet ID

static locale::id id;

Public Member Functions

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; 

Extensions of this Implementation

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;

Protected Member Functions

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; 
virtual iter_type 
do_get_date(iter_type s, iter_type end, ios_base &io,
            ios_base::iostate& err, tm* t) const; 
virtual iter_type 
do_get_monthname(iter_type s, ios_base &io,
                 ios_base::iostate& err, tm* t) const; 
virtual iter_type 
do_get_time(iter_type s, iter_type end, os_base &io,
            ios_base::iostate& err, tm* t) const; 
virtual iter_type 
do_get_weekday(iter_type s, iter_type end, ios_base &io, 
               ios_base::iostate& err, tm* t) const; 
virtual iter_type 
do_get_year(iter_type s, iter_type end, ios_base &io, 
            ios_base::iostate& err, tm* t) const; 

Extension of this Implementation

iter_type 
do_get (iter_type s, iter_type end, ios_base &io,
        ios_base::iostate &err, tm *t, char fmt, char mod)
const;

Example

See Also

locale, Facets, time_put

Standards Conformance

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



Previous fileTop of DocumentContentsIndex pageNext file