NAME¶

std::formatter,std::chrono::local_time_format - std::formatter,std::chrono::local_time_format

Synopsis¶

Defined in header <chrono>
template<class Duration, class CharT> (1)
struct formatter<std::chrono::local_time<Duration>, CharT>;
template<class Duration>

struct /*local-time-format-t*/ { // exposition only
std::chrono::local_time<Duration> time; // exposition only
const std::string* abbrev; // exposition only
const std::chrono::seconds* offset; // exposition only

};
template<class Duration> (2)

/*local-time-format-t*/<Duration>
local_time_format(const std::chrono::local_time<Duration>& tp,
const std::string* abbrev = nullptr,

const std::chrono::seconds* offset_sec = nullptr);
template<class Duration, class CharT>
struct formatter</*local-time-format-t*/<Duration>, CharT>;

Specialization of std::formatter that defines formatting rules for a
std::chrono::local_time.

1) If %Z, %z or a modified variant of %z is used, a std::format_error is thrown.
2) The local_time_format function returns a value of unspecified type that holds the
local time, offset, and time zone abbreviation.
When an object f of this unspecified type is formatted, if %Z is used, it is
replaced with *f.abbrev widened to CharT if f.abbrev is not null; otherwise a
std::format_error is thrown. If %z or a modified variant thereof is used, an offset
of *f.offset_sec will be formatted if f.offset_sec is not null; otherwise a
std::format_error is thrown.

std::formatter is usually not directly accessed, but is used through formatting
functions.

Format specification

The format specification has the form

fill-and-align(optional) width(optional) precision(optional) L(optional)
chrono-spec(optional)

fill-and-align, width, and precision have the same meaning as in standard format
specification. precision is valid only for std::chrono::duration types where the
representation type Rep is a floating-point type, otherwise std::format_error is
thrown.

The locale used for formatting is determined as follows:

* the default "C" locale if L is not present in the format specification,
* otherwise, the locale denoted by the std::locale passed to the formatting
function, if any,
* otherwise (L is present but no std::locale is passed to the formatting
function), the global locale.

The chrono-spec consists of one or more conversion specifiers and ordinary
characters (other than {, } and %). A chrono-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 an E or O modifier character is inserted after the %
character. Each conversion specifier is replaced by appropriate characters in the
output as described below.

If the chrono-spec is empty, the chrono object is formatted as if by streaming it to
an object os of type std::stringstream with the formatting locale (one of
std::locale::classic(), the passed std::locale object, and std::locale::global())
imbued and copying os.str() to the output buffer with additional padding and
adjustments as per format specifiers.

The following format specifiers are available:

Conversion Explanation
specifier
%% Writes a literal % character.
%n Writes a newline character.
%t Writes a horizontal tab character.
Year
Writes the year divided by 100 using floored division. If the result is
%C a single decimal digit, it is prefixed with 0.
%EC
The modified command %EC writes the locale's alternative representation
of the century.
Writes the last two decimal digits of the year. If the result is a
single digit it is prefixed by 0.
%y
%Oy The modified command %Oy writes the locale's alternative representation.
%Ey
The modified command %Ey writes the locale's alternative representation
of offset from %EC (year only).
Writes the year as a decimal number. If the result is less than four
%Y digits it is left-padded with 0 to four digits.
%EY
The modified command %EY writes the locale's alternative full year
representation.
Month
%b Writes the locale's abbreviated month name.
%h
%B Writes the locale's full month name.
Writes the month as a decimal number (January is 01). If the result is a
%m single digit, it is prefixed with 0.
%Om
The modified command %Om writes the locale's alternative representation.
Day
Writes the day of month as a decimal number. If the result is a single
%d decimal digit, it is prefixed with 0.
%Od
The modified command %Od writes the locale's alternative representation.
Writes the day of month as a decimal number. If the result is a single
%e decimal digit, it is prefixed with a space.
%Oe
The modified command %Oe writes the locale's alternative representation.
Day of the week
%a Writes the locale's abbreviated weekday name.
%A Writes the locale's full weekday name.
%u Writes the ISO weekday as a decimal number (1-7), where Monday is 1.
%Ou
The modified command %Ou writes the locale's alternative representation.
%w Writes the weekday as a decimal number (0-6), where Sunday is 0.
%Ow
The modified command %Ow writes 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 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.
Writes the ISO 8601 week of the year as a decimal number. If the result
%V is a single digit, it is prefixed with 0.
%OV
The modified command %OV writes the locale's alternative representation.
Week/day of the year
Writes the day of the year as a decimal number (January 1 is 001). If
%j the result is less than three digits, it is left-padded with 0 to three
digits.
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
%U that are in week 00. If the result is a single digit, it is prefixed
%OU with 0.

The modified command %OU writes the locale's alternative representation.
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
%W that are in week 00. If the result is a single digit, it is prefixed
%OW with 0.

The modified command %OW writes the locale's alternative representation.
Date
%D Equivalent to "%m/%d/%y".
%F Equivalent to "%Y-%m-%d".
Writes the locale's date representation.
%x
%Ex The modified command %Ex produces the locale's alternate date
representation.
Time of day
Writes the hour (24-hour clock) as a decimal number. If the result is a
%H single digit, it is prefixed with 0.
%OH
The modified command %OH writes the locale's alternative representation.
Writes the hour (12-hour clock) as a decimal number. If the result is a
%I single digit, it is prefixed with 0.
%OI
The modified command %OI writes the locale's alternative representation.
Writes the minute as a decimal number. If the result is a single digit,
%M it is prefixed with 0.
%OM
The modified command %OM writes the locale's alternative representation.
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
%S seconds, then the format is a decimal floating-point number with a fixed
%OS 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 %OS writes the locale's alternative representation.
%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.
Writes the locale's time representation.
%X
%EX The modified command %EX writes the locale's alternate time
representation.
Time zone
Writes the offset from UTC in the ISO 8601 format. For example -0430
%z refers to 4 hours 30 minutes behind UTC. If the offset is zero, +0000 is
%Ez used.
%Oz
The modified commands %Ez and %Oz insert a : between the hours and
minutes (e.g., -04:30).
%Z Writes the time zone abbreviation.

Miscellaneous¶

Writes the locale's date and time representation.
%c
%Ec The modified command %Ec writes the locale's alternative date and time
representation.

The following specifiers are recognized, but will cause std::format_error to be
thrown:

Conversion Explanation
specifier
Duration count
%Q Writes the count of ticks of the duration, i.e. the value obtained via
count().
%q Writes the unit suffix of the duration, as specified in operator<<().

Example¶

This section is incomplete
Reason: no example

See also¶

format stores formatted representation of the arguments in a new string
(C++20) (function template)