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): ______________________________________.
 *
 * $Revision: 31150 $
 * $Author: rjongbloed $
 * $Date: 2014-01-08 15:08:30 +1100 (Wed, 08 Jan 2014) $
 */

#ifndef PTLIB_TIME_H
#define PTLIB_TIME_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif


// System time and date class

class PTimeInterval;


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

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

    PTime() { SetCurrentTime(); }

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

    PBoolean IsValid() const;

    PInt64 GetTimestamp() const;

    void SetCurrentTime();

    void SetTimestamp(
      time_t seconds,
      long usecs = 0
    );

    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;

    PTimeInterval GetElapsed() const;

    PBoolean IsPast() const;

    PBoolean IsFuture() const;

    static PBoolean 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,
      RFC3339,
      ShortISO8601,
      LongISO8601,
      LongDateTime,
      LongDate,
      LongTime,
      MediumDateTime,
      MediumDate,
      ShortDateTime,
      ShortDate,
      ShortTime,
      EpochTime,
      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:
       <table border=0>
       <tr><td>h         <td>hour without leading zero
       <tr><td>hh        <td>hour with leading zero
       <tr><td>m         <td>minute without leading zero
       <tr><td>mm        <td>minute with leading zero
       <tr><td>s         <td>second without leading zero
       <tr><td>ss        <td>second with leading zero
       <tr><td>u         <td>tenths of second
       <tr><td>uu        <td>hundedths of second with leading zero
       <tr><td>uuu       <td>millisecond with leading zeros
       <tr><td>uuuu      <td>microsecond with leading zeros
       <tr><td>a         <td>the am/pm string
       <tr><td>w/ww/www  <td>abbreviated day of week name
       <tr><td>wwww      <td>full day of week name
       <tr><td>d         <td>day of month without leading zero
       <tr><td>dd        <td>day of month with leading zero
       <tr><td>M         <td>month of year without leading zero
       <tr><td>MM        <td>month of year with leading zero
       <tr><td>MMM       <td>month of year as abbreviated text
       <tr><td>MMMM      <td>month of year as full text
       <tr><td>y/yy      <td>year without century
       <tr><td>yyy/yyyy  <td>year with century
       <tr><td>z         <td>the time zone description ('GMT' for UTC)
       <tr><td>Z         <td>the time zone description ('Z' for UTC)
       <tr><td>ZZ        <td>the time zone description (':' separates hour/minute)
       </table>

       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.

       @return empty string if time is invalid.
     */
    PString AsString(
      const char * formatPtr,    
      int zone = Local           
    ) const;

    bool Parse(
      const PString & str
    );

    static PString GetTimeSeparator();

    static PBoolean 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 // PTLIB_TIME_H


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