|
|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Member functions | ||||
| Time point I/O | ||||
formatter<std::chrono::sys_time> | ||||
Defined in header <chrono> | ||
template<class Duration,class CharT> struct formatter<std::chrono::sys_time<Duration>, CharT>; | (since C++20) | |
Specialization ofstd::formatter that defines formatting rules for astd::chrono::sys_time.
%Z is used, it is replaced with"UTC" widened toCharT.%z or a modified variant thereof is used, an offset of0min will be formatted.Thestd::formatter specialization is usually not directly accessed, but is used throughformatting functions.
Contents |
The format specification has the form
fill-and-align (optional)width (optional)precision (optional)L(optional)chrono-spec (optional) | |||||||||
fill-and-align,width, andprecision have the same meaning as instandard format specification.precision is valid only forstd::chrono::duration types where the representation typeRep is a floating-point type, otherwisestd::format_error is thrown.
The locale used for formatting is determined as follows:
L is not present in the format specification,L is present but nostd::locale is passed to the formatting function), the global locale.If the(ordinary or wide) string literal encoding is a Unicode encoding form and the locale is among an implementation-defined set of locales, each replacement that depends on the locale is performed as if the replacement character sequence is converted to the literal encoding.
Thechrono-spec consists of one or more conversion specifiers and ordinary characters (other than{,}, and%). Achrono-spec must start with a conversion specifier. All ordinary characters are written to the output without modification. 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 anE orO modifier character is inserted after the% character. Each conversion specifier is replaced by appropriate characters in the output as described below.
Unless otherwise specified, if thechrono-spec is empty, the chrono object is formatted as if bystreaming it to an objectos of typestd::basic_ostringstream<CharT> with the formatting locale (one ofstd::locale::classic(), the passedstd::locale object, andstd::locale::global())imbued and copyingos.str() to the output buffer with additional padding and adjustments as per format specifiers.
The following format specifiers are available:
| Conversion specifier | Explanation | |
|---|---|---|
%% | Writes a literal% character. | |
%n | Writes a newline character. | |
%t | Writes a horizontal tab character. | |
| Year | ||
%C%EC | Writes the year divided by 100 using floored division. If the result is a single decimal digit, it is prefixed with 0. The modified command | |
%y%Oy%Ey | Writes the last two decimal digits of the year. If the result is a single digit it is prefixed by 0. The modified command The modified command | |
%Y%EY | Writes the year as a decimal number. If the result is less than four digits it is left-padded with 0 to four digits. The modified command | |
| Month | ||
%b%h | Writes the locale's abbreviated month name. | |
%B | Writes the locale's full month name. | |
%m%Om | Writes the month as a decimal number (January is01). If the result is a single digit, it is prefixed with 0.The modified command | |
| Day | ||
%d%Od | Writes the day of month as a decimal number. If the result is a single decimal digit, it is prefixed with 0. The modified command | |
%e%Oe | Writes the day of month as a decimal number. If the result is a single decimal digit, it is prefixed with a space. The modified command | |
| Day of the week | ||
%a | Writes the locale's abbreviated weekday name. | |
%A | Writes the locale's full weekday name. | |
%u%Ou | Writes the ISO weekday as a decimal number (1-7), where Monday is1.The modified command | |
%w%Ow | Writes the weekday as a decimal number (0-6), where Sunday is0.The modified command | |
| ISO 8601 week-based year | ||
In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the following requirements:
| ||
%g | Writes the last two decimal digits of the ISO 8601 week-based year. If the result is a single digit it is prefixed by 0. | |
%G | Writes the ISO 8601 week-based year as a decimal number. If the result is less than four digits it is left-padded with 0 to four digits. | |
%V%OV | Writes the ISO 8601 week of the year as a decimal number. If the result is a single digit, it is prefixed with 0. The modified command | |
| Week/day of the year | ||
%j | Writes the day of the year as a decimal number (January 1 is001). If the result is less than three digits, it is left-padded with 0 to three digits. | |
%U%OU | Writes 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. If the result is a single digit, it is prefixed with 0. The modified command | |
%W%OW | Writes 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. If the result is a single digit, it is prefixed with 0. The modified command | |
| Date | ||
%D | Equivalent to"%m/%d/%y". | |
%F | Equivalent to"%Y-%m-%d". | |
%x%Ex | Writes the locale's date representation. The modified command | |
| Time of day | ||
%H%OH | Writes the hour (24-hour clock) as a decimal number. If the result is a single digit, it is prefixed with 0. The modified command | |
%I%OI | Writes the hour (12-hour clock) as a decimal number. If the result is a single digit, it is prefixed with 0. The modified command | |
%M%OM | Writes the minute as a decimal number. If the result is a single digit, it is prefixed with 0. The modified command | |
%S%OS | Writes the second as a decimal number. If the number of seconds is less than 10, the result is prefixed with 0. If the precision of the input cannot be exactly represented with seconds, then the format is a decimal floating-point number with a fixed format and a precision matching that of the precision of the input (or to a microseconds precision if the conversion to floating-point decimal seconds cannot be made within 18 fractional digits). The character for the decimal point is localized according to the locale. The modified command | |
%p | Writes 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 | Writes the locale's 12-hour clock time. | |
%X%EX | Writes the locale's time representation. The modified command | |
| Time zone | ||
%z%Ez%Oz | Writes the offset from UTC in the ISO 8601 format. For example-0430 refers to 4 hours 30 minutes behind UTC. If the offset is zero,+0000 is used.The modified commands | |
%Z | Writes the time zone abbreviation. | |
| Miscellaneous | ||
%c%Ec | Writes the locale's date and time representation. The modified command | |
The following specifiers are recognized, but will causestd::format_error to be thrown:
| Conversion specifier | Explanation | |
|---|---|---|
| Duration count | ||
%Q | Writes the count of ticks of the duration, i.e. the value obtained viacount(). | |
%q | Writes the unit suffix of the duration, as specified inoperator<<(). | |
#include <chrono>#include <format>#include <iostream> int main(){std::chrono::time_point<std::chrono::utc_clock> epoch; std::cout<<std::format("The time of the Unix epoch was {0:%F}T{0:%R%z}.", epoch)<<'\n';}
Output:
The time of the Unix epoch was 1970-01-01T00:00+0000.
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| P2372R3 | C++20 | formatter used the global locale or passed locale | default"C" locale is used whenL is absent |
(C++20) | stores formatted representation of the arguments in a new string (function template)[edit] |
