Apache C++ Standard Library Reference Guide

## time_put

Library: Localization

                                                                                                    time_put      locale::facet

- Local Index
- Summary
- Synopsis
- Specializations
- Description
- Interface
- Member Types
- Constructor
- Destructor
- Facet ID
- Public Member Functions
- Protected Member Functions
- Example
- See Also
- Standards Conformance

### Local Index

#### Members

char_type do_put() | id iter_type | put() time_put() | ~time_put()

### Summary

A time formatting facet for output

### Synopsis

    #include <locale>

    namespace std {
      template <class charT, class OutputIterator =
                  ostreambuf_iterator<charT> >
      class time_put;
    }

### Specializations

    template <> class time_put<char>;
    template <> class time_put<wchar_t>;

### Description

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.

### Interface

    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;
      };
    }

### Member Types

    char_type

The type of the first template argument.

    iter_type

The type of the second template argument.

### Constructor

    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.

### Destructor

    virtual ~time_put();

Destroys the facet.

### Facet ID

    static locale::id id;

Unique identifier for this type of facet.

### Public Member Functions

    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)`.

### Protected Member Functions

    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).

#### Table 36: Recognized formatting characters. Struct tm members used to produce the format are noted [in brackets].

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`

1. This format is an extension to the IEEE Std 1003.1 standard provided by this implementation.

Table 37 illustrates the recgonized modified formatting characters and their corresponding meaning.

#### Table 37: Recognized modified formatting characters .

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``"`.

### Example

    //
    //  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"

### See Also

locale, Facets, time_get

### Standards Conformance

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