std::time_get<CharT,InputIt>::get_year, std::time_get<CharT,InputIt>::do_get_year

< cpp‎ | locale‎ | time get
Localizations library
Locales and facets
Facet category base classes
ctype facets
numeric facets
collate facets
time facets
monetary facets
messages facets
Character classification and conversion
Character classification
Code conversion facets
C locale
Text encoding identifications
Defined in header <locale>

iter_type get_year( iter_type s, iter_type end, std::ios_base& str,

                    std::ios_base::iostate& err, std::tm* t ) const;

virtual iter_type do_get_year( iter_type s, iter_type end, std::ios_base& str,

                               std::ios_base::iostate& err, std::tm* t ) const;
1) Public member function, calls the protected virtual member function do_get_year of the most derived class.
2) Reads successive characters from the sequence [begend) and parses out the year using some implementation-defined format. Depending on the locale, two-digit years may be accepted, and it is implementation-defined which century they belong to.

The parsed year is stored in the std::tm structure field t->tm_year.

If the end iterator is reached before a valid year is read, the function sets std::ios_base::eofbit in err. If a parsing error is encountered, the function sets std::ios_base::failbit in err.


[edit] Parameters

beg - iterator designating the start of the sequence to parse
end - one past the end iterator for the sequence to parse
str - a stream object that this function uses to obtain locale facets when needed, e.g. std::ctype to skip whitespace or std::collate to compare strings
err - stream error flags object that is modified by this function to indicate errors
t - pointer to the std::tm object that will hold the result of this function call

[edit] Return value

Iterator pointing one past the last character in [begend) that was recognized as a part of a valid year.

[edit] Notes

For two-digit input values, many implementations use the same parsing rules as the conversion specifier '%y' as used by std::get_time, std::time_get::get(), and the POSIX function strptime(): two-digit integer is expected, the values in the range [6999] results in values 1969 to 1999, range [0068] results in 2000 to 2068. Four-digit inputs are typically accepted as-is.

If a parsing error is encountered, most implementations of this function leave *t unmodified.

[edit] Example

#include <iostream>
#include <iterator>
#include <locale>
#include <sstream>
void try_get_year(const std::string& s)
    std::cout << "Parsing the year out of '" << s
              << "' in the locale " << std::locale().name() << '\n';
    std::istringstream str(s);
    std::ios_base::iostate err = std::ios_base::goodbit;
    std::tm t;
    std::time_get<char> const& facet = std::use_facet<std::time_get<char>>(str.getloc());
    std::istreambuf_iterator<char> ret = facet.get_year({str}, {}, str, err, &t);
    std::istreambuf_iterator<char> last{};
    if (str)
        std::cout << "Successfully parsed, year is " << 1900 + t.tm_year;
        if (ret != last)
            std::cout << " Remaining content: ";
            std::copy(ret, last, std::ostreambuf_iterator<char>(std::cout));
            std::cout << " the input was fully consumed";
        std::cout << "Parse failed. Unparsed string: ";
        std::copy(ret, last, std::ostreambuf_iterator<char>(std::cout));
    std::cout << '\n';
int main()

Possible output:

Parsing the year out of '13' in the locale en_US.utf8
Successfully parsed, year is 2013 the input was fully consumed
Parsing the year out of '2013' in the locale en_US.utf8
Successfully parsed, year is 2013 the input was fully consumed
Parsing the year out of '2013年' in the locale ja_JP.utf8
Successfully parsed, year is 2013 Remaining content: 年

[edit] Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR Applied to Behavior as published Correct behavior
LWG 248 C++98 eofbit was not set upon reaching the end iterator sets eofbit if a valid year has not been read

[edit] See also

parses a date/time value of specified format
(function template) [edit]