std::chrono...:year_month)(3)

📦 version 2024.07.05, in nixpkgs unstable, opensuse-leap 16.0

✨ `std::chrono::from_stream` (`std::chrono::year_month`) ✨

okay bestie, buckle up 💅 this one lives in the C++ Standard Library manual, and it's literally the std::chrono::from_stream(std::chrono::year_month) page — yes that title is a mouthful, no we are not renaming it, iykyk. it's giving "glow-up for your date parsing" and honestly? obsessed 🎀

🌸 NAME 🌸

std::chrono::from_stream(std::chrono::year_month) — the one that pulls a year-and-month out of a stream, fr fr 💖

⭐ Synopsis ⭐

first things first, she's defined in header <chrono>, and she's been here since C++20 👑

template< class CharT, class Traits, class Alloc =
std::allocator<CharT> >

std::basic_istream<CharT, Traits>&
    from_stream( std::basic_istream<CharT, Traits>& is, const CharT* fmt,
(since C++20)
                 std::chrono::year_month& ym,
                 std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr,

                 std::chrono::minutes* offset = nullptr );

like, look at that signature. four-and-a-bit template params, a format string, a year_month reference, and two optional pointers that are basically "hey, want the extras?" 🙈

💜 the vibe check (what it actually does) 💜

so. what does she do? she attempts to parse the input stream is into the std::chrono::year_month ym, according to the format string fmt. that's the whole assignment, and she executes it flawlessly 💅

she behaves as an UnformattedInputFunction, with one lil exception: she has an unspecified effect on is.gcount() — so don't go counting on that count, bestie, it's a mystery on purpose 🕵️‍♀️

the actual sequence is iconic:

construct and check the sentry object (standard istream ritual, no notes) 🧚
attempt to parse the input stream is into ym according to the format string fmt

and here's the part where you gotta pay attention, because it's the drama:

if the parse fails to decode a valid year_month, then is.setstate(std::ios_base::failbit) gets called — and ym is not modified. no half-parsed monstrosity, no corrupted value, she just ✨ refuses ✨ and leaves your variable exactly as she found it 🫶

🦋 the format specifier tea ☕

two special little guys get extra treatment:

%Z — if this specifier is used and successfully parsed, the parsed value gets assigned to *abbrev, but only if abbrev is not null. null pointer? she simply does not bother 💀
%z (or a modified variant of it) — if it's used and successfully parsed, the parsed value gets assigned to *offset, again only if offset is not null 🌈

that's it, that's the whole extras system. optional pointers, optional data, zero pressure 😌

part 2 is coming, don't go anywhere 👀

✨ Parameters ✨

okay so here's what you're feeding this thing, bestie — five little slots, and they all matter:

is — an input stream 💖
fmt — a format string (see below, and yes, "below" means right down there 👇)
ym — the object that holds the parse result
abbrev — if it's not null, it's a pointer to an object that will hold the time zone abbreviation or name corresponding to the %Z specifier
offset — if it's not null, it's a pointer to an object that will hold the offset from UTC corresponding to the %z specifier

🌸 Format string 🌸

Your format string is made of zero or more conversion specifiers plus ordinary characters. That's the whole vibe.

Every ordinary character — meaning anything that isn't a whitespace character and isn't the terminating null character — has to match one identical character from the input stream. If the next character on the stream doesn't compare equal, the function just fails. No cap, that's the rule. 😭

Every whitespace character in the format matches zero or more whitespace characters in the input stream. Generous queen behavior tbh. 🫶

Each unmodified conversion specifier begins with a % character followed by a character that decides what that specifier actually does. Some of them have a modified form where an E or O modifier character gets inserted right after the %. Some have a modified form where a width parameter — written as a positive decimal integer, shown as N down below — gets inserted after the % character. Each conversion specifier takes the characters it matched and interprets them as parts of date and time types, per the table below. 💅

And here's a lil gotcha: a character sequence in the format string that begins with a % but does not match one of the conversion specifiers below? That's interpreted as ordinary characters. Cute, iconic, slightly chaotic. 🎀

⚠️ real talk: if from_stream fails to parse everything specified by the format string, or if insufficient information is parsed to specify a complete result, or if parsing discloses contradictory information, then is.setstate(std::ios_base::failbit) gets called. All three. Any of them. Failbit. 💀

Here are the conversion specifiers you've got:

%% — matches a literal % character.
%n — matches one whitespace character.
%t — matches zero or one whitespace character.

🌟 Year 🌟

%C, %NC, %EC — parses the century as a decimal number. The width N specifies the maximum number of characters to read. The default width is 2. Leading zeroes are permitted but not required. The modified command %EC interprets the locale's alternative representation of the century.
%y, %Ny, %Ey, %Oy — parses the last two decimal digits of the year. If the century isn't otherwise specified (like, say, with %C), values in the range [69, 99] are presumed to refer to the years 1969 to 1999, and values in the range [00, 68] are presumed to refer to the years 2000 to 2068. The width N specifies the maximum number of characters to read. The default width is 2. Leading zeroes are permitted but not required. The modified commands %Ey and %Oy interpret the locale's alternative representation.
%Y, %NY, %EY — parses the year as a decimal number. The width N specifies the maximum number of characters to read. The default width is 4. Leading zeroes are permitted but not required. The modified command %EY interprets the locale's alternative representation.

🌸 Month 🌸

%b, %B, %h — parses the locale's full or abbreviated case-insensitive month name.
%m, %Nm, %Om — parses the month as a decimal number (January is 1). The width N specifies the maximum number of characters to read. The default width is 2. Leading zeroes are permitted but not required. The modified command %Om interprets the locale's alternative representation.

🦋 Day 🦋

%d, %Nd, %Od — parses the day of month as a decimal number. The width N specifies the maximum number of characters to read. The default width is 2. Leading zeroes are permitted but not required.
%e, %Ne, %Oe — grouped right here with the day crew, and for the record: the modified commands %Od and %Oe interpret the locale's alternative representation.

🎀 Day of the week 🎀

%a, %A — parses the locale's full or abbreviated case-insensitive weekday name.
%u, %Nu — parses the ISO weekday as a decimal number (1-7), where Monday is 1. The width N specifies the maximum number of characters to read. The default width is 1. Leading zeroes are permitted but not required.
%w, %Nw, %Ow — parses the weekday as a decimal number (0-6), where Sunday is 0. The width N specifies the maximum number of characters to read. The default width is 1. Leading zeroes are permitted but not required. The modified command %Ow interprets the locale's alternative representation.

🌈 ISO 8601 week-based year 🌈

quick side quest, bestie — in ISO 8601, weeks begin with Monday, and the first week of the year has to satisfy these requirements:

Includes January 4
Includes first Thursday of the year

okay back to the specifiers:

%g, %Ng — parses the last two decimal digits of the ISO 8601 week-based year. The width N specifies the maximum number of characters to read. The default width is 2. Leading zeroes are permitted but not required.
%G, %NG — parses the ISO 8601 week-based year as a decimal number. The width N specifies the maximum number of characters to read. The default width is 4. Leading zeroes are permitted but not required.
%V, %NV — parses the ISO 8601 week of the year as a decimal number. The width N specifies the maximum number of characters to read. The default width is 2. Leading zeroes are permitted but not required.

⭐ Week/day of the year ⭐

%j, %Nj — parses the day of the year as a decimal number (January 1 is 1). The width N specifies the maximum number of characters to read. The default width is 3. Leading zeroes are permitted but not required.
%U, %NU, %OU — parses the week number of the year as a decimal number. The first Sunday of the year is the first day of week 01. Days of the same year prior to that are in week 00. The width N specifies the maximum number of characters to read. The default width is 2. Leading zeroes are permitted but not required. The modified command %OU interprets the locale's alternative representation.
%W, %NW, %OW — parses the week number of the year as a decimal number. The first Monday of the year is the first day of week 01. Days of the same year prior to that are in week 00. The width N specifies the maximum number of characters to read. The default width is 2. Leading zeroes are permitted but not required. The modified command %OW interprets the locale's alternative representation.

💜 Date 💜

%D — equivalent to "%m/%d/%y".
%F, %NF — equivalent to "%Y-%m-%d". If the width is specified, it is only applied to the %Y.
%x, %Ex — parses the locale's date representation. The modified command %Ex interprets the locale's alternate date representation.

🔥 Time of day 🔥

%H, %NH, %OH — parses the hour (24-hour clock) as a decimal number. The width N specifies the maximum number of characters to read. The default width is 2. Leading zeroes are permitted but not required. The modified command %OH interprets the locale's alternative representation.
%I, %NI, %OI — parses the hour (12-hour clock) as a decimal number. The width N specifies the maximum number of characters to read. The default width is 2. Leading zeroes are permitted but not required. The modified command %OI interprets the locale's alternative representation.
%M, %NM, %OM — parses the minute as a decimal number. The width N specifies the maximum number of characters to read. The default width is 2. Leading zeroes are permitted but not required. The modified command %OM interprets the locale's alternative representation.
%S, %NS, %OS — parses the second as a decimal number. The width N specifies the maximum number of characters to read. The default width is 2. Leading zeroes are permitted but not required. The modified command %OS interprets the locale's alternative representation.
%p — parses the locale's equivalent of the AM/PM designations associated with a 12-hour clock.
%R — equivalent to "%H:%M".
%T — equivalent to "%H:%M:%S".
%r — parses the locale's 12-hour clock time.
%X, %EX — parses the locale's time representation. The modified command %EX interprets the locale's alternate time representation.
%c — parses the locale's date and time representation ✨
%Ec — the modified command %Ec interprets the locale's alternative date and time representation 🎀
%z — parses the offset from UTC, in the format [+|-]hh[mm]. For example, -0430 refers to 4 hours 30 minutes behind UTC, and 04 refers to 4 hours ahead of UTC 💅
%Ez, %Oz — the modified commands %Ez and %Oz parse the format [+|-]h[h][:mm] (i.e., requiring a : between the hours and minutes and making the leading zero for hour optional) 🦋
%Z — parses the time zone abbreviation or name, taken as the longest sequence of characters that only contains the characters A through Z, a through z, 0 through 9, -, +, _, and / ⭐

💖 RETURN VALUE 💖

Ok so bestie, the page literally just says this:

is

That's it. That's the whole return value section 😭 is. Ngl that's iconic in a feral way — go read it as "whatever the rest of the sentence says," lmao. 🙈

🌈 SEE ALSO 🌈

parse — parses a chrono object from a stream 🫶 (C++20) (function template)

fr fr read the parse page next, it's the whole vibe check for this one 👑

And that's a wrap on part 3, bestie! 💜 This lil beauty is from cppreference.com, dated 2024.06.10, and it's the man page for std::chrono...:year_month — mwah, go parse something slay ✨🌸🎀

📦 where this page comes from

nixpkgs unstable: stdman 2024.07.05
opensuse-leap 16.0: stdman 2024.07.05-bp160.1.9 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms