std::wcsftime(3)

✨ std::wcsftime ✨

ok so this is std::wcsftime, and it lives in the C++ Standard Library — we love a legend with a home fr fr 💖. Come on bestie, let's format some wide-character dates together 💅

---

🎀 NAME 🎀

std::wcsftime — that's it, that's the name, no notes, periodt 👑

---

🌸 Synopsis 🌸

Defined in header <cwchar>

std::size_t wcsftime( wchar_t* str, std::size_t count, const wchar_t* format,
                      const std::tm* time );

So what does it do? It takes the date and time info from a given calendar time time and converts it into a null-terminated wide character string str, following the format string format. Up to count wide characters get written. That's the whole vibe 🦋

---

💜 Parameters 💜

• str — pointer to the first element of the wchar_t array where the output goes. The stage, the venue, the main character ✨
• count — the maximum number of wide characters to write. It's a limit, not a suggestion, bestie 🙈
• format — pointer to a null-terminated wide character string that says how the conversion should be formatted
• time — pointer to the date and time information that's getting converted

🌈 Format string 🌈

ok so the format string is made of zero or more conversion specifiers and ordinary characters (ordinary characters being everything except %). All the ordinary characters, including the terminating null character, get copied to the output string without modification — no edits, no glow-up, just straight through 💯

Every conversion specification starts with a % character, then optionally an E or O modifier (ignored if the locale doesn't support it, no hard feelings), then the character that decides what the specifier actually does.

Here's the full roster of format specifiers, bestie — every single one 👇

🧚 The little ones 🧚

• % — writes a literal %. Careful though: the full conversion specification must be %% 💀
• n — writes the newline character (C++11)
• t — writes the horizontal tab character (C++11)

👑 Year 👑

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

🌸 Month 🌸

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

🦋 Week 🦋

• U — writes the 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 — writes the week of the year, as by %U, using the alternative numeric system, e.g. 五十二 instead of 52 in the ja_JP locale (C++11) — used fields: tm_year, tm_wday, tm_yday
• W — writes the 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 — writes the week of the year, as by %W, using the alternative numeric system, e.g. 五十二 instead of 52 in the ja_JP locale (C++11) — used fields: tm_year, tm_wday, tm_yday
• V — writes the ISO 8601 week of the year (range [01,53]) (C++11) — used fields: tm_year, tm_wday, tm_yday
  • 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
• OV — writes the week of the year, as by %V, using the alternative numeric system, e.g. 五十二 instead of 52 in the ja_JP locale (C++11) — used fields: tm_year, tm_wday, tm_yday

🍓 Day of the year / month 🍓

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

💅 Day of the week 💅

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

⭐ Hour, minute, second ⭐

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

🔥 Other 🔥

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

---

🫶 Return value 🫶

On success you get the number of wide characters written into the wide character array pointed to by str, not counting the terminating L'\0' — that one's on the house, bestie 💖

⚠️ But listen: if count was reached before the entire string could be stored, 0 is returned and the contents are undefined. Not "partially there", not "close enough" — literally undefined. So size your buffer like you mean it 😭

---

💀 Example 💀

// Run this code

#include <ctime>
#include <cwchar>
#include <iostream>
#include <locale>

int main()
{
    std::locale::global(std::locale("ja_JP.utf8"));
    std::time_t t = std::time(nullptr);
    wchar_t wstr[100];
    if (std::wcsftime(wstr, 100, L"%A %c", std::localtime(&t)))
        std::wcout << wstr << '\n';
}

Possible output:

火曜日 2011年12月27日 17時43分13秒

no cap that output is genuinely iconic 🎀

👀 See also 👀

• strftime — bestie, this is the O.G. version: it converts a std::tm object into a custom textual representation. (It's a function, no template nonsense.) ✨
• put_time — formats and outputs a date/time value according to the specified format. It's giving "the fancy C++11 way," and yes it's a function template. 🎀 (C++11)
• C documentation for wcsftime — like, the whole original C vibe if you wanna go full retro. 🌈

---

okay so that's literally the whole list 💅 go forth and format your little hearts out, bestie 🫶

And that's a wrap, fr fr! This iconic little page came from http://cppreference.com, dated 2024.06.10, and it's the std::wcsftime(3) page — she ate and left no crumbs 👑💖

mwah — catch you in the next manpage, bestie! 🌸🦋⭐