25 Time library [time]

25.11 Formatting [time.format]

1
#
Each format overload specified in this subclause calls to_­stream unqualified, so as to enable argument dependent lookup ([basic.lookup.argdep]).
🔗
template<class charT, class Streamable> basic_string<charT> format(const charT* fmt, const Streamable& s);
2
#
Remarks: This function shall not participate in overload resolution unless 
to_stream(declval<basic_ostream<charT>&>(), fmt, s)
is a valid expression.
3
#
Effects: Constructs a local variable of type basic_­ostringstream<charT> (named os for exposition purposes).
Executes os.exceptions(ios​::​failbit | ios​::​badbit).
Then calls to_­stream(os, fmt, s).
4
#
Returns: os.str().
🔗
template<class charT, class Streamable> basic_string<charT> format(const locale& loc, const charT* fmt, const Streamable& s);
5
#
Remarks: This function shall not participate in overload resolution unless 
to_stream(declval<basic_ostream<charT>&>(), fmt, s)
is a valid expression.
6
#
Effects: Constructs a local variable of type basic_­ostringstream<charT> (named os for exposition purposes).
Executes os.exceptions(ios​::​failbit | ios​::​badbit).
Then calls os.imbue(loc).
Then calls to_­stream(os, fmt, s).
7
#
Returns: os.str().
🔗
template<class charT, class traits, class Alloc, class Streamable> basic_string<charT, traits, Alloc> format(const basic_string<charT, traits, Alloc>& fmt, const Streamable& s);
8
#
Remarks: This function shall not participate in overload resolution unless 
to_stream(declval<basic_ostringstream<charT, traits, Alloc>&>(), fmt.c_str(), s)
is a valid expression.
9
#
Effects: Constructs a local variable of type basic_­ostringstream<charT, traits, Alloc> (named os for exposition purposes).
Executes os.exceptions(ios​::​failbit | ios​::​badbit).
Then calls to_­stream(os, fmt.c_­str(), s).
10
#
Returns: os.str().
🔗
template<class charT, class traits, class Alloc, class Streamable> basic_string<charT, traits, Alloc> format(const locale& loc, const basic_string<charT, traits, Alloc>& fmt, const Streamable& s);
11
#
Remarks: This function shall not participate in overload resolution unless 
to_stream(declval<basic_ostringstream<charT, traits, Alloc>&>(), fmt.c_str(), s)
is a valid expression.
12
#
Effects: Constructs a local variable of type basic_­ostringstream<charT, traits, Alloc> (named os for exposition purposes).
Then calls os.imbue(loc).
Executes os.exceptions(ios​::​failbit | ios​::​badbit).
Then calls to_­stream(os, fmt.c_­str(), s).
13
#
Returns: os.str().
14
#
The format functions call a to_­stream function with a basic_­ostream, a formatting string specifier, and a Streamable argument.
Each to_­stream overload is customized for each Streamable type.
However all to_­stream overloads treat the formatting string specifier according to the following specification:
15
#
The fmt string consists of zero or more conversion specifiers and ordinary multibyte characters.
A conversion specifier consists of a % character, possibly followed by an E or O modifier character (described below), followed by a character that determines the behavior of the conversion specifier.
All ordinary multibyte characters (excluding the terminating null character) are streamed unchanged into the basic_­ostream.
16
#
Each conversion specifier is replaced by appropriate characters as described in Table 88.
Some of the conversion specifiers depend on the locale which is imbued to the basic_­ostream.
If the Streamable object does not contain the information the conversion specifier refers to, the value streamed to the basic_­ostream is unspecified.
17
#
Unless explicitly specified, Streamable types will not contain time zone abbreviation and time zone offset information.
If available, the conversion specifiers %Z and %z will format this information (respectively).
If the information is not available, and %Z or %z are contained in fmt, os.setstate(ios_­base​::​failbit) shall be called.
Table 88 — Meaning of format conversion specifiers
Specifier
Replacement
%a
The locale's abbreviated weekday name.
If the value does not contain a valid weekday, setstate(ios​::​failbit) is called.
%A
The locale's full weekday name.
If the value does not contain a valid weekday, setstate(ios​::​failbit) is called.
%b
The locale's abbreviated month name.
If the value does not contain a valid month, setstate(ios​::​failbit) is called.
%B
The locale's full month name.
If the value does not contain a valid month, setstate(ios​::​failbit) is called.
%c
The locale's date and time representation.
The modified command %Ec produces the locale's alternate date and time representation.
%C
The year divided by 100 using floored division.
If the result is a single decimal digit, it is prefixed with 0.
The modified command %EC produces the locale's alternative representation of the century.
%d
The day of month as a decimal number.
If the result is a single decimal digit, it is prefixed with 0.
The modified command %Od produces the locale's alternative representation.
%D
Equivalent to %m/%d/%y.
%e
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 %Oe produces the locale's alternative representation.
%F
Equivalent to %Y-%m-%d.
%g
The last two decimal digits of the ISO week-based year.
If the result is a single digit it is prefixed by 0.
%G
The ISO week-based year as a decimal number.
If the result is less than four digits it is left-padded with 0 to four digits.
%h
Equivalent to %b.
%H
The hour (24-hour clock) as a decimal number.
If the result is a single digit, it is prefixed with 0.
The modified command %OH produces the locale's alternative representation.
%I
The hour (12-hour clock) as a decimal number.
If the result is a single digit, it is prefixed with 0.
The modified command %OI produces the locale's alternative representation.
%j
The day of the year as a decimal number.
Jan 1 is 001.
If the result is less than three digits, it is left-padded with 0 to three digits.
%m
The month as a decimal number.
Jan is 01.
If the result is a single digit, it is prefixed with 0.
The modified command %Om produces the locale's alternative representation.
%M
The minute as a decimal number.
If the result is a single digit, it is prefixed with 0.
The modified command %OM produces the locale's alternative representation.
%n
A new-line character.
%p
The locale's equivalent of the AM/PM designations associated with a 12-hour clock.
%r
The locale's 12-hour clock time.
%R
Equivalent to %H:%M.
%S
Seconds 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 %OS produces the locale's alternative representation.
%t
A horizontal-tab character.
%T
Equivalent to %H:%M:%S.
%u
The ISO weekday as a decimal number (1-7), where Monday is 1.
The modified command %Ou produces the locale's alternative representation.
%U
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 %OU produces the locale's alternative representation.
%V
The ISO week-based week number as a decimal number.
If the result is a single digit, it is prefixed with 0.
The modified command %OV produces the locale's alternative representation.
%w
The weekday as a decimal number (0-6), where Sunday is 0.
The modified command %Ow produces the locale's alternative representation.
%W
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 %OW produces the locale's alternative representation.
%x
The locale's date representation.
The modified command %Ex produces the locale's alternate date representation.
%X
The locale's time representation.
The modified command %EX produces the locale's alternate time representation.
%y
The last two decimal digits of the year.
If the result is a single digit it is prefixed by 0.
%Y
The year as a decimal number.
If the result is less than four digits it is left-padded with 0 to four digits.
%z
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 %Ez and %Oz insert a : between the hours and minutes: -04:30.
If the offset information is not available, setstate(ios_­base​::​failbit) shall be called.
%Z
The time zone abbreviation.
If the time zone abbreviation is not available, setstate(ios_­base​::​failbit) shall be called.
%%
A % character.