std::put_time(3)

💖 NAME 💖

Okay bestie, the manual name is std::put_time, and the NAME line is literally std::put_time - std::put_time — no notes, just vibes. This is the C++ Standard Libary page (yes, the header spells it "Libary", and I'm not fixing it 💀).

This is part 1, so buckle up.

---

✨ Synopsis ✨

Defined in header <iomanip>, and it's a template on CharT. Since C++11, babes.

template< class CharT >
/*unspecified*/ put_time( const std::tm* tmb, const CharT* fmt );

When used in an expression out << put_time(tmb, fmt), it converts the date and time information from a given calendar time tmb to a character string according to format string fmt, as if by calling std::strftime, std::wcsftime, or analog (depending on CharT), according to the std::time_put facet of the locale currently imbued in the output stream out.

---

🎀 Parameters 🎀

• tmb — pointer to the calendar time structure as obtained from std::localtime or std::gmtime
• fmt — pointer to a null-terminated CharT string specifying the format of conversion

🦋 Format string 🦋

The format string consists of zero or more conversion specifiers and ordinary characters (except %). All ordinary characters, including the terminating null character, are copied to the output string without modification. Each conversion specification begins with % character, optionally followed by E or O modifier (ignored if unsupported by the locale), followed by the character that determines the behavior of the specifier. The following format specifiers are available:

🌸 Year 🌸

• Y — writes year as a decimal number, e.g. 2017. Used fields: tm_year.
• EY (C++11) — writes year in the alternative representation, e.g. 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale. Used fields: tm_year.
• y — writes last 2 digits of year as a decimal number (range [00,99]). Used fields: tm_year.
• Oy (C++11) — writes last 2 digits of year using the alternative numeric system, e.g. 十一 instead of 11 in ja_JP locale. Used fields: tm_year.
• Ey (C++11) — writes year as offset from locale's alternative calendar period %EC (locale-dependent). Used fields: tm_year.
• C (C++11) — writes first 2 digits of year as a decimal number (range [00,99]). Used fields: tm_year.
• EC (C++11) — writes name of the base year (period) in the locale's alternative representation, e.g. 平成 (Heisei era) in ja_JP. Used fields: tm_year.
• G (C++11) — writes ISO 8601 week-based year, i.e. the year that contains the specified week.

In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the following requirements:

• Includes January 4
• Includes first Thursday of the year

Used fields: tm_year, tm_wday, tm_yday.

• g (C++11) — writes last 2 digits of ISO 8601 week-based year, i.e. the year that contains the specified week (range [00,99]).

In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the following requirements:

• Includes January 4
• Includes first Thursday of the year

Used fields: tm_year, tm_wday, tm_yday.

🍓 Month 🍓

• b — writes abbreviated month name, e.g. Oct (locale dependent). Used fields: tm_mon.
• h (C++11) — synonym of b. Used fields: tm_mon.
• B — writes full month name, e.g. October (locale dependent). Used fields: tm_mon.
• m — writes month as a decimal number (range [01,12]). Used fields: tm_mon.
• Om (C++11) — writes month using the alternative numeric system, e.g. 十二 instead of 12 in ja_JP locale. Used fields: tm_mon.

🧚 Week 🧚

• U — writes week of the year as a decimal number (Sunday is the first day of the week) (range [00,53]). Used fields: tm_year, tm_wday, tm_yday.
• OU (C++11) — writes week of the year, as by %U, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale. Used fields: tm_year, tm_wday, tm_yday.
• W — writes week of the year as a decimal number (Monday is the first day of the week) (range [00,53]). Used fields: tm_year, tm_wday, tm_yday.
• OW (C++11) — writes week of the year, as by %W, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale. Used fields: tm_year, tm_wday, tm_yday.
• V (C++11) — writes ISO 8601 week of the year (range [01,53]).

In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the following requirements:

• Includes January 4
• Includes first Thursday of the year

Used fields: tm_year, tm_wday, tm_yday.

• OV (C++11) — writes week of the year, as by %V, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale. Used fields: tm_year, tm_wday, tm_yday.

💅 Day of the year/month 💅

• j — writes day of the year as a decimal number (range [001,366]). Used fields: tm_yday.
• d — writes day of the month as a decimal number (range [01,31]). Used fields: tm_mday.
• Od (C++11) — writes zero-based day of the month using the alternative numeric system, e.g. 二十七 instead of 27 in ja_JP locale. Single character is preceded by a space. Used fields: tm_mday.
• e (C++11) — writes day of the month as a decimal number (range [1,31]). Single digit is preceded by a space. Used fields: tm_mday.
• Oe (C++11) — writes one-based day of the month using the alternative numeric system, e.g. 二十七 instead of 27 in ja_JP locale. Single character is preceded by a space. Used fields: tm_mday.

🌈 Day of the week 🌈

• a — writes abbreviated weekday name, e.g. Fri (locale dependent). Used fields: tm_wday.
• A — writes full weekday name, e.g. Friday (locale dependent). Used fields: tm_wday.
• w — writes weekday as a decimal number, where Sunday is 0 (range [0-6]). Used fields: tm_wday.
• Ow (C++11) — writes weekday, where Sunday is 0, using the alternative numeric system, e.g. 二 instead of 2 in ja_JP locale. Used fields: tm_wday.
• u (C++11) — writes weekday as a decimal number, where Monday is 1 (ISO 8601 format) (range [1-7]). Used fields: tm_wday.
• Ou (C++11) — writes weekday, where Monday is 1, using the alternative numeric system, e.g. 二 instead of 2 in ja_JP locale. Used fields: tm_wday.

⭐ Hour, minute, second ⭐

• H — writes hour as a decimal number, 24 hour clock (range [00-23]). Used fields: tm_hour.
• OH (C++11) — writes hour from 24-hour clock using the alternative numeric system, e.g. 十八 instead of 18 in ja_JP locale. Used fields: tm_hour.
• I — writes hour as a decimal number, 12 hour clock (range [01,12]). Used fields: tm_hour.
• OI (C++11) — writes hour from 12-hour clock using the alternative numeric system, e.g. 六 instead of 06 in ja_JP locale. Used fields: tm_hour.
• M — writes minute as a decimal number (range [00,59]). Used fields: tm_min.
• OM (C++11) — writes minute using the alternative numeric system, e.g. 二十五 instead of 25 in ja_JP locale. Used fields: tm_min.
• S — writes second as a decimal number (range [00,60]). Used fields: tm_sec.
• OS (C++11) — writes second using the alternative numeric system, e.g. 二十四 instead of 24 in ja_JP locale. Used fields: tm_sec.

👑 Other 👑

• c — writes standard date and time string, e.g. Sun Oct 17 04:41:13 2010 (locale dependent). Used fields: all.
• Ec (C++11) — writes alternative date and time string, e.g. using 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale. Used fields: all.
• x — writes localized date representation (locale dependent). Used fields: all.
• Ex (C++11) — writes alternative date representation, e.g. using 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale. Used fields: all.
• X — writes localized time representation, e.g. 18:40:20 or 6:40:20 PM (locale dependent). Used fields: all.
• EX (C++11) — writes alternative time representation (locale dependent). Used fields: all.
• D (C++11) — equivalent to "%m/%d/%y". Used fields: tm_mon, tm_mday, tm_year.
• F (C++11) — equivalent to "%Y-%m-%d" (the ISO 8601 date format). Used fields: tm_mon, tm_mday, tm_year.
• r (C++11) — writes localized 12-hour clock time (locale dependent). Used fields: tm_hour, tm_min, tm_sec.
• R (C++11) — equivalent to "%H:%M". Used fields: tm_hour, tm_min.
• T (C++11) — equivalent to "%H:%M:%S" (the ISO 8601 time format). Used fields: tm_hour, tm_min, tm_sec.
• p — writes localized a.m. or p.m. (locale dependent). Used fields: tm_hour.
• z (C++11) — writes offset from UTC in the ISO 8601 format (e.g. -0430), or no characters if the time zone information is not available. Used fields: tm_isdst.
• Z — writes locale-dependent time zone name or abbreviation, or no characters if the time zone information is not available. Used fields: tm_isdst.

---

💜 Return value 💜

An object of unspecified type such that:

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

where the function f is defined as:

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

    const TimePut& tp = std::use_facet<TimePut>(str.getloc());
    const Iter end = tp.put(Iter(str.rdbuf()), str, str.fill(), tmb,
        fmt, fmt + Traits::length(fmt));

    if (end.failed())
        str.setstate(std::ios_base::badbit);
}

🌸 EXAMPLE 🌸

ok bestie this is the moment, the main character demo, the whole reason you're here 💖 literally just run this code:

// Run this code

#include <ctime>
#include <iomanip>
#include <iostream>

int main()
{
    std::time_t t = std::time(nullptr);
    std::tm tm = *std::localtime(&t);

    std::cout.imbue(std::locale("ru_RU.utf8"));
    std::cout << "ru_RU: " << std::put_time(&tm, "%c %Z") << '\n';

    std::cout.imbue(std::locale("ja_JP.utf8"));
    std::cout << "ja_JP: " << std::put_time(&tm, "%c %Z") << '\n';
}

so what's happening here 🔍 you grab the current time with std::time(nullptr), turn it into a std::tm via *std::localtime(&t), then you hit std::cout.imbue(...) to swap the locale — first ru_RU.utf8, then ja_JP.utf8 — and print the same std::put_time(&tm, "%c %Z") both times. same std::tm, same format string, two different locales, two different vibes. that's the whole flex of this function tbh ✨

✨ Possible output ✨

and it may spit out something like this 🎀 (note: possible, not guaranteed, locales be like that):

ru_RU: Ср. 28 дек. 2011 10:21:16 EST
ja_JP: 2011年12月28日 10時21分16秒 EST

look at that 📅 same instant in time, and %c gives you the full locale-flavoured date-time while %Z tacks on the time zone name. iconic behaviour, no cap 🫶

---

👀 SEE ALSO 👀

your little friends in the neighbourhood, go say hi:

• time_put — formats contents of std::tm for output as character sequence (class template) 💅
• get_time — parses a date/time value of specified format (C++11) (function template) 🔄
• strftime — converts a std::tm object to custom textual representation (function) 📝
• wcsftime — converts a std::tm object to custom wide string textual representation (function) 🌈

---

ok that's the whole page, you made it to the end, I'm so proud of you fr fr 😭💜 this lil beauty comes to you courtesy of cppreference.com, version dated 2024.06.10 — go drink some water and then go format some timestamps, you absolute icon 👑✨🍓