std::chrono...:month_day)(3)

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

🎀 std::chrono::from_stream(std::chrono::month_day) — C++ Standard Library, section 3

okay bestie, we are in part 1 of 3 of this absolute unit of a manual page. buckle up, because this one is all about parsing a month_day out of a stream and it is lowkey iconic. more parts are coming, so do not close the tab. 💅

🌸 NAME

std::chrono::from_stream(std::chrono::month_day) — and the description is literally std::chrono::from_stream(std::chrono::month_day) again. yes, the same string twice. the duplication is giving copy-paste main character energy, and honestly? we respect it. 💖

✨ Synopsis

Defined in header <chrono> — write that down, bestie.

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,
                 std::chrono::month_day& md,
                 std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr,
                 std::chrono::minutes* offset = nullptr );

This overload is here since C++20. ✨

So what does it actually do? It attempts to parse the input stream is into the std::chrono::month_day md according to the format string fmt. that is the whole quest. no cap. 🦋

Vibe check: it behaves as an UnformattedInputFunction, except that it has an unspecified effect on is.gcount(). so do not count on gcount() being predictable here. it is giving “we don’t promise anything about that counter” and we are simply going to accept it. 😭

After constructing and checking the sentry object, it attempts to parse the input stream is into md according to the format string fmt. yes, sentry object first. it is doing its little checks before the parse era begins. 🫶

bestie warning: if the parse fails to decode a valid month_day, then is.setstate(std::ios_base::failbit) is called, and md is not modified. so no half-parsed chaos, no accidental glow-up on your md. it stays exactly as it was. periodt. 💅

Now for the format-specifier lore: if the format specifier %Z is used and successfully parsed, the parsed value is assigned to *abbrev if abbrev is not null. and if the format specifier %z or a modified variant is used and successfully parsed, the parsed value is assigned to *offset if offset is not null. both of those pointers default to nullptr in the synopsis, so you only get the assignment when you actually passed somewhere to put it. iykyk. 🌈

okay that is the synopsis and the core behavior of part 1. part 2 is literally next, bestie — keep scrolling, do not sign off. 🎀

💅 Parameters 💅

okay so here's what you're actually handing this thing, bestie:

  • is — an input stream 🫶
  • fmt — a format string (see below 👇 literally the whole personality of this function)
  • md — object to hold the parse result
  • abbrev — if not null, pointer to an object that will hold the time zone abbreviation or name corresponding to the %Z specifier
  • offset — if not null, pointer to an object that will hold the offset from UTC corresponding to the %z specifier

🎀 Format string 🎀

The format string is made of zero or more conversion specifiers plus ordinary characters. that's it, that's the recipe 🍓

Each ordinary character, excluding whitespace characters and the terminating null character, matches one identical character from the input stream — or causes the function to fail if the next character on the stream does not compare equal. no vibes-based matching here, it's gotta be a literal match fr fr.

Each whitespace character matches zero or more whitespace characters in the input stream. slay, flexible.

Each unmodified conversion specifier begins with a % character followed by a character that determines the behavior of the specifier. Some conversion specifiers have a modified form in which an E or O modifier character is inserted after the % character. Some conversion specifiers have a modified form in which a width parameter given as a positive decimal integer (shown as N below) is inserted after the % character. 💅

Each conversion specifier causes the matched characters to be interpreted as parts of date and time types according to the table below.

🚨 heads up: a character sequence in the format string that begins with a % but does not match one of the conversion specifiers below is interpreted as ordinary characters. no error, no drama, it just becomes plain text.
😭 also important: 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, is.setstate(std::ios_base::failbit) is called. so like… it will let you know.

The following conversion specifiers are available:

  • %% — 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 is not otherwise specified (e.g. 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. (yes, case-insensitive, we're not out here case-shaming anyone ✨)
  • %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 — also part of the Day lineup, and quick note: 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 🧚

ok so 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

the way that's so specific and yet so iconic. periodt.

  • %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. (read that again bestie, the width does not touch the other pieces 👀)
  • %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.

🦋 Miscellaneous 🦋

okay so these are the leftover format specifiers, and they’re honestly kind of iconic once you clock the pattern 💅

  • %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 💖

is

okay so real talk: that’s literally all it says 😭 the page got cut off mid-thought and I’m not gonna invent lore for you, bestie. No cap, that’s the whole section as it survived.

🌈 See also 🌈

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

source: cppreference.com · version/date: 2024.06.10 · page: std::chrono...:month_day)(3) 🫶✨

📦 where this page comes from