std::chrono::parse(3)

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

💅 std::chrono::parse — C++ Standard Library

okay bestie, sit down, because we're about to get into std::chrono::parse, and it is so much. this is the C++ Standard Library manual page for it, and yes it's long, which is why it comes in three parts. this is part one. hydrate. 🍓

✨ NAME ✨

std::chrono::parse — literally std::chrono::parse. iconic, self-titled, no notes. 👑

✨ Synopsis ✨

so first things first: this whole situation lives in the header <chrono>. get familiar. 🎀

there are eight overloads, and every single one of them is (since C++20). yes, all of them. we love a consistent queen.

Overload (1) — (since C++20)

template< class CharT, class Parsable >
/* unspecified */ parse( const CharT* fmt, Parsable& tp );

Overload (2) — (since C++20)

template< class CharT, class Traits, class Alloc, class Parsable >
/* unspecified */ parse( const std::basic_string<CharT, Traits, Alloc>& fmt,
                         Parsable& tp );

Overload (3) — (since C++20)

template< class CharT, class Traits, class Alloc, class Parsable >
/* unspecified */ parse( const CharT* fmt, Parsable& tp,
                         std::basic_string<CharT, Traits, Alloc>& abbrev );

Overload (4) — (since C++20)

template< class CharT, class Traits, class Alloc, class Parsable >
/* unspecified */ parse( const std::basic_string<CharT, Traits, Alloc>& fmt,
                         Parsable& tp,
                         std::basic_string<CharT, Traits, Alloc>& abbrev );

Overload (5) — (since C++20)

template< class CharT, class Parsable >
/* unspecified */ parse( const CharT* fmt, Parsable& tp,
                         std::chrono::minutes& offset );

Overload (6) — (since C++20)

template< class CharT, class Traits, class Alloc, class Parsable >
/* unspecified */ parse( const std::basic_string<CharT, Traits, Alloc>& fmt,
                         Parsable& tp, std::chrono::minutes& offset );

Overload (7) — (since C++20)

template< class CharT, class Traits, class Alloc, class Parsable >
/* unspecified */ parse( const CharT* fmt, Parsable& tp,
                         std::basic_string<CharT, Traits, Alloc>& abbrev,
                         std::chrono::minutes& offset );

Overload (8) — (since C++20)

template< class CharT, class Traits, class Alloc, class Parsable >
/* unspecified */ parse( const std::basic_string<CharT, Traits, Alloc>& fmt,
                         Parsable& tp,
                         std::basic_string<CharT, Traits, Alloc>& abbrev,
                         std::chrono::minutes& offset );

🦋 what it actually returns (the plot twist)

so every one of these bad boys returns an object manip of unspecified type. unspecified type means we're not telling you the type, don't @ us. 🙈

the deal is: given a std::basic_istream<CharT, Traits> object named is, the expression is >> manip calls from_stream — and it calls it unqualified, specifically so that argument-dependent lookup is enabled. iykyk. ✨

here's exactly how each overload maps out:

from_stream(is, fmt, tp)
from_stream(is, fmt.c_str(), tp)
from_stream(is, fmt, tp, std::addressof(abbrev))
from_stream(is, fmt.c_str(), tp, std::addressof(abbrev))
from_stream(is, fmt, tp, static_cast<std::basic_string<CharT, Traits, Alloc>*>(nullptr), &offset)
from_stream(is, fmt.c_str(), tp, static_cast<std::basic_string<CharT, Traits, Alloc>*>(nullptr), &offset)
from_stream(is, fmt, tp, std::addressof(abbrev), &offset)
from_stream(is, fmt.c_str(), tp, std::addressof(abbrev), &offset)

periodt. that's the whole mapping. 💅

🫶 the lil details that matter

the expression is >> manip is an lvalue of type std::basic_istream<CharT, Traits> whose value is is. say it with me: value is is. very "the way that it just returns the stream" of it all. 😭

these overloads only participate in overload resolution if the corresponding from_stream expression is well-formed. so if it don't compile, it don't exist. vibe check passed or it's not even in the building. 🚫

ok and here's the serious one, bestie, don't skip it: implementations are recommended to make it difficult to use potentially dangling references to the format string — for example, by making the return types non-movable and preventing operator>> from accepting lvalues of the return types. that's a recommendation to implementers, not you, but it's there for a reason and it's giving "we're protecting you from yourself" and honestly? valid. 🧚

part 1 of 3, keep scrolling for the rest 💖

🫶 PARAMETERS 🫶

fmt — a format string (see below)
tp — object to hold the parse result
abbrev — string to hold the time zone abbreviation or name corresponding to the %Z specifier
offset — duration to represent the offset from UTC corresponding to the %z specifier

✨ Format string ✨

Okay so bestie, the format string is literally made of zero or more conversion specifiers and ordinary characters. 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 cap.

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

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. 💅

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. (So like, don't stress if you see a stray % — it's just a regular character then. 🫶)

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. Big yikes, but that's the rule. 😭

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 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 the following 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 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.

🌈 Miscellaneous 🌈

%c — parses the locale's date and time representation. Classic, no notes 💅
%Ec — the modified command here; it interprets the locale's alternative date and time representation. Lowkey the cooler twin 🦋
%z — parses the offset from UTC, and the format is [+|-]hh[mm]. So like, -0430 means 4 hours 30 minutes behind UTC, and 04 means 4 hours ahead of UTC. Easy ✨
%Ez, %Oz — the modified commands, and they parse the format [+|-]h[h][:mm]. Translation: the : between hours and minutes is required, and the leading zero on the hour is optional. She's flexible but she does have standards 😌
%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 /. That's the whole guest list, nobody else gets in 🎀

🌸 EXAMPLE 🌸

This section is incomplete Reason: no example

Not me giving you a section that's literally just a "no example yet" placeholder 😭 the vibes are immaculate but the code sample is missing. Tragic. If you need a working example bestie, that's a you-and-the-compiler moment fr fr 💀

💀 DEFECT REPORTS 💀

The following behavior-changing defect reports were applied retroactively to previously published C++ standards. So yes, the past got edited. Main character energy 👑

LWG 3554 — applied to C++20. What was published: overloads for plain null-terminated character type sequences were missing. Correct behavior now: added. She said "actually no" and they fixed it 🫶

🫶 SEE ALSO 🫶

Okay so there are a lot of sibling functions here, all of them from_stream overloads living their best lives, plus one old-school friend. Every one of these is a function template — noted for each, no cap ✨

from_stream(std::chrono::sys_time) (C++20) — parses a sys_time from a stream according to the provided format
from_stream(std::chrono::utc_time) (C++20) — parses a utc_time from a stream according to the provided format
from_stream(std::chrono::tai_time) (C++20) — parses a tai_time from a stream according to the provided format
from_stream(std::chrono::gps_time) (C++20) — parses a gps_time from a stream according to the provided format
from_stream(std::chrono::file_time) (C++20) — parses a file_time from a stream according to the provided format
from_stream(std::chrono::local_time) (C++20) — parses a local_time from a stream according to the provided format
from_stream (C++20) — parses a year from a stream according to the provided format
from_stream (C++20) — parses a month from a stream according to the provided format
from_stream (C++20) — parses a day from a stream according to the provided format
from_stream (C++20) — parses a weekday from a stream according to the provided format
from_stream (C++20) — parses a month_day from a stream according to the provided format
from_stream (C++20) — parses a year_month from a stream according to the provided format
from_stream (C++20) — parses a year_month_day from a stream according to the provided format
get_time (C++11) — parses a date/time value of specified format. The vintage one, still iconic 🎀

One last little sidebar before we go 🦋 — under the hood this page is filed under:

Category: * Todo no example

So yeah, the to-do list literally says "no example." She's aware. She's working on it. Give her a minute 💅

And that's a wrap on std::chrono::parse(3) bestie!! 🎉 Source is http://cppreference.com, version 2024.06.10 — go drink some water, go parse a timestamp, and remember: the format string is not a suggestion, it's a lifestyle. Periodt 💖✨🫶🌸

📦 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