## time_put

            time_put_base
    time_put
            locale::facet

- Summary
- Data Type and Member Function Indexes
- Synopsis
- Description
- Interface
- Types
- Constructors
- Destructors
- Facet ID
- Public Member Functions
- Protected Member Functions
- Example
- See Also

### Summary

A time formatting facet for output.

### Data Type and Member Function Indexes
(exclusive of constructors and destructors)

Data Types
char_type id iter_type

Member Functions
do_put() put()

### Synopsis

    #include <locale>
    template <class charT, class OutputIterator =
              ostreambuf_iterator<charT> >
    class time_put;

### Description

The time_put facet includes facilities for formatted output of date/time values. The member function of time_put takes a date/time in the form of a struct `tm` and translates this into a character string representation.

### Interface

    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:
      ~time_put();  // virtual
      virtual iter_type do_put(iter_type, ios_base&,
                               char_type, const tm*,
                               char, char) const;
    };

### Types

    char_type

Type of character the facet is instantiated on.

    iter_type

Type of iterator used to scan the character buffer.

### Constructors

    explicit time_put(size_t refs = 0);

Constructs a time_put facet. If the `refs` argument is `0`, then destruction of the object is delegated to the locale, or locales, containing it. This allows the user to ignore lifetime management issues. On the other hand, if `refs` is `1`, then the object must be explicitly deleted; the locale does not do so. In this case, the object can be maintained across the lifetime of multiple locales.

### Destructors

    ~time_put();  // virtual and protected

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 charT* pattern, const charT* pat_end) const;

Creates a character string representing the Date/Time contained in `tmb`. The format of the string is determined by a sequence of format modifiers contained in the range `[pattern,pat_end)`. These modifiers are from the same set as those used by the `strftime` function and are applied in exactly the same way. The resulting string is written out to the buffer pointed to by the iterator `s`. See the table below for a description of `strftime` formatting characters.

The `fill` argument is used for any padding.

Returns an iterator pointing one past the last character written.

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

Calls the protected virtual `do_put` function.

Writes out a character string representation of the Date/Time contained in `t`. The string is formatted according the specifier `format` and modifier `modifier`. These values are interpreted in exactly the same way as the `strftime` function interprets its format and modifier flags. See the table below for a description of `strftime` formatting characters.

The `fill` argument is used for any padding.

Returns an iterator pointing one past the last character written.

#### Table 1 -- Formatting characters used by strftime() . For those formats that do not use all members of the struct tm, only those members that are actually used are noted [in brackets].

Format character | Meaning | Example
--- | --- | ---
`a` | `Abbreviated weekday name [from tm::tm_wday]` | `Sun`
`A` | `Full weekday name [from tm::tm_wday]` | `Sunday`
`b` | `Abbreviated month name` | `Feb`
`B` | `Full month name` | `February`
`c` | `Date and time [may use all members]` | `Feb 29 14:34:56 1984`
`d` | `Day of the month` | `29`
`H` | `Hour of the 24-hour day` | `14`
`I` | `Hour of the 12-hour day` | `02`
`j` | `Day of the year, from 001 [from tm::tm_yday]` | `60`
`m` | `Month of the year, from 01` | `02`
`M` | `Minutes after the hour` | `34`
`p` | `AM/PM indicator, if any` | `AM`
`S` | `Seconds after the minute` | `56`
`U` | `Sunday week of the year, from 00 [from tm::tm_yday and tm::tm_wday]` | ``
`w` | `Day of the week, with 0 for Sunday` | `0`
`W` | `Monday week of the year, from 00 [from tm::tm_yday and tm::tm_wday]` | ``
`x` | `Date [uses tm::tm_yday in some locales]` | `Feb 29 1984`
`X` | `Time` | `14:34:56`
`y` | `Year of the century, from 00 (deprecated)` | `84`
`Y` | `Year` | `1984`
`Z` | `Time zone name [from tm::tm_isdst]` | `PST or PDT`

### Example

    //
    // timeput.cpp
    //
    #include <iostream>

    int main ()
    {
      using namespace std;

      typedef ostreambuf_iterator<char,char_traits<char> >
              iter_type;

      locale loc;
      time_t tm = time(NULL);
      struct tm* tmb = localtime(&tm);
      struct tm timeb;
      memcpy(&timeb,tmb,sizeof(struct tm));
      char pat[] = "%c";

      // Get a time_put facet
      const time_put<char,iter_type>& tp =
    #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
      use_facet<time_put<char,iter_type> >(loc);
    #else
      use_facet(loc,(time_put<char,iter_type>*)0);
    #endif

      // Construct a ostreambuf_iterator on cout
      iter_type begin(cout);

      cout << " --> ";
      tp.put(begin,cout,' ',&timeb,pat,pat+2);

      cout << endl << " --> ";
      tp.put(begin,cout,' ',&timeb,'c',' ');

      cout <<  endl;

      return 0;
    }

### See Also

locale, facets, time_get

Copyright (c) 1998, Rogue Wave Software, Inc.
Send mail to report errors or comment on the documentation.
OEM Release, June 1998