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

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

💖 NAME 💖

std::chrono::from_stream(std::chrono::sys_time) — literally the std::chrono::from_stream(std::chrono::sys_time) overload, bestie. That's the whole name, no cap. It lives in the C++ Standard Library, section 3 of the manual, iykyk. 🌸

✨ SYNOPSIS ✨

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

std::basic_istream<CharT, Traits>&
    from_stream( std::basic_istream<CharT, Traits>& is, const CharT* fmt,
                 std::chrono::sys_time<Duration>& tp,
                 std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr,
                 std::chrono::minutes* offset = nullptr );

(since C++20) 🦋 — yes queen, this one is a C++20 girlie, and that note applies to the whole overload up there, not just the line it's sitting next to in the raw page. 🙈

So like. What does it actually do? It attempts to parse the input stream is into the time point tp according to the format string fmt. That's the whole vibe check. 🎀

It behaves as an UnformattedInputFunction, with one very specific caveat: except that it has an unspecified effect on is.gcount(). So don't come for gcount()'s whole life expecting tea, because the standard is literally not telling you. 💀

After constructing and checking the sentry object, it attempts to parse the input stream is into tp according to the format string fmt. If the parse fails to decode a valid time point, then — and this is the important bit, bestie, write it down — is.setstate(std::ios_base::failbit) is called and tp is not modified. Like, not even a little. It stays exactly as it was. She's not getting dragged into your failed parse. 🙅‍♀️

⚠️ ok so fr fr: if the parse fails, you get failbit on the stream and your tp is left untouched. No partial slay, no half-written timestamp, just failure energy. 💅

🌈 the %Z and %z situation (iykyk)

Two format specifiers have side quests, and they're both obsessed with your pointer arguments:

  • %Z — if the format specifier %Z is used and successfully parsed, the parsed value is assigned to *abbrev if abbrev is not null. (Default is nullptr, so if you didn't pass one, nothing happens. She's chill like that. 🫶)
  • %z (or a modified variant of it) — 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, and the parsed offset will be subtracted from the parsed timestamp before the difference is assigned to tp. 🧚

Read that last part again because it's giving main character energy: the offset doesn't just get handed to you, it gets subtracted from the parsed timestamp first, and then the resulting difference is what lands in tp. ✨ Math girlie behavior, honestly iconic. 👑

🌟 both abbrev and offset are the classic "only touch it if it's not null" pattern, so passing nullptr (which is the default for both) means the parse still works fine, you just don't get the extra little gift basket. 🎁

ok that's part one of this page done!! more to come, don't go anywhere, the rest of this overload's lore is literally right there. 💜

💜 Parameters 🫶

Okay so here's who's showing up to the function, bestie — know your cast:

  • is — an input stream. The source of truth, the feed, the whole vibe. 💧
  • fmt — a format string (see below — and yes, "below" is a whole journey). 🗺️
  • tp — the time point object that's gonna hold the parse result. It's the container, the little guy getting filled up. ✨
  • 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, pointer to an object that will hold the offset from UTC corresponding to the %z specifier. 🌍

🌸 Format string 🌸

So the format string is literally made of zero or more conversion specifiers plus ordinary characters, and here's how each one behaves, no cap:

Each ordinary character — meaning not whitespace, and not the terminating null character — matches one identical character from the input stream. And if the next character on the stream doesn't compare equal? Boom, the function fails. 😭 Match or miss, babe.

Each whitespace character matches zero or more whitespace characters in the input stream. Flexible queen behavior. 💅

Each unmodified conversion specifier starts with a % character followed by a character that decides how it behaves. Some specifiers 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 — given as a positive decimal integer, shown as N below — goes in after the % character. Every conversion specifier makes those matched characters get interpreted as parts of date and time types, per the table below. 👑

And a heads-up: a character sequence in the format string that starts with a % but doesn't actually match one of the conversion specifiers below? It gets interpreted as ordinary characters. It's just gonna sit there being text. 🙈

⚠️ Warning time, bestie: if from_stream fails to parse everything specified by the format string, or if there's insufficient information parsed to specify a complete result, or if parsing discloses contradictory information — then is.setstate(std::ios_base::failbit) is called. That's the fail bit. It's over. 💀

The following conversion specifiers are available:

⭐ The little basics

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

🔥 Year

  • %C, %NC — 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.
  • %EC — 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 (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 — 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 modified commands %Od and %Oe interpret the locale's alternative representation. (Yeah, %Od rides along in this group — that's just how the page tells it. 🙈)

🎀 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

First, the rules, because ISO 8601 has opinions. 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

Now 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 if Duration is convertible to std::chrono::seconds, otherwise it is determined by the decimal precision of Duration and the field is interpreted as a long double in a fixed format, with the decimal point character determined by the locale (if encountered). 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 bestie, here’s the rest of the format-specifier tea ☕ — every one of these is having its own little parse moment, no cap.

  • %c — parses the locale’s date and time representation. 💅
  • %Ec — the modified command %Ec interprets the locale’s alternative date and time representation. slay, but make it localized ✨
  • %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 parses the format [+|-]h[h][:mm] (i.e., requiring a : between the hours and minutes and making the leading zero for hour optional). yes, the original says “parses,” we’re keeping that energy fr fr 🫶
  • %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 /. iconic character set, honestly 🎀

🌟 Return value 🌟

The page says: is

That’s it. That’s the whole return value section. not me staring at it like 👁️👄👁️ — but we keep the facts exactly as they are.

📝 Example 📝

This section is incomplete.

Reason: no example

(cries in no snippet 😭 but we move.)

👀 See also 👀

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

🏷️ Category 🏷️

  • * Todo no example

xoxo, bestie 💖 — this page came from http://cppreference.com, and the version/date situation is 2024.06.10. stay parsed, stay slay 🦋✨

📦 where this page comes from