ptime.h

Go to the documentation of this file.

/*
 * ptime.h
 *
 * Time and date class.
 *
 * Portable Windows Library
 *
 * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Portable Windows Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
 * All Rights Reserved.
 *
 * Contributor(s): ______________________________________.
 *
 * $Log: ptime.h,v $
 * Revision 1.35  2005/11/25 03:43:47  csoutheren
 * Fixed function argument comments to be compatible with Doxygen
 *
 * Revision 1.34  2003/09/17 05:41:59  csoutheren
 * Removed recursive includes
 *
 * Revision 1.33  2003/09/17 01:18:02  csoutheren
 * Removed recursive include file system and removed all references
 * to deprecated coooperative threading support
 *
 * Revision 1.32  2002/12/10 04:45:14  robertj
 * Added support in PTime for ISO 8601 format.
 *
 * Revision 1.31  2002/10/29 00:07:03  robertj
 * Added IsValid() function to indicate that a PTime is set correctly.
 *
 * Revision 1.30  2002/09/16 01:08:59  robertj
 * Added #define so can select if #pragma interface/implementation is used on
 *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
 *
 * Revision 1.29  2001/05/22 12:49:32  robertj
 * Did some seriously wierd rewrite of platform headers to eliminate the
 *   stupid GNU compiler warning about braces not matching.
 *
 * Revision 1.28  2000/04/29 08:14:52  robertj
 * Added some documentation on string formats that can be parsed into a time.
 *
 * Revision 1.27  2000/04/29 04:49:00  robertj
 * Added microseconds to string output.
 *
 * Revision 1.26  2000/04/05 02:50:16  robertj
 * Added microseconds to PTime class.
 *
 * Revision 1.25  1999/03/09 02:59:50  robertj
 * Changed comments to doc++ compatible documentation.
 *
 * Revision 1.24  1999/02/16 08:11:10  robertj
 * MSVC 6.0 compatibility changes.
 *
 * Revision 1.23  1998/09/23 06:21:15  robertj
 * Added open source copyright license.
 *
 * Revision 1.22  1998/01/04 08:04:27  robertj
 * Changed gmtime and locatime to use operating system specific functions.
 *
 * Revision 1.21  1997/01/12 04:21:40  robertj
 * Added IsPast() and IsFuture() functions for time comparison.
 *
 * Revision 1.20  1996/05/09 12:16:06  robertj
 * Fixed syntax error found by Mac platform.
 *
 * Revision 1.19  1996/02/15 14:47:34  robertj
 * Fixed bugs in time zone compensation (some in the C library).
 *
 * Revision 1.18  1996/02/13 12:58:43  robertj
 * Changed GetTimeZone() so can specify standard/daylight time.
 *
 * Revision 1.17  1996/02/08 12:13:03  robertj
 * Changed zone parameter in PTime to indicate the time zone as minutes not enum.
 * Staticised some functions that are system global.
 *
 * Revision 1.16  1996/02/03 11:04:52  robertj
 * Added string constructor for times, parses date/time from string.
 *
 * Revision 1.15  1996/01/03 11:09:34  robertj
 * Added Universal Time and Time Zones to PTime class.
 *
 * Revision 1.14  1995/06/17 11:13:10  robertj
 * Documentation update.
 *
 * Revision 1.13  1995/03/14 12:42:18  robertj
 * Updated documentation to use HTML codes.
 *
 * Revision 1.12  1995/01/11  09:45:12  robertj
 * Documentation and normalisation.
 *
 * Revision 1.11  1995/01/09  12:34:05  robertj
 * Removed unnecesary return value from I/O functions.
 *
 * Revision 1.10  1994/08/23  11:32:52  robertj
 * Oops
 *
 * Revision 1.9  1994/08/22  00:46:48  robertj
 * Added pragma fro GNU C++ compiler.
 *
 * Revision 1.8  1994/07/27  05:58:07  robertj
 * Synchronisation.
 *
 * Revision 1.7  1994/06/25  11:55:15  robertj
 * Unix version synchronisation.
 *
 * Revision 1.6  1994/01/13  03:16:09  robertj
 * Added function to return time as a string.
 *
 * Revision 1.5  1994/01/03  04:42:23  robertj
 * Mass changes to common container classes and interactors etc etc etc.
 *
 * Revision 1.4  1993/12/31  06:45:38  robertj
 * Made inlines optional for debugging purposes.
 *
 * Revision 1.3  1993/08/27  18:17:47  robertj
 * Made time functions common to all platforms.
 * Moved timer resolution function to PTimeInterval wher it belongs.
 *
 * Revision 1.2  1993/07/14  12:49:16  robertj
 * Fixed RCS keywords.
 *
 */

#ifndef _PTIME
#define _PTIME

#ifdef P_USE_PRAGMA
#pragma interface
#endif


#include <time.h>


// System time and date class

class PTimeInterval;


class PTime : public PObject
{
  PCLASSINFO(PTime, PObject);

  public:
    enum {
      UTC   = 0,
      GMT   = UTC,
      Local = 9999
    };

    PTime();

    PTime(
      time_t tsecs,          
      long usecs = 0
    ) { theTime = tsecs; microseconds = usecs; }

    PTime(
      const PString & str   
    );

    PTime(
      int second,           
      int minute,           
      int hour,             
      int day,              
      int month,            
      int year,             
      int tz = Local        
    );

    PObject * Clone() const;

    virtual Comparison Compare(
      const PObject & obj   
    ) const;

    virtual void PrintOn(
      ostream & strm    
    ) const;

    virtual void ReadFrom(
      istream & strm    
    );

    BOOL IsValid() const;

    PInt64 GetTimestamp() const;

    time_t GetTimeInSeconds() const;

    long GetMicrosecond() const;

    int GetSecond() const;

    int GetMinute() const;

    int GetHour() const;

    int GetDay() const;

    enum Months {
      January = 1,
      February,
      March,
      April,
      May,
      June,
      July,
      August,
      September,
      October,
      November,
      December
    };

    Months GetMonth() const;

    int GetYear() const;

    enum Weekdays {
      Sunday,
      Monday,
      Tuesday,
      Wednesday,
      Thursday,
      Friday,
      Saturday
    };

    Weekdays GetDayOfWeek() const;

    int GetDayOfYear() const;

    BOOL IsPast() const;

    BOOL IsFuture() const;

    static BOOL IsDaylightSavings();

    enum TimeZoneType {
      StandardTime,
      DaylightSavings
    };

    static int GetTimeZone();
    static int GetTimeZone(
       TimeZoneType type  
    );

    static PString GetTimeZoneString(
       TimeZoneType type = StandardTime 
    );

    PTime operator+(
      const PTimeInterval & time   
    ) const;

    PTime & operator+=(
      const PTimeInterval & time   
    );

    PTimeInterval operator-(
      const PTime & time   
    ) const;

    PTime operator-(
      const PTimeInterval & time   
    ) const;

    PTime & operator-=(
      const PTimeInterval & time   
    );


    enum TimeFormat {
      RFC1123,
      ShortISO8601,
      LongISO8601,
      LongDateTime,
      LongDate,
      LongTime,
      MediumDateTime,
      MediumDate,
      ShortDateTime,
      ShortDate,
      ShortTime,
      NumTimeStrings
    };

    PString AsString(
      TimeFormat formatCode = RFC1123,  
      int zone = Local                  
    ) const;

    PString AsString(
      const PString & formatStr, 
      int zone = Local           
    ) const;
    /* Convert the time to a string using the format code or string as a
       formatting template. The special characters in the formatting string
       are:
\begin{description}
       \item[h]         hour without leading zero
       \item[hh]        hour with leading zero
       \item[m]         minute without leading zero
       \item[mm]        minute with leading zero
       \item[s]         second without leading zero
       \item[ss]        second with leading zero
       \item[u]         tenths of second
       \item[uu]        hundedths of second with leading zero
       \item[uuu]       millisecond with leading zeros
       \item[uuuu]      microsecond with leading zeros
       \item[a]         the am/pm string
       \item[w/ww/www]  abbreviated day of week name
       \item[wwww]      full day of week name
       \item[d]         day of month without leading zero
       \item[dd]        day of month with leading zero
       \item[M]         month of year without leading zero
       \item[MM]        month of year with leading zero
       \item[MMM]       month of year as abbreviated text
       \item[MMMM]      month of year as full text
       \item[y/yy]      year without century
       \item[yyy/yyyy]  year with century
       \item[z]         the time zone description
\end{description}

       All other characters are copied to the output string unchanged.
       
       Note if there is an 'a' character in the string, the hour will be in 12
       hour format, otherwise in 24 hour format.
     */
    PString AsString(
      const char * formatPtr,    
      int zone = Local           
    ) const;

    static PString GetTimeSeparator();

    static BOOL GetTimeAMPM();

    static PString GetTimeAM();

    static PString GetTimePM();

    enum NameType {
      FullName,
      Abbreviated
    };

    static PString GetDayName(
      Weekdays dayOfWeek,       
      NameType type = FullName  
    );

    static PString GetDateSeparator();

    static PString GetMonthName(
      Months month,             
      NameType type = FullName  
    );

    enum DateOrder {
      MonthDayYear,   
      DayMonthYear,   
      YearMonthDay    
    };

    static DateOrder GetDateOrder();

    static struct tm * os_localtime(const time_t * clock, struct tm * t);
    static struct tm * os_gmtime(const time_t * clock, struct tm * t);
    /*
      Threadsafe version of localtime library call.
      We could make these calls non-static if we could put the struct tm inside the
      instance. But these calls are usually made with const objects so that's not possible,
      and we would require per-thread storage otherwise. Sigh...
    */

  protected:
    // Member variables
    time_t theTime;
    long   microseconds;


// Include platform dependent part of class
#ifdef _WIN32
#include "msos/ptlib/ptime.h"
#else
#include "unix/ptlib/ptime.h"
#endif
};

#endif

// End Of File ///////////////////////////////////////////////////////////////

---