| Localization library | |||||||||||||||||||||||||
| Regular expressions library(C++11) | |||||||||||||||||||||||||
| Formatting library(C++20) | |||||||||||||||||||||||||
| Null-terminated sequence utilities | |||||||||||||||||||||||||
| Byte strings | |||||||||||||||||||||||||
| Multibyte strings | |||||||||||||||||||||||||
| Wide strings | |||||||||||||||||||||||||
| Primitive numeric conversions | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
| Text encoding identifications | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Member functions | ||||
time_put::puttime_put::do_put |
Defined in header <locale> | ||
public: iter_type put( iter_type out,std::ios_base& str, | (1) | |
public: iter_type put( iter_type out,std::ios_base& str, | (2) | |
protected: virtual iter_type do_put( iter_type out,std::ios_base& str, | (3) | |
Converts the calendar date and time stored in thestd::tm object pointed to byt into a character string, according to theformat string[fmtbeg, fmtend). The format string is the same as used bystd::strftime, but each format specifier is processed by an individual call todo_put(), which can be customized by extending this facet.
[fmtbeg, fmtend), examining the characters. Every character that is not a part of a format sequence is written to the output iteratorout immediately. To identify format sequences, this function narrows the next characterc in[fmtbeg, fmtend) as if bystd::ctype<char_type>(str.getloc()).narrow(c,0) and if it equals'%', the next one or two characters are compared to the list of format sequences recognized bystd::strftime plus any additional implementation-defined formats supported by this locale. For each valid format sequence, a call todo_put(out, str, fill, t, format, modifier) is made, whereformat is the format sequence character, andmodifier is the optional format sequence modifier ('E' or'O'). A value of'\0' is used if the modifier is absent.do_put member function of the most derived class.Contents |
| out | - | output iterator where the result of the conversion is written |
| str | - | a stream object that this function uses to obtain locale facets when needed, e.g.std::ctype to narrow characters |
| t | - | pointer to thestd::tm object from which the date/time values are obtained |
| fmtbeg | - | pointer to the first character of a sequence ofchar_type characters specifying theconversion format |
| fmtend | - | pointer one past the last character of a sequence ofchar_type characters specifying theconversion format |
| fill | - | fill character (usually space) |
| format | - | the character that names aconversion specifier |
| modifier | - | the optional modifier that may appear between% and theconversion specifier |
The format string consists of zero or more conversion specifiers and ordinary characters (except%). All ordinary characters, including the terminating null character, are copied to the output string without modification. Each conversion specification begins with% character, optionally followed byE orO modifier (ignored if unsupported by the locale), followed by the character that determines the behavior of the specifier. The following format specifiers are available:
| Conversion specifier | Explanation | Used fields |
|---|---|---|
% | writes literal%. The full conversion specification must be%%. | |
n(C++11) | writes newline character | |
t(C++11) | writes horizontal tab character | |
| Year | ||
Y | writesyear as a decimal number, e.g. 2017 | tm_year |
EY(C++11) | writesyear in the alternative representation, e.g.平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale | tm_year |
y | writes last 2 digits ofyear as a decimal number (range[00,99]) | tm_year |
Oy(C++11) | writes last 2 digits ofyear using the alternative numeric system, e.g. 十一 instead of 11 in ja_JP locale | tm_year |
Ey(C++11) | writesyear as offset from locale's alternative calendar period%EC (locale-dependent) | tm_year |
C(C++11) | writes first 2 digits ofyear as a decimal number (range[00,99]) | tm_year |
EC(C++11) | writes name of thebase year (period) in the locale's alternative representation, e.g. 平成 (Heisei era) in ja_JP | tm_year |
G(C++11) | writesISO 8601 week-based year, i.e. the year that contains the specified week. In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the following requirements:
| tm_year,tm_wday,tm_yday |
g(C++11) | writes last 2 digits ofISO 8601 week-based year, i.e. the year that contains the specified week (range[00,99]).In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the following requirements:
| tm_year,tm_wday,tm_yday |
| Month | ||
b | writesabbreviated month name, e.g.Oct (locale dependent) | tm_mon |
h(C++11) | synonym ofb | tm_mon |
B | writesfull month name, e.g.October (locale dependent) | tm_mon |
m | writesmonth as a decimal number (range[01,12]) | tm_mon |
Om(C++11) | writesmonth using the alternative numeric system, e.g. 十二 instead of 12 in ja_JP locale | tm_mon |
| Week | ||
U | writesweek of the year as a decimal number (Sunday is the first day of the week) (range[00,53]) | tm_year,tm_wday,tm_yday |
OU(C++11) | writesweek of the year, as by%U, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale | tm_year,tm_wday,tm_yday |
W | writesweek of the year as a decimal number (Monday is the first day of the week) (range[00,53]) | tm_year,tm_wday,tm_yday |
OW(C++11) | writesweek of the year, as by%W, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale | tm_year,tm_wday,tm_yday |
V(C++11) | writesISO 8601 week of the year (range[01,53]).In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the following requirements:
| tm_year,tm_wday,tm_yday |
OV(C++11) | writesweek of the year, as by%V, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale | tm_year,tm_wday,tm_yday |
| Day of the year/month | ||
j | writesday of the year as a decimal number (range[001,366]) | tm_yday |
d | writesday of the month as a decimal number (range[01,31]) | tm_mday |
Od(C++11) | writes zero-basedday of the month using the alternative numeric system, e.g. 二十七 instead of 27 in ja_JP locale Single character is preceded by a space. | tm_mday |
e(C++11) | writesday of the month as a decimal number (range[1,31]).Single digit is preceded by a space. | tm_mday |
Oe(C++11) | writes one-basedday of the month using the alternative numeric system, e.g. 二十七 instead of 27 in ja_JP locale Single character is preceded by a space. | tm_mday |
| Day of the week | ||
a | writesabbreviated weekday name, e.g.Fri (locale dependent) | tm_wday |
A | writesfull weekday name, e.g.Friday (locale dependent) | tm_wday |
w | writesweekday as a decimal number, where Sunday is0 (range[0-6]) | tm_wday |
Ow(C++11) | writesweekday, where Sunday is0, using the alternative numeric system, e.g. 二 instead of 2 in ja_JP locale | tm_wday |
u(C++11) | writesweekday as a decimal number, where Monday is1 (ISO 8601 format) (range[1-7]) | tm_wday |
Ou(C++11) | writesweekday, where Monday is1, using the alternative numeric system, e.g. 二 instead of 2 in ja_JP locale | tm_wday |
| Hour, minute, second | ||
H | writeshour as a decimal number, 24 hour clock (range[00-23]) | tm_hour |
OH(C++11) | writeshour from 24-hour clock using the alternative numeric system, e.g. 十八 instead of 18 in ja_JP locale | tm_hour |
I | writeshour as a decimal number, 12 hour clock (range[01,12]) | tm_hour |
OI(C++11) | writeshour from 12-hour clock using the alternative numeric system, e.g. 六 instead of 06 in ja_JP locale | tm_hour |
M | writesminute as a decimal number (range[00,59]) | tm_min |
OM(C++11) | writesminute using the alternative numeric system, e.g. 二十五 instead of 25 in ja_JP locale | tm_min |
S | writessecond as a decimal number (range[00,60]) | tm_sec |
OS(C++11) | writessecond using the alternative numeric system, e.g. 二十四 instead of 24 in ja_JP locale | tm_sec |
| Other | ||
c | writesstandard date and time string, e.g.Sun Oct 17 04:41:13 2010 (locale dependent) | all |
Ec(C++11) | writesalternative date and time string, e.g. using 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale | all |
x | writes localizeddate representation (locale dependent) | all |
Ex(C++11) | writesalternative date representation, e.g. using 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale | all |
X | writes localizedtime representation, e.g. 18:40:20 or 6:40:20 PM (locale dependent) | all |
EX(C++11) | writesalternative time representation (locale dependent) | all |
D(C++11) | equivalent to"%m/%d/%y" | tm_mon,tm_mday,tm_year |
F(C++11) | equivalent to"%Y-%m-%d" (the ISO 8601 date format) | tm_mon,tm_mday,tm_year |
r(C++11) | writes localized12-hour clock time (locale dependent) | tm_hour,tm_min,tm_sec |
R(C++11) | equivalent to"%H:%M" | tm_hour,tm_min |
T(C++11) | equivalent to"%H:%M:%S" (the ISO 8601 time format) | tm_hour,tm_min,tm_sec |
p | writes localizeda.m. or p.m. (locale dependent) | tm_hour |
z(C++11) | writesoffset from UTC in the ISO 8601 format (e.g.-0430), or no characters if the time zone information is not available | tm_isdst |
Z | writes locale-dependenttime zone name or abbreviation, or no characters if the time zone information is not available | tm_isdst |
Iterator pointing one past the last character that was produced.
No error handling is provided.
Thefill character is provided for those implementation-defined format specifiers and for the user-defined overrides ofdo_put() that use padding and filling logic. Such implementations typically make use of the formatting flags fromstr.
#include <iostream>#include <sstream>#include <iomanip>#include <ctime> void try_time_put(conststd::tm* t,conststd::string& fmt){std::cout.imbue(std::locale());std::cout<<"In the locale '"<<std::cout.getloc().name()<<"' : '"; std::use_facet<std::time_put<char>>(std::cout.getloc()).put({std::cout},std::cout,' ', t,&fmt[0],&fmt[0]+ fmt.size()); std::cout<<"'\n";} int main(){std::time_t t=std::time(NULL);std::tm tm=*std::localtime(&t); std::string fmt="%c";std::cout<<"Using the format string '"<< fmt<<"' to format the time: "<<std::ctime(&t)<<'\n'; std::locale::global(std::locale("de_DE.utf8")); try_time_put(&tm, fmt); std::locale::global(std::locale("el_GR.utf8")); try_time_put(&tm, fmt); std::locale::global(std::locale("ja_JP.utf8")); try_time_put(&tm, fmt);}
Possible output:
Using the format string '%c' to format the time: Mon Feb 11 22:58:50 2013 In the locale 'de_DE.utf8' : 'Mo 11 Feb 2013 23:02:38 EST'In the locale 'el_GR.utf8' : 'Δευ 11 Φεβ 2013 11:02:38 μμ EST'In the locale 'ja_JP.utf8' : '2013年02月11日 23時02分38秒'
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 164 | C++98 | the purpose of the parameterfill was not clear | made clear |
(C++11) | formats and outputs a date/time value according to the specified format (function template)[edit] |
[virtual](C++11) | extracts date/time components from input stream, according to the specified format (virtual protected member function of std::time_get<CharT,InputIt>)[edit] |
