time_put(3C++)

Standard C++ Library
Copyright 1998, Rogue Wave Software, Inc.

NAME

time_put

- A time formatting facet for output.

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

FORMATMEANINGEXAMPLE
CHARACTER
aAbbreviated weekday nameSun
[from tm::tm_wday]

AFull weekday nameSunday
[from tm::tm_wday]

bAbbreviated month name Feb

BFull month name February

cDate and timeFeb 29
[may use all members]14:34:56 1984

dDay of the month29

HHour of the 24-hour day14

IHour of the 12-hour day02

jDay of the year, from 00160
[from tm::tm_yday]

mMonth of the year, from 0102

MMinutes after the hour34

pAM/PM indicator, if anyAM

SSeconds after the minute56

USunday week of the year,
from 00 [from tm::tm_yday and
tm::tm_wday]

wDay of the week, with 00
for Sunday

WMonday week of the year,
from 00 [from tm::tm_yday and
tm::tm_wday]

xDate [uses tm::tm_ydayFeb 29 1984
in some locales]

XTime14:34:56

yYear of the century,84
from 00 (deprecated)

YYear1984

ZTime zone namePST or PDT
[from tm::tm_isdst]

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;

}

Museum