Standard C++ LibraryCopyright 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



privacy and legal statement