std::get_time(3)

💖 std::get_time 💖

okay bestie, welcome to std::get_time — part of the C++ Standard Library, and honestly? lowkey iconic. she's serving parse a date out of a stream and she does it with the std::time_get facet energy. no cap, we're gonna go through the whole thing together, every single specifier, so grab a boba 🍓

✨ SYNOPSIS ✨

Defined in header <iomanip>

template< class CharT >                                      (since C++11)
/*unspecified*/ get_time( std::tm* tmb, const CharT* fmt );

so here's the vibe 💅 — when you use it inside an expression like in >> get_time(tmb, fmt), it reads the character input and parses it as a date/time value according to the format string fmt, and it does that according to the std::time_get facet of the locale that's currently imbued in the input stream in. the resultant value gets stored in the std::tm object pointed to by tmb. simple as that, periodt.

---

🌸 PARAMETERS 🌸

• tmb — a valid pointer to the std::tm object where the result will be stored 🫶
• fmt — pointer to a null-terminated CharT string that specifies the conversion format

okay so the format string is made of zero or more conversion specifiers, whitespace characters, and ordinary characters (everything except %). let's break that down because this ate:

• each ordinary character is expected to match one character in the input stream, and the comparison is case-insensitive (yes, she's chill like that)
• each whitespace character matches arbitrary whitespace in the input string
• each conversion specification begins with the % character, optionally followed by an E or O modifier (which is ignored if the locale doesn't support it — not me being flexible 💅), followed by the character that determines the behavior of the specifier
• the format specifiers match the POSIX function strptime() — iykyk

---

🌈 the conversion specifiers, in all their glory 🌈

🎀 the misc girlies (year-agnostic)

• %% — matches a literal %. tbh the full conversion specification must be %%. Writes to: none.
• %t — matches any whitespace. Writes to: none.
• %n — matches any whitespace. Writes to: none.

🗓️ Year

• %Y — parses full year as a 4 digit decimal number, leading zeroes permitted but not required. Writes to tm_year.
• %EY — parses year in the alternative representation, e.g. 平成23年 (year Heisei 23) which writes 2011 to tm_year in the ja_JP locale. Writes to tm_year.
• %y — parses last 2 digits of year as a decimal number. Range [69,99] results in values 1969 to 1999, range [00,68] results in 2000-2068. Writes to tm_year.
• %Oy — parses last 2 digits of year using the alternative numeric system, e.g. 十一 is parsed as 11 in the ja_JP locale. Writes to tm_year.
• %Ey — parses year as offset from locale's alternative calendar period %EC. Writes to tm_year.
• %C — parses the first 2 digits of year as a decimal number (range [00,99]). Writes to tm_year.
• %EC — parses the name of the base year (period) in the locale's alternative representation, e.g. 平成 (Heisei era) in ja_JP. Writes to tm_year.

🌙 Month

• %b — parses the month name, either full or abbreviated, e.g. Oct. Writes to tm_mon.
• %h — synonym of %b. Writes to tm_mon.
• %B — synonym of %b. Writes to tm_mon.
• %m — parses the month as a decimal number (range [01,12]), leading zeroes permitted but not required. Writes to tm_mon.
• %Om — parses the month using the alternative numeric system, e.g. 十二 parses as 12 in the ja_JP locale. Writes to tm_mon.

🦋 Week

• %U — parses the week of the year as a decimal number (Sunday is the first day of the week) (range [00,53]), leading zeroes permitted but not required. Writes to tm_year, tm_wday, tm_yday.
• %OU — parses the week of the year, as by %U, using the alternative numeric system, e.g. 五十二 parses as 52 in the ja_JP locale. Writes to tm_year, tm_wday, tm_yday.
• %W — parses the week of the year as a decimal number (Monday is the first day of the week) (range [00,53]), leading zeroes permitted but not required. Writes to tm_year, tm_wday, tm_yday.
• %OW — parses the week of the year, as by %W, using the alternative numeric system, e.g. 五十二 parses as 52 in the ja_JP locale. Writes to tm_year, tm_wday, tm_yday.

🧚 Day of the year / month

• %j — parses day of the year as a decimal number (range [001,366]), leading zeroes permitted but not required. Writes to tm_yday.
• %d — parses the day of the month as a decimal number (range [01,31]), leading zeroes permitted but not required. Writes to tm_mday.
• %Od — parses the day of the month using the alternative numeric system, e.g. 二十七 parses as 27 in the ja_JP locale, leading zeroes permitted but not required. Writes to tm_mday.
• %e — synonym of %d. Writes to tm_mday.
• %Oe — synonym of %Od. Writes to tm_mday.

🌸 Day of the week

• %a — parses the name of the day of the week, either full or abbreviated, e.g. Fri. Writes to tm_wday.
• %A — synonym of %a. Writes to tm_wday.
• %w — parses weekday as a decimal number, where Sunday is 0 (range [0-6]). Writes to tm_wday.
• %Ow — parses weekday as a decimal number, where Sunday is 0, using the alternative numeric system, e.g. 二 parses as 2 in the ja_JP locale. Writes to tm_wday.

⏰ Hour, minute, second

• %H — parses the hour as a decimal number, 24 hour clock (range [00-23]), leading zeroes permitted but not required. Writes to tm_hour.
• %OH — parses hour from 24-hour clock using the alternative numeric system, e.g. 十八 parses as 18 in the ja_JP locale. Writes to tm_hour.
• %I — parses hour as a decimal number, 12 hour clock (range [01,12]), leading zeroes permitted but not required. Writes to tm_hour.
• %OI — parses hour from 12-hour clock using the alternative numeric system, e.g. 六 reads as 06 in the ja_JP locale. Writes to tm_hour.
• %M — parses minute as a decimal number (range [00,59]), leading zeroes permitted but not required. Writes to tm_min.
• %OM — parses minute using the alternative numeric system, e.g. 二十五 parses as 25 in the ja_JP locale. Writes to tm_min.
• %S — parses second as a decimal number (range [00,60]), leading zeroes permitted but not required. Writes to tm_sec.
• %OS — parses second using the alternative numeric system, e.g. 二十四 parses as 24 in the ja_JP locale. Writes to tm_sec.

💜 Other (the combo-meal specifiers, obsessed)

• %c — parses the locale's standard date and time string format, e.g. Sun Oct 17 04:41:13 2010 (locale dependent). Writes to: all.
• %Ec — parses the locale's alternative date and time string format, e.g. expecting 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in the ja_JP locale. Writes to: all.
• %x — parses the locale's standard date representation. Writes to: all.
• %Ex — parses the locale's alternative date representation, e.g. expecting 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in the ja_JP locale. Writes to: all.
• %X — parses the locale's standard time representation. Writes to: all.
• %EX — parses the locale's alternative time representation. Writes to: all.
• %D — equivalent to "%m / %d / %y ". Writes to tm_mon, tm_mday, tm_year.
• %r — parses locale's standard 12-hour clock time (in POSIX, "%I : %M : %S %p"). Writes to tm_hour, tm_min, tm_sec.
• %R — equivalent to "%H : %M". Writes to tm_hour, tm_min.
• %T — equivalent to "%H : %M : %S". Writes to tm_hour, tm_min, tm_sec.
• %p — parses the locale's equivalent of a.m. or p.m. Writes to tm_hour.

💀 note bestie: tm_isdst is not written to, and it needs to be set explicitly for use with functions such as mktime. don't forget or she'll be mad at you.

---

🎀 RETURN VALUE 🎀

so she returns an object of unspecified type such that:

• if in is an object of type std::basic_istream<CharT, Traits>, the expression in >> get_time(tmb, fmt)
  • has type std::basic_istream<CharT, Traits>&
  • has value in
  • behaves as if it called f(in, tmb, fmt)

where the function f is defined as:

template<class CharT, class Traits>
void f(std::basic_ios<CharT, Traits>& str, std::tm* tmb, const CharT* fmt)
{
    using Iter = std::istreambuf_iterator<CharT, Traits>;
    using TimeGet = time_get<CharT, Iter>;

    std::ios_base::iostate err = std::ios_base::goodbit;
    const TimeGet& tg = std::use_facet<TimeGet>(str.getloc());

    tg.get(Iter(str.rdbuf()), Iter(), str, err, tmb,
        fmt, fmt + Traits::length(fmt));

    if (err != std::ios_base::goodbit)
        str.setstate(err);
}

like, she's literally just handing you the whole implementation, no gatekeeping ❤️

---

🦋 NOTES 🦋

as specified in std::time_get::do_get, which this function calls, it's unspecified if this function zero out the fields in *tmb that are not set directly by the conversion specifiers that appear in fmt 🙈. so portable programs should initialize every field of *tmb to zero before calling std::get_time. that's not optional if you want to be portable, fr fr — zero her out first.

---

and that's the first half of the glow-up, bestie — part 2 is right behind me 🫶✨

💖 Example 💖

okay bestie, here's the vibe check on this one — and yes, there's a compiler note you need before you run it:

Note: choose clang or gcc >= 12.1 to observe the output. libstdc++ before 12.1 does not correctly implement the %b specifier: bug #78714.

So like… don't come for me if you're on an ancient libstdc++ and %b is acting up 😭 that's literally bug #78714, not you.

Here's the code, no cap:

// Run this code

#include <iomanip>
#include <iostream>
#include <locale>
#include <sstream>

int main()
{
    std::tm t = {};
    std::istringstream ss("2011-Februar-18 23:12:34");
    ss.imbue(std::locale("de_DE.utf-8"));
    ss >> std::get_time(&t, "%Y-%b-%d %H:%M:%S");

    if (ss.fail())
        std::cout << "Parse failed\n";
    else
        std::cout << std::put_time(&t, "%c") << '\n';
}

Possible output:

Sun Feb 18 23:12:34 2011

she ate that fr fr 💅✨

---

🔎 See also 🔎

• time_get — parses time/date values from an input character sequence into std::tm — (class template) 🕰️
• put_time — formats and outputs a date/time value according to the specified format — (C++11) (function template) 🎀
• parse — parses a chrono object from a stream — (C++20) (function template) 🌸

---

that's the whole page, bestie 🫶 go forth and parse those timestamps with main character energy 👑

source/version: http://cppreference.com · date: 2024.06.10 · page: std::get_time(3) 💖✨