[locale.time.get]

# 28 Text processing library [[text]](./#text)

## 28.3 Localization library [[localization]](localization#locale.time.get)

### 28.3.4 Standard locale categories [[locale.categories]](locale.categories#locale.time.get)

#### 28.3.4.6 The time category [[category.time]](category.time#locale.time.get)

#### 28.3.4.6.2 Class template time_get [locale.time.get]

#### [28.3.4.6.2.1](#general) General [[locale.time.get.general]](locale.time.get.general)

[🔗](#lib:time_get)

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:using char_type = charT; using iter_type = InputIterator; explicit time_get(size_t refs = 0);

 dateorder date_order() const { return do_date_order(); } iter_type get_time(iter_type s, iter_type end, ios_base& f,
 ios_base::iostate& err, tm* t) const;
 iter_type get_date(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_monthname(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;
 iter_type get(iter_type s, iter_type end, ios_base& f,
 ios_base::iostate& err, tm* t, char format, char modifier = 0) const;
 iter_type get(iter_type s, iter_type end, ios_base& f,
 ios_base::iostate& err, tm* t, const char_type* fmt, const char_type* fmtend) const; static locale::id id; protected:~time_get(); virtual dateorder do_date_order() const; virtual iter_type do_get_time(iter_type s, iter_type end, ios_base&,
 ios_base::iostate& err, tm* t) const; virtual iter_type do_get_date(iter_type s, iter_type end, ios_base&,
 ios_base::iostate& err, tm* t) const; virtual iter_type do_get_weekday(iter_type s, iter_type end, ios_base&,
 ios_base::iostate& err, tm* t) const; virtual iter_type do_get_monthname(iter_type s, iter_type end, ios_base&,
 ios_base::iostate& err, tm* t) const; virtual iter_type do_get_year(iter_type s, iter_type end, ios_base&,
 ios_base::iostate& err, tm* t) const; virtual iter_type do_get(iter_type s, iter_type end, ios_base& f,
 ios_base::iostate& err, tm* t, char format, char modifier) const; };}

[1](#general-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3585)

time_get is used to parse a character sequence,
extracting components of a time or date into a tm object[.](#general-1.sentence-1)

Each get member parses a format as produced by a corresponding format specifier totime_put<>​::​put[.](#general-1.sentence-2)

If the sequence being parsed matches the correct format, the corresponding
members of thetm argument are set to the values used to produce the sequence; otherwise
either an error is reported or unspecified values are assigned[.](#general-1.sentence-3)[227](#footnote-227 "In other words, user confirmation is required for reliable parsing of user-entered dates and times, but machine-generated formats can be parsed reliably. This allows parsers to be aggressive about interpreting user variations on standard formats.")

[2](#general-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3604)

If the end iterator is reached during parsing by any of theget() member functions, the member setsios_base​::​eofbit in err[.](#general-2.sentence-1)

[227)](#footnote-227)[227)](#footnoteref-227)

In
other words, user confirmation is required for reliable parsing of
user-entered dates and times, but machine-generated formats can be
parsed reliably[.](#footnote-227.sentence-1)

This allows parsers to be aggressive about
interpreting user variations on standard formats[.](#footnote-227.sentence-2)

#### [28.3.4.6.2.2](#members) Members [[locale.time.get.members]](locale.time.get.members)

[🔗](#lib:time_get,date_order)

`dateorder date_order() const;
`

[1](#members-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3619)

*Returns*: do_date_order()[.](#members-1.sentence-1)

[🔗](#lib:time_get,get_time)

`iter_type get_time(iter_type s, iter_type end, ios_base& str,
                   ios_base::iostate& err, tm* t) const;
`

[2](#members-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3631)

*Returns*: do_get_time(s, end, str, err, t)[.](#members-2.sentence-1)

[🔗](#lib:time_get,get_date)

`iter_type get_date(iter_type s, iter_type end, ios_base& str,
                   ios_base::iostate& err, tm* t) const;
`

[3](#members-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3643)

*Returns*: do_get_date(s, end, str, err, t)[.](#members-3.sentence-1)

[🔗](#lib:time_get,get_weekday)

`iter_type get_weekday(iter_type s, iter_type end, ios_base& str,
                      ios_base::iostate& err, tm* t) const;
iter_type get_monthname(iter_type s, iter_type end, ios_base& str,
                        ios_base::iostate& err, tm* t) const;
`

[4](#members-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3658)

*Returns*: do_get_weekday(s, end, str, err, t) ordo_get_monthname(s, end, str, err, t)[.](#members-4.sentence-1)

[🔗](#lib:time_get,get_year)

`iter_type get_year(iter_type s, iter_type end, ios_base& str,
                   ios_base::iostate& err, tm* t) const;
`

[5](#members-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3672)

*Returns*: do_get_year(s, end, str, err, t)[.](#members-5.sentence-1)

[🔗](#lib:get,time_get)

`iter_type get(iter_type s, iter_type end, ios_base& f, ios_base::iostate& err,
              tm* t, char format, char modifier = 0) const;
`

[6](#members-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3684)

*Returns*: do_get(s, end, f, err, t, format, modifier)[.](#members-6.sentence-1)

[🔗](#lib:get,time_get_)

`iter_type get(iter_type s, iter_type end, ios_base& f, ios_base::iostate& err,
              tm* t, const char_type* fmt, const char_type* fmtend) const;
`

[7](#members-7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3696)

*Preconditions*: [fmt, fmtend) is a valid range[.](#members-7.sentence-1)

[8](#members-8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3700)

*Effects*: The function starts by evaluating err = ios_base​::​goodbit[.](#members-8.sentence-1)

It then enters a loop,
reading zero or more characters from s at each iteration[.](#members-8.sentence-2)

Unless otherwise specified below,
the loop terminates when the first of the following conditions holds:

- [(8.1)](#members-8.1)

  The expression fmt == fmtend evaluates to true[.](#members-8.1.sentence-1)

- [(8.2)](#members-8.2)

  The expression err == ios_base​::​goodbit evaluates to false[.](#members-8.2.sentence-1)

- [(8.3)](#members-8.3)

  The expression s == end evaluates to true,
in which case
the function evaluates err = ios_base​::​eofbit | ios_base​::​failbit[.](#members-8.3.sentence-1)

- [(8.4)](#members-8.4)

  The next element of fmt is equal to '%',
optionally followed by a modifier character,
followed by a conversion specifier character, format,
together forming a conversion specification
valid for the POSIX function strptime[.](#members-8.4.sentence-1)
  If the number of elements in the range [fmt, fmtend)
is not sufficient to unambiguously determine
whether the conversion specification is complete and valid,
the function evaluates err = ios_base​::​failbit[.](#members-8.4.sentence-2)
  Otherwise,
the function evaluates s = do_get(s, end, f, err, t, format, modifier),
where the value of modifier is '\0' when the optional modifier is absent from the conversion specification[.](#members-8.4.sentence-3)
  If err == ios_base​::​goodbit holds
after the evaluation of the expression,
the function increments fmt to point just past the end of the conversion specification and
continues looping[.](#members-8.4.sentence-4)

- [(8.5)](#members-8.5)

  The expression isspace(*fmt, f.getloc()) evaluates to true,
in which case the function first increments fmt untilfmt == fmtend || !isspace(*fmt, f.getloc()) evaluates to true,
then advances s until s == end || !isspace(*s, f.getloc()) is true, and
finally resumes looping[.](#members-8.5.sentence-1)

- [(8.6)](#members-8.6)

  The next character read from s matches the element pointed to by fmt in a case-insensitive comparison,
in which case the function evaluates ++fmt, ++s and continues looping[.](#members-8.6.sentence-1)
  Otherwise, the function evaluates err = ios_base​::​failbit[.](#members-8.6.sentence-2)

[9](#members-9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3752)

[*Note [1](#members-note-1)*:

The function uses the ctype<charT> facet
installed in f's locale
to determine valid whitespace characters[.](#members-9.sentence-1)

It is unspecified
by what means the function performs case-insensitive comparison or
whether multi-character sequences are considered while doing so[.](#members-9.sentence-2)

— *end note*]

[10](#members-10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3762)

*Returns*: s[.](#members-10.sentence-1)

#### [28.3.4.6.2.3](#virtuals) Virtual functions [[locale.time.get.virtuals]](locale.time.get.virtuals)

[🔗](#lib:time_get,do_date_order)

`dateorder do_date_order() const;
`

[1](#virtuals-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3775)

*Returns*: An enumeration value indicating the preferred order of components
for those date formats that are composed of day, month, and year[.](#virtuals-1.sentence-1)[228](#footnote-228 "This function is intended as a convenience only, for common formats, and can return no_­order in valid locales.")

Returns no_order if the date format specified by 'x' contains other variable components (e.g., Julian day, week number, week day)[.](#virtuals-1.sentence-2)

[🔗](#lib:time_get,do_get_time)

`iter_type do_get_time(iter_type s, iter_type end, ios_base& str,
                      ios_base::iostate& err, tm* t) const;
`

[2](#virtuals-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3794)

*Effects*: Reads characters starting at s until it has extracted those tm members, and
remaining format characters,
used by time_put<>​::​put to produce the format specified by "%H:%M:%S",
or until it encounters an error or end of sequence[.](#virtuals-2.sentence-1)

[3](#virtuals-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3803)

*Returns*: An iterator pointing immediately beyond
the last character recognized as possibly part of a valid time[.](#virtuals-3.sentence-1)

[🔗](#lib:time_get,do_get_date)

`iter_type do_get_date(iter_type s, iter_type end, ios_base& str,
                      ios_base::iostate& err, tm* t) const;
`

[4](#virtuals-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3816)

*Effects*: Reads characters starting at s until it has extracted those tm members and
remaining format characters
used by time_put<>​::​put to produce one of the following formats,
or until it encounters an error[.](#virtuals-4.sentence-1)

The format depends on the value returned by date_order() as shown in Table [102](#tab:locale.time.get.dogetdate "Table 102: do_­get_­date effects")[.](#virtuals-4.sentence-2)

Table [102](#tab:locale.time.get.dogetdate) — do_get_date effects [[tab:locale.time.get.dogetdate]](./tab:locale.time.get.dogetdate)  

| [🔗](#tab:locale.time.get.dogetdate-row-1)<br>**date_order()** | **Format** |
| --- | --- |
| [🔗](#tab:locale.time.get.dogetdate-row-2)<br>no_order | "%m%d%y" |
| [🔗](#tab:locale.time.get.dogetdate-row-3)<br>dmy | "%d%m%y" |
| [🔗](#tab:locale.time.get.dogetdate-row-4)<br>mdy | "%m%d%y" |
| [🔗](#tab:locale.time.get.dogetdate-row-5)<br>ymd | "%y%m%d" |
| [🔗](#tab:locale.time.get.dogetdate-row-6)<br>ydm | "%y%d%m" |

[5](#virtuals-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3836)

An implementation may also accept additionalimplementation-defined formats[.](#virtuals-5.sentence-1)

[6](#virtuals-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3840)

*Returns*: An iterator pointing immediately beyond
the last character recognized as possibly part of a valid date[.](#virtuals-6.sentence-1)

[🔗](#lib:time_get,do_get_weekday)

`iter_type do_get_weekday(iter_type s, iter_type end, ios_base& str,
                         ios_base::iostate& err, tm* t) const;
iter_type do_get_monthname(iter_type s, iter_type end, ios_base& str,
                           ios_base::iostate& err, tm* t) const;
`

[7](#virtuals-7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3856)

*Effects*: Reads characters starting at s until it has extracted the (perhaps abbreviated) name of a weekday or month[.](#virtuals-7.sentence-1)

If it finds an abbreviation
that is followed by characters that can match a full name,
it continues reading until it matches the full name or fails[.](#virtuals-7.sentence-2)

It sets the appropriate tm member accordingly[.](#virtuals-7.sentence-3)

[8](#virtuals-8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3865)

*Returns*: An iterator pointing immediately beyond the last character recognized
as part of a valid name[.](#virtuals-8.sentence-1)

[🔗](#lib:time_get,do_get_year)

`iter_type do_get_year(iter_type s, iter_type end, ios_base& str,
                      ios_base::iostate& err, tm* t) const;
`

[9](#virtuals-9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3878)

*Effects*: Reads characters starting at s until it has extracted an unambiguous year identifier[.](#virtuals-9.sentence-1)

It isimplementation-defined
whether two-digit year numbers are accepted,
and (if so) what century they are assumed to lie in[.](#virtuals-9.sentence-2)

Sets the t->tm_year member accordingly[.](#virtuals-9.sentence-3)

[10](#virtuals-10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3888)

*Returns*: An iterator pointing immediately beyond
the last character recognized as part of a valid year identifier[.](#virtuals-10.sentence-1)

[🔗](#lib:do_get,time_get)

`iter_type do_get(iter_type s, iter_type end, ios_base& f,
                 ios_base::iostate& err, tm* t, char format, char modifier) const;
`

[11](#virtuals-11)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3901)

*Preconditions*: t points to an object[.](#virtuals-11.sentence-1)

[12](#virtuals-12)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3905)

*Effects*: The function starts by evaluating err = ios_base​::​goodbit[.](#virtuals-12.sentence-1)

It then reads characters starting at s until it encounters an error, or
until it has extracted and assigned those tm members, and
any remaining format characters,
corresponding to a conversion specification appropriate for
the POSIX function strptime,
formed by concatenating '%',
the modifier character, when non-NUL, and
the format character[.](#virtuals-12.sentence-2)

When the concatenation fails to yield a complete valid directive
the function leaves the object pointed to by t unchanged and
evaluates err |= ios_base​::​failbit[.](#virtuals-12.sentence-3)

When s == end evaluates to true after reading a character
the function evaluates err |= ios_base​::​eofbit[.](#virtuals-12.sentence-4)

[13](#virtuals-13)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3922)

For complex conversion specifications
such as %c, %x, or %X, or
conversion specifications that involve the optional modifiers E or O,
when the function is unable to unambiguously determine
some or all tm members from the input sequence [s, end),
it evaluates err |= ios_base​::​eofbit[.](#virtuals-13.sentence-1)

In such cases the values of those tm members are unspecified
and may be outside their valid range[.](#virtuals-13.sentence-2)

[14](#virtuals-14)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3932)

*Returns*: An iterator pointing immediately beyond
the last character recognized as possibly part of
a valid input sequence for the given format and modifier[.](#virtuals-14.sentence-1)

[15](#virtuals-15)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3938)

*Remarks*: It is unspecified whether multiple calls to do_get() with the address of the same tm object
will update the current contents of the object or simply overwrite its members[.](#virtuals-15.sentence-1)

Portable programs should zero out the object before invoking the function[.](#virtuals-15.sentence-2)

[228)](#footnote-228)[228)](#footnoteref-228)

This function is intended as a convenience only, for common formats, and
can return no_order in valid locales[.](#footnote-228.sentence-1)