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

 NAME

   time_put - Time formatting facet for ouput.

 SYNOPSIS

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

 DESCRIPTION

   The time_put facet provides facilities for formated output of
   date/time values.  The member function of time_put take	a
   date/time in the form	of a struct tm and	translate this into
   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 AND DESTRUCTORS

   explicit time_put(size_t refs	= 0)

      Construct 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 had, if refs  is 1	then
      the object	must be	explicitly deleted; the locale will not do
      so.  In	this case, the object can be maintained across the
      lifetime of multiple locales.

   ~time_put();	// virtual and protected

      Destroy 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 use by the strftime
      function and	apply in exactly the same way.	The resulting
      string is	written	out to the buffer pointed to by	the iterator
      s.	 See the Table 1 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.

   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 do_put	function.

 PROTECTED MEMBER FUNCTIONS

   virtual iter_type
   do_put(iter_type s, ios_base&,
 	char_type fill,	const tm* t,
 	char format, char modifier) const;

      Writes out	a character string representation of the Date/Time
      contained in	t.  The	string is formatted according the the
      specifier	format and modifier modifier.	 These values are
      interpreted in exactly the same way that the strftime function
      intrprets its format and modifier flags.  See the Table 1 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

 STANDARDS CONFORMANCE
   ANSI X3J16/ISO WG21 Joint C++	Committee