Library: Localization
time_putlocale::facet
A time formatting facet for output
#include <locale>
namespace std {
template <class charT, class OutputIterator =
ostreambuf_iterator<charT> >
class time_put;
}
template <> class time_put<char>; template <> class time_put<wchar_t>;
The time_put facet includes facilities for formatted output of date/time values. The put() member functions format a struct tm that represents a date/time into a character string representation.
namespace std {
template <class charT, class OutputIterator =
ostreambuf_iterator<charT> >
class time_put : public locale::facet {
public:
typedef charT char_type;
typedef OutputIterator iter_type;
explicit time_put(size_t = 0);
iter_type put(iter_type, ios_base&,
char_type, const tm*,
const charT*, const charT*) const;
iter_type put(iter_type, ios_base&, char_type,
const tm*, char, char = 0) const;
static locale::id id;
protected:
virtual iter_type do_put(iter_type, ios_base&,
char_type, const tm*,
char, char) const;
};
}
char_type
The type of the first template argument.
iter_type
The type of the second template argument.
explicit time_put(size_t refs = 0);
Constructs a time_put object. Calls locale::facet (refs).
The refs argument is set to the initial value of the time_put object's reference count. A time_put object f constructed with (refs == 0) that is installed in one or more locale objects will be destroyed and the storage it occupies will be deallocated when the last locale object containing the facet is destroyed, as if by calling delete static_cast<locale::facet*>(&f). A time_put object constructed with (refs != 0) will not be destroyed by any locale objects in which it may have been installed.
virtual ~time_put();
Destroys the facet.
static locale::id id;
Unique identifier for this type of facet.
iter_type
put(iter_type s, ios_base& f,
char_type fill, const tm* tmb,
const char_type* pattern, const char_type* pat_end) const;
Formats the contents of the object pointed to by tmb into the output sequence beginning with s. The format of the output sequence is determined by the string of format specifiers and modifiers contained in the range [pattern,pat_end). These specifiers and modifiers are from the same set as those used by the strftime function and are applied in exactly the same way. See Table 36 for a description of strftime formatting characters.
The f argument is used to determine the justification and the width of the output sequence.
The fill argument is used for any padding.
Returns an iterator pointing one past the last character written.
iter_type
put(iter_type s, ios_base& f, char_type fill,
const tm* tmb, char format, char modifier = 0) const;
Calls the protected virtual function do_put(s,f,fill,tmb,format,modifier).
iter_type
do_put(iter_type s, ios_base& f, char_type fill,
const tm* tmb, char format, char modifier = 0) const;
Formats the contents of the object pointed to by the tmb into the output sequence beginning with s. The output sequence is formatted according the specifier format and modifier modifier. These values are interpreted in the same way as the strftime function interprets its format specifiers and modifiers flags. See the table below for a description of recognized formatting characters.
The f argument is used to determine the justification and the width of the output sequence.
The fill argument is used for any padding.
Returns an iterator pointing one past the last character written.
Table 36 illustrates the recognized formatting characters of strftime. The values in the table are for February 29, 1984 at 14:34:56 (MST).
| Format character | Meaning | C locale value |
a |
Abbreviated weekday name. In the C locale, the first three characters of %A. [tm_wday] |
Wed |
A |
Full weekday name. [tm_wday] |
Wednesday |
b |
Abbreviated month name. In the C locale, the first three characters of %B. [tm_mon] |
Feb |
B |
Full month name. [tm_mon] |
February |
c |
Date and time. In the C Locale, equivalent to %a %b %e %H %M %S %Y May use any or all members. |
Wed Feb 29 14:34:56 1984 |
C |
The year divided by 100 and truncated to an integer. [00,99][tm_year] |
84 |
d |
Day of the month. [01,31][tm_mday] |
29 |
D |
Equivalent to %m/%d/%y [tm_mon, tm_mday, tm_year] |
02/29/84 |
e |
The day of the month [1,31] with single digits preceded by a space. [tm_mday] |
29 |
F |
Equivalent to %Y-%m-%d (the ISO 8601:2000 standard date format). [tm_year, tm_mon, tm_mday] |
1984-02-29 |
g |
The last 2 digits of the ISO 8601:2000 standard week-based year [00,99]. [tm_year, tm_wday, tm_yday] |
84 |
G |
The ISO 8601:2000 standard week-based year. [tm_year, tm_wday, tm_yday] |
1984 |
h |
Equivalent to %b. [tm_mon] |
Feb |
H |
Hour of the 24-hour day.[00,23]. [tm_hour] |
14 |
i |
Hour of the 12-hour day [1,12]. Single digits preceded by a blank. [tm_hour] 1 |
" 2" |
I |
Hour of the 12-hour day [01,12]. [tm_hour] |
02 |
j |
Day of the year [001,366]. [tm_yday] |
60 |
k |
Hour of the 24-hour day [0,23]. Single digits preceded by a blank. [tm_hour]1 |
14 |
m |
Month of the year [01,12]. [tm_mon] |
02 |
M |
Minutes after the hour [00,59]. [tm_min] |
34 |
n |
The <newline> character from the Portable Character Set. |
\n |
p |
AM/PM indicator, if any. In the C locale, one of "AM", and "PM". [tm_hour] |
PM |
r |
Time using a.m. and p.m. notation. In the C locale, equivalent to %I:%M %S %p. [tm_hour, tm_min, tm_sec] |
02:34:56 PM |
R |
Time in 24-hour notation (%H:%M). [tm_hour, tm_min] |
14:34 |
S |
Seconds after the minute. [tm_sec] |
56 |
t |
The <tab> character from the Portable Character Set. |
\t |
T |
Time (%H:%M:%S). [tm_hour, tm_min, tm_sec] |
14:34:56 |
u |
Weekday as a decimal number, with 1 for Monday [1,7]. [tm_wday] |
3 |
U |
Sunday-based week of the year [00,53]. [tm_year, tm_wday, tm_yday] |
09 |
V |
ISO 8601:2000 standard (Monday-based) week number of the year [01,53]. [tm_year, tm_wday, tm_yday] |
09 |
w |
Day of the week, with 0 for Sunday [0,6]. |
3 |
W |
Monday-based week of the year [00,53]. [tm_year, tm_wday, tm_yday] |
09 |
x |
Date. In the C locale, equivalent to %m/%d/%y. [may use any or all members] |
02/29/1984 |
X |
Time. In the C locale, equivalent to %T. [may use any or all members] |
14:34:56 |
y |
Last 2 digits of the year [00,99]. [tm_year] |
84 |
Y |
Year. [tm_year] |
1984 |
z |
The offset from UTC in the ISO 8601:2000 standard format (+hhmm or -hhmm), or by no characters if no time zone is determinable. If tm_isdst is zero, the standard time offset is used; otherwise if tm_isdst is greater than zero, the daylight savings time offset is used; otherwise, no characters are returned. [tm_isdst] |
e.g., -0700 |
Z |
Time zone name (implementation-defined). [tm_isdst] |
e.g. MST |
Table 37 illustrates the recgonized modified formatting characters and their corresponding meaning.
| Format string | Meaning |
%Ec |
The locale's alternative appropriate date and time representation. |
%EC |
The name of the base year (period) in the locale's alternative representation. |
%Ex |
The locale's alternative date representation. |
%EX |
The locale's alternative time representation. |
%Ey |
The offset from %EC (year only) in the locale's alternative representation. |
%EY |
The full alternative year representation. |
%Od |
The day of the month, using the locale's alternative numeric symbols, filled if necessary with leading zeros if there is any alternative symbol for zero; otherwise, with leading spaces. |
%Oe |
The day of the month, using the locale's alternative numeric symbols, filled if necessary with leading spaces. |
%OH |
The hour of the 24-hour day using the locale's alternative numeric symbols. |
%OI |
The hour of the 12-hour day using the locale's alternative numeric symbols. |
%Om |
The month using the locale's alternative numeric symbols. |
%OM |
The minutes using the locale's alternative numeric symbols. |
%OS |
The seconds using the locale's alternative numeric symbols. |
%Ou |
The Monday-based weekday as a number in the locale's alternative representation. |
%OU |
The Sunday-based week number of the year (as in %U) using the locale's alternative numeric symbols. |
%OV |
The Monday-based week number of the year (as in %V) using the locale's alternative numeric symbols. |
%Ow |
The Sunday-based number of the weekday using the locale's alternative numeric symbols. |
%OW |
The Monday-based week number of the year using the locale's alternative numeric symbols. |
%Oy |
Replaced by the year (offset from %C) using the locale's alternative numeric symbols. |
In the C locale, the 'E' and 'O' modifiers are ignored.
The behavior of the functions is undefined if the modifier is other than '\0', 'E' and 'O', or if the format character is other than those specified in Table 36 above.
For example, if the set of a locale's alternative numeric symbols consists of { "", "1st", "2nd", "3rd", ... , "31st"} then the date Wednesday, February 29, 1984 will be formatted using "%Od" as "29th".
//
// timeput.cpp
//
#include <ctime> // for struct tm
#include <iostream> // for cout, endl
#include <locale> // for locale, time_put
int main ()
{
// zero-out all members (including any non-standard
// ones) std::tm t = std::tm ();
// assign individual members being careful to
// avoid relying on the implementation-defined
// layout of the struct
t.tm_sec = 56; // seconds
t.tm_min = 34; // minutes
t.tm_hour = 14; // hours (i.e., 2 PM)
t.tm_mday = 29; // day of month
t.tm_mon = 1; // month (Feb)
t.tm_year = 84; // years since 1900
// (i.e., 1984)
t.tm_yday = 59; // day of the year
t.tm_wday = 3; // day of the week (Wednesday)
t.tm_isdst = 0; // Daylight Saving Time
const char* const fmt[] = {
"%a", "%A", "%b", "%B", "%c", "%C", "%d", "%D",
"%e", "%F", "%g", "%G", "%h", "%H", "%I", "%j",
"%k", "%l", "%m", "%M", "%n", "%p", "%r", "%R",
"%S", "%t", "%T", "%u", "%U", "%V", "%w", "%W", "%x",
"%X", "%y", "%Y", "%z", "%Z", "%%", "%Ec", "%EC", "%Ex",
"%EX", "%Ey", "%EY", "%Od", "%Oe", "%OH", "%OI", "%Om",
"%OM", "%OS", "%Ou", "%OU", "%OV", "%Ow", "%OW", "%Oy"
};
// retrieve the time_put facet installed in cout
const std::time_put<char> &tput =
std::use_facet<std::time_put<char> >(std::cout.getloc ());
// print out the value of t formatted according to each
// of the format/ specifiers defined above
for (std::size_t i = 0; i != sizeof fmt / sizeof *fmt; ++i) {
std::cout << " \"" << fmt [i] << "\" \"";
if ('n' == fmt [i][1])
std::cout << "\\n";
else if ('t' == fmt [i][1])
std::cout << "\\t";
else
tput.put (std::ostreambuf_iterator<char>(std::cout.rdbuf ()),
std::cout, '\0', &t, fmt [i],
fmt [i] + std::char_traits<char>::length (fmt [i]));
std::cout << "\"\n";
}
return 0;
}
Program Output:
With the TZ environment variable defined to a value equivalent to PST8PDT, the output of the program will be as follows:
"%a" "Wed"
"%A" "Wednesday"
"%b" "Feb"
"%B" "February"
"%c" "Wed Feb 29 14:34:56 1984"
"%C" "19"
"%d" "29"
"%D" "02/29/84"
"%e" "29"
"%F" "1984-02-29"
"%g" "84"
"%G" "1984"
"%h" "Feb"
"%H" "14"
"%I" "02"
"%j" "060"
"%k" "14"
"%l" " 2"
"%m" "02"
"%M" "34"
"%n" "\n"
"%p" "PM"
"%r" "02:34:56 PM"
"%R" "14:34"
"%S" "56"
"%t" "\t"
"%T" "14:34:56"
"%u" "3"
"%U" "09"
"%V" "09"
"%w" "3"
"%W" "09"
"%x" "02/29/84"
"%X" "14:34:56"
"%y" "84"
"%Y" "1984"
"%z" "+0700"
"%Z" "MST"
"%%" "%"
"%Ec" "Wed Feb 29 14:34:56 1984"
"%EC" "19"
"%Ex" "02/29/84"
"%EX" "14:34:56"
"%Ey" "84"
"%EY" "1984"
"%Od" "29"
"%Oe" "29"
"%OH" "14"
"%OI" "02"
"%Om" "02"
"%OM" "34"
"%OS" "56"
"%Ou" "3"
"%OU" "09"
"%OV" "09"
"%Ow" "3"
"%OW" "09"
"%Oy" "84"
ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 25.2.5.3
ISO/IEC 9899:1999 -- Programming Language C, Section 7.23.3.5, paragraph 3
IEEE Std 1003.1-2001 -- The Open Group Base Specifications Issue 6, strftime
ISO 8601:2000 -- Data elements and interchange formats -- Information interchange -- Representation of dates and times
IEEE Std 1003.1-2001 -- The Open Group Base Specifications Issue 6, Character Set