PTime Class Reference

#include <ptime.h>

Inheritance diagram for PTime:

PObject

List of all members.

Public Member Functions

Overrides from class PObject
PObjectClone () const
virtual Comparison Compare (const PObject &obj) const
virtual void PrintOn (ostream &strm) const
virtual void ReadFrom (istream &strm)
Operations
PTime operator+ (const PTimeInterval &time) const
PTimeoperator+= (const PTimeInterval &time)
PTimeInterval operator- (const PTime &time) const
PTime operator- (const PTimeInterval &time) const
PTimeoperator-= (const PTimeInterval &time)

Static Public Member Functions

static struct tm * os_localtime (const time_t *clock, struct tm *t)
static struct tm * os_gmtime (const time_t *clock, struct tm *t)

Protected Attributes

time_t theTime
 Number of seconds since 1 January 1970.
long microseconds

Construction

enum  { UTC = 0, GMT = UTC, Local = 9999 }
 PTime ()
 PTime (time_t tsecs, long usecs=0)
 PTime (const PString &str)
 PTime (int second, int minute, int hour, int day, int month, int year, int tz=Local)

Access functions

enum  Months {
  January = 1, February, March, April,
  May, June, July, August,
  September, October, November, December
}
 Month codes. More...
enum  Weekdays {
  Sunday, Monday, Tuesday, Wednesday,
  Thursday, Friday, Saturday
}
 Days of the week. More...
PBoolean IsValid () const
PInt64 GetTimestamp () const
time_t GetTimeInSeconds () const
long GetMicrosecond () const
int GetSecond () const
int GetMinute () const
int GetHour () const
int GetDay () const
Months GetMonth () const
int GetYear () const
Weekdays GetDayOfWeek () const
int GetDayOfYear () const
PBoolean IsPast () const
PBoolean IsFuture () const

Time Zone configuration functions

enum  TimeZoneType { StandardTime, DaylightSavings }
 Flag for time zone adjustment on daylight savings. More...
static PBoolean IsDaylightSavings ()
static int GetTimeZone ()
 Get the time zone offset in minutes.
static int GetTimeZone (TimeZoneType type)
static PString GetTimeZoneString (TimeZoneType type=StandardTime)

String conversion functions

enum  TimeFormat {
  RFC1123, ShortISO8601, LongISO8601, LongDateTime,
  LongDate, LongTime, MediumDateTime, MediumDate,
  ShortDateTime, ShortDate, ShortTime, NumTimeStrings
}
 Standard time formats for string representations of a time and date. More...
PString AsString (TimeFormat formatCode=RFC1123, int zone=Local) const
PString AsString (const PString &formatStr, int zone=Local) const
PString AsString (const char *formatPtr, int zone=Local) const

Internationalisation functions

enum  NameType { FullName, Abbreviated }
 Flag for returning language dependent string names. More...
enum  DateOrder { MonthDayYear, DayMonthYear, YearMonthDay }
 Possible orders for date components. More...
static PString GetTimeSeparator ()
static PBoolean GetTimeAMPM ()
static PString GetTimeAM ()
static PString GetTimePM ()
static PString GetDayName (Weekdays dayOfWeek, NameType type=FullName)
static PString GetDateSeparator ()
static PString GetMonthName (Months month, NameType type=FullName)
static DateOrder GetDateOrder ()


Detailed Description

This class defines an absolute time and date. It has a number of time and date rendering and manipulation functions. It is based on the standard C library functions for time. Thus it is based on a number of seconds since 1 January 1970.

Member Enumeration Documentation

anonymous enum

Time Zone special codes. The value for a time zone is usually in minutes from UTC, this enum are special values for specific areas.

Enumerator:
UTC  Universal Coordinated Time.
GMT  Greenwich Mean Time, effectively UTC.
Local  Local Time.

Possible orders for date components.

Enumerator:
MonthDayYear  Date is ordered month then day then year.
DayMonthYear  Date is ordered day then month then year.
YearMonthDay  Date is ordered year then day month then day.

Month codes.

Enumerator:
January 
February 
March 
April 
May 
June 
July 
August 
September 
October 
November 
December 

Flag for returning language dependent string names.

Enumerator:
FullName 
Abbreviated 

Standard time formats for string representations of a time and date.

Enumerator:
RFC1123  Internet standard format.
ShortISO8601  Short form ISO standard format.
LongISO8601  Long form ISO standard format.
LongDateTime  Date with weekday, full month names and time with seconds.
LongDate  Date with weekday, full month names and no time.
LongTime  Time with seconds.
MediumDateTime  Date with abbreviated month names and time without seconds.
MediumDate  Date with abbreviated month names and no time.
ShortDateTime  Date with numeric month name and time without seconds.
ShortDate  Date with numeric month and no time.
ShortTime  Time without seconds.
NumTimeStrings 

Flag for time zone adjustment on daylight savings.

Enumerator:
StandardTime 
DaylightSavings 

Days of the week.

Enumerator:
Sunday 
Monday 
Tuesday 
Wednesday 
Thursday 
Friday 
Saturday 


Constructor & Destructor Documentation

PTime::PTime (  ) 

Create a time object instance. This initialises the time with the current time in the current time zone.

Referenced by Clone().

PTime::PTime ( time_t  tsecs,
long  usecs = 0 
) [inline]

Create a time object instance. This initialises the time to the specified time.

Parameters:
tsecs Time in seconds since 00:00:00 1/1/70 UTC

References microseconds, and theTime.

PTime::PTime ( const PString str  ) 

Create a time object instance. This initialises the time to the specified time, parsed from the string. The string may be in many different formats, for example: "5/03/1999 12:34:56" "15/06/1999 12:34:56" "15/06/01 12:34:56 PST" "5/06/02 12:34:56" "5/23/1999 12:34am" "5/23/00 12:34am" "1999/23/04 12:34:56" "Mar 3, 1999 12:34pm" "3 Jul 2004 12:34pm" "12:34:56 5 December 1999" "10 minutes ago" "2 weeks"

Parameters:
str Time and data as a string

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

Create a time object instance. This initialises the time to the specified time.

Parameters:
second Second from 0 to 59.
minute Minute from 0 to 59.
hour Hour from 0 to 23.
day Day of month from 1 to 31.
month Month from 1 to 12.
year Year from 1970 to 2038
tz local time or UTC


Member Function Documentation

PString PTime::AsString ( const char *  formatPtr,
int  zone = Local 
) const

Parameters:
formatPtr Arbitrary format C string pointer for time.
zone Time zone for the time.

PINLINE PString PTime::AsString ( const PString formatStr,
int  zone = Local 
) const

Convert the time to a string representation.

Parameters:
formatStr Arbitrary format string for time.
zone Time zone for the time.

References AsString().

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

Convert the time to a string representation.

Parameters:
formatCode Standard format for time.
zone Time zone for the time.

Referenced by AsString(), and PrintOn().

PINLINE PObject * PTime::Clone (  )  const [virtual]

Create a copy of the time on the heap. It is the responsibility of the caller to delete the created object.

Returns:
pointer to new time.

Reimplemented from PObject.

References microseconds, PNEW, PTime(), and theTime.

virtual Comparison PTime::Compare ( const PObject obj  )  const [virtual]

Determine the relative rank of the specified times. This ranks the times as you would expect.

Returns:
rank of the two times.
Parameters:
obj Other time to compare against.

Reimplemented from PObject.

static DateOrder PTime::GetDateOrder (  )  [static]

Return the internationalised date order.

Returns:
code for date ordering.

static PString PTime::GetDateSeparator (  )  [static]

Get the internationalised date separator.

Returns:
string for date separator.

PINLINE int PTime::GetDay (  )  const

Get the day of the month of the date.

Returns:
integer in range 1..31.

References os_localtime(), and theTime.

static PString PTime::GetDayName ( Weekdays  dayOfWeek,
NameType  type = FullName 
) [static]

Get the internationalised day of week day name (0=Sun etc).

Returns:
string for week day.
Parameters:
dayOfWeek Code for day of week.
type Flag for abbreviated or full name.

PINLINE PTime::Weekdays PTime::GetDayOfWeek (  )  const

Get the day of the week of the date.

Returns:
enum for week days with 0=Sun, 1=Mon, ..., 6=Sat.

References os_localtime(), and theTime.

PINLINE int PTime::GetDayOfYear (  )  const

Get the day in the year of the date.

Returns:
integer from 1..366.

References os_localtime(), and theTime.

PINLINE int PTime::GetHour (  )  const

Get the hour of the time.

Returns:
integer in range 0..23.

References os_localtime(), and theTime.

PINLINE long PTime::GetMicrosecond (  )  const

Get the microsecond part of the time.

Returns:
integer in range 0..999999.

References microseconds.

PINLINE int PTime::GetMinute (  )  const

Get the minute of the time.

Returns:
integer in range 0..59.

References os_localtime(), and theTime.

PINLINE PTime::Months PTime::GetMonth (  )  const

Get the month of the date.

Returns:
enum for month.

References January, os_localtime(), and theTime.

static PString PTime::GetMonthName ( Months  month,
NameType  type = FullName 
) [static]

Get the internationalised month name string (1=Jan etc).

Returns:
string for month.
Parameters:
month Code for month in year.
type Flag for abbreviated or full name.

PINLINE int PTime::GetSecond (  )  const

Get the second of the time.

Returns:
integer in range 0..59.

References os_localtime(), and theTime.

static PString PTime::GetTimeAM (  )  [static]

Get the internationalised time AM string.

Returns:
string for AM.

static PBoolean PTime::GetTimeAMPM (  )  [static]

Get the internationalised time format: AM/PM or 24 hour.

Returns:
PTrue is 12 hour, PFalse if 24 hour.

PINLINE time_t PTime::GetTimeInSeconds (  )  const

Get the total seconds since the epoch. The epoch is the 1st January 1970.

Returns:
seconds.

References theTime.

static PString PTime::GetTimePM (  )  [static]

Get the internationalised time PM string.

Returns:
string for PM.

static PString PTime::GetTimeSeparator (  )  [static]

Get the internationalised time separator.

Returns:
string for time separator.

PINLINE PInt64 PTime::GetTimestamp (  )  const

Get the total microseconds since the epoch. The epoch is the 1st January 1970.

Returns:
microseconds.

References microseconds, and theTime.

static int PTime::GetTimeZone ( TimeZoneType  type  )  [static]

Get the time zone offset in minutes. This is the number of minutes to add to UTC (previously known as GMT) to get the local time. The first form automatically adjusts for daylight savings time, whilst the second form returns the specified time.

Returns:
Number of minutes.
Parameters:
type Daylight saving or standard time.

PINLINE int PTime::GetTimeZone (  )  [static]

Get the time zone offset in minutes.

References DaylightSavings, IsDaylightSavings(), and StandardTime.

static PString PTime::GetTimeZoneString ( TimeZoneType  type = StandardTime  )  [static]

Get the text identifier for the local time zone .

Returns:
Time zone identifier string.
Parameters:
type Daylight saving or standard time.

PINLINE int PTime::GetYear (  )  const

Get the year of the date.

Returns:
integer in range 1970..2038.

References os_localtime(), and theTime.

static PBoolean PTime::IsDaylightSavings (  )  [static]

Get flag indicating daylight savings is current.

Returns:
PTrue if daylight savings time is active.

Referenced by GetTimeZone().

PINLINE PBoolean PTime::IsFuture (  )  const

Determine if the time is in the past or in the future.

Returns:
PTrue if time is after the current real time.

References theTime.

PINLINE PBoolean PTime::IsPast (  )  const

Determine if the time is in the past or in the future.

Returns:
PTrue if time is before the current real time.

References theTime.

PINLINE PBoolean PTime::IsValid (  )  const

Determine if the timestamp is valid. This will return PTrue if the timestamp can be represented as a time in the epoch. The epoch is the 1st January 1970.

In practice this means the time is > 13 hours to allow for time zones.

References theTime.

PTime PTime::operator+ ( const PTimeInterval time  )  const

Add the interval to the time to yield a new time.

Returns:
Time altered by the interval.
Parameters:
time Time interval to add to the time.

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

Add the interval to the time changing the instance.

Returns:
reference to the current time instance.
Parameters:
time Time interval to add to the time.

PTime PTime::operator- ( const PTimeInterval time  )  const

Subtract the interval from the time to yield a new time.

Returns:
Time altered by the interval.
Parameters:
time Time interval to subtract from the time.

PTimeInterval PTime::operator- ( const PTime time  )  const

Calculate the difference between two times to get a time interval.

Returns:
Time intervale difference between the times.
Parameters:
time Time to subtract from the time.

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

Subtract the interval from the time changing the instance.

Returns:
reference to the current time instance.
Parameters:
time Time interval to subtract from the time.

static struct tm* PTime::os_gmtime ( const time_t *  clock,
struct tm *  t 
) [static, read]

static struct tm* PTime::os_localtime ( const time_t *  clock,
struct tm *  t 
) [static, read]

PINLINE void PTime::PrintOn ( ostream &  strm  )  const [virtual]

Output the time to the stream. This uses the AsString()# function with the ShortDateTime# parameter.

Parameters:
strm Stream to output the time to.

Reimplemented from PObject.

References AsString().

virtual void PTime::ReadFrom ( istream &  strm  )  [virtual]

Input the time from the specified stream. If a parse error occurs the time is set to the current time. The string may be in many different formats, for example: "5/03/1999 12:34:56" "15/06/1999 12:34:56" "15/06/01 12:34:56 PST" "5/06/02 12:34:56" "5/23/1999 12:34am" "5/23/00 12:34am" "1999/23/04 12:34:56" "Mar 3, 1999 12:34pm" "3 Jul 2004 12:34pm" "12:34:56 5 December 1999" "10 minutes ago" "2 weeks"

Parameters:
strm Stream to input the time from.

Reimplemented from PObject.


Member Data Documentation

long PTime::microseconds [protected]

time_t PTime::theTime [protected]


The documentation for this class was generated from the following files:

Generated on Fri Apr 10 22:33:53 2009 for PTLib by  doxygen 1.5.8