std::chrono...o::weekday)(3)

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

🎀 NAME 🎀

okay so bestie, welcome to the C++ Standard Libary manual page for std::chrono::from_stream(std::chrono::weekday) — yes, section 3, and yes, the manual name is folded in right here instead of being pasted as that header line. 💖

The NAME section is literally:

  • std::chrono::from_stream(std::chrono::weekday) — full line: std::chrono::from_stream(std::chrono::weekday) - std::chrono::from_stream(std::chrono::weekday). It said it twice because it's iconic like that. 👑

✨ Synopsis ✨

Defined in header <chrono> 🦋

This template signature is the main character, so here it is exactly, no edits:

          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::weekday& wd,
                           std::basic_string<CharT, Traits, Alloc>* abbrev =
          nullptr,

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

The manual's exact mission statement: “Attempts to parse the input stream is into the std::chrono::weekday wd according to the format string fmt.” That's the whole vibe, periodt. 💅

It behaves as an UnformattedInputFunction, except that it has an unspecified effect on is.gcount(). Yes, unspecified — the manual really said that, so don't act surprised. 🙈

After constructing and checking the sentry object, it attempts to parse the input stream is into wd according to the format string fmt. If the parse fails to decode a valid weekday, then is.setstate(std::ios_base::failbit) is called and wd is not modified. That's the fail-safe vibe: no valid weekday, no changes to wd. 😭

🫶 little format-specifier note: if the format specifier %Z is used and successfully parsed, the parsed value is assigned to *abbrev if abbrev is not null. 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.

💖 Parameters

  • is — the input stream we’re reading from, bestie.
  • fmt — the format string (all the deets are below ✨).
  • wd — the object that’s gonna hold 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 that goes with the %Z specifier.
  • offset — if it’s not null, it’s a pointer to an object that will hold the offset from UTC that goes with the %z specifier.

🌈 Format string 🌈

Okay so the format string is literally zero or more conversion specifiers plus ordinary characters. Every ordinary character — not counting whitespace characters and the terminating null character — has to match one identical character from the input stream, or the function fails if the next character on the stream doesn’t compare equal. No cap.

Each whitespace character matches zero or more whitespace characters in the input stream. Slay.

Each unmodified conversion specifier starts with a % character followed by a character that decides what the specifier does. Some conversion specifiers have a modified form where an E or O modifier character gets inserted after the % character. Some conversion specifiers have a modified form where a width parameter given as a positive decimal integer (shown as N below) gets inserted after the % character. Each conversion specifier makes the matched characters get interpreted as parts of date and time types according to the deets below. Periodt.

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. That’s the rule, iykyk.

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) is called. Big yikes, but that’s the behavior.

🎀 Conversion specifiers 🎀

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.
  • %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 — the note here is that 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 🦋

  • In ISO 8601, weeks begin with Monday and the first week of the year must satisfy these requirements:
    • Includes January 4
    • Includes first Thursday of the year
  • %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 %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.

✨ Miscellaneous ✨

These are the remaining format specifiers, bestie — and yes, they’re giving “niche but essential” energy 💅

  • %c — parses the locale’s date and time representation. iconic little all-in-one moment 🌸
  • %Ec — the modified command %Ec interprets the locale’s alternative date and time representation. it’s the “but make it ✨alternative✨” version 💖
  • %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. timezone math, but make it fashion 🕶️
  • %Ez, %Oz — the modified commands %Ez and %Oz parses the format [+|-]h[h][:mm] (i.e., requiring a : between the hours and minutes and making the leading zero for hour optional). so extra about the colon, lowkey 🎀
  • %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 /. it’s picky about its letters and symbols, and honestly? same 💅

💖 Return value 💖

The page gives us exactly this:

is

That’s it. That’s the whole return value, bestie — just is. no cap, I’m not gonna invent extra lore 😭

🦋 See also 🦋

  • parse — parses a chrono object from a stream (C++20) (function template). go look at that one too, iykyk 👑

mwah 💋 that’s the whole page, bestie. source: cppreference.com, dated 2024.06.10 — now go parse something cute 🎀

📦 where this page comes from