Apache C++ Standard Library Reference Guide

## time_get

Library: Localization

             time_base
    time_get
             locale::facet

- Local Index
- Summary
- Synopsis
- Specializations
- Description
- Interface
- Member Types
- Constructors
- Destructor
- Facet ID
- Public Member Functions
- Extensions of this Implementation
- Protected Member Functions
- Extension of this Implementation
- Example
- See Also
- Standards Conformance

### Local Index

#### Members

char_type date_order() do_date_order() do_get() do_get_date() | do_get_monthname() do_get_time() do_get_weekday() do_get_year() get() | get_date() get_monthname() get_time() get_weekday() get_year() | id iter_type time_get() ~time_get()

### 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

    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;
      };
    }

### Member Types

    char_type

Type of the first template argument, `charT`.

    iter_type

Type of the second template argument, `InputIterator`.

### Constructors

    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.

### Destructor

    virtual ~time_get();

Destroys 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 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.

### 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;

Returns `do_get (s, end, io, err, t, fmt, mod)`.

### 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;

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.

### 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;

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.

#### Table 34: Recognized conversion specifiers

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.

#### Table 35: 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.

### Example

    #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

### 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