PTLib  Version 2.10.4
PTime Class Reference

This class defines an absolute time and date. More...

#include <ptime.h>

Inheritance diagram for PTime:
PObject

List of all members.

Public Member Functions

Overrides from class PObject
PObjectClone () const
 Create a copy of the time on the heap.
virtual Comparison Compare (const PObject &obj) const
 Determine the relative rank of the specified times.
virtual void PrintOn (ostream &strm) const
 Output the time to the stream.
virtual void ReadFrom (istream &strm)
 Input the time from the specified stream.
Operations
PTime operator+ (const PTimeInterval &time) const
 Add the interval to the time to yield a new time.
PTimeoperator+= (const PTimeInterval &time)
 Add the interval to the time changing the instance.
PTimeInterval operator- (const PTime &time) const
 Calculate the difference between two times to get a time interval.
PTime operator- (const PTimeInterval &time) const
 Subtract the interval from the time to yield a new time.
PTimeoperator-= (const PTimeInterval &time)
 Subtract the interval from the time changing the instance.

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 }
 Time Zone special codes. More...
 PTime ()
 Create a time object instance.
 PTime (time_t tsecs, long usecs=0)
 Create a time object instance.
 PTime (const PString &str)
 Create a time object instance.
 PTime (int second, int minute, int hour, int day, int month, int year, int tz=Local)
 Create a time object instance.

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
 Determine if the timestamp is valid.
PInt64 GetTimestamp () const
 Get the total microseconds since the epoch.
void SetCurrentTime ()
 Set the the objects time with the current time in the current time zone.
void SetTimestamp (time_t seconds, long usecs=0)
 Set the time in seconds and microseconds.
time_t GetTimeInSeconds () const
 Get the total seconds since the epoch.
long GetMicrosecond () const
 Get the microsecond part of the time.
int GetSecond () const
 Get the second of the time.
int GetMinute () const
 Get the minute of the time.
int GetHour () const
 Get the hour of the time.
int GetDay () const
 Get the day of the month of the date.
Months GetMonth () const
 Get the month of the date.
int GetYear () const
 Get the year of the date.
Weekdays GetDayOfWeek () const
 Get the day of the week of the date.
int GetDayOfYear () const
 Get the day in the year of the date.
PBoolean IsPast () const
 Determine if the time is in the past or in the future.
PBoolean IsFuture () const
 Determine if the time is in the past or in the future.

Time Zone configuration functions

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

String conversion functions

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

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 ()
 Get the internationalised time separator.
static PBoolean GetTimeAMPM ()
 Get the internationalised time format: AM/PM or 24 hour.
static PString GetTimeAM ()
 Get the internationalised time AM string.
static PString GetTimePM ()
 Get the internationalised time PM string.
static PString GetDayName (Weekdays dayOfWeek, NameType type=FullName)
 Get the internationalised day of week day name (0=Sun etc).
static PString GetDateSeparator ()
 Get the internationalised date separator.
static PString GetMonthName (Months month, NameType type=FullName)
 Get the internationalised month name string (1=Jan etc).
static DateOrder GetDateOrder ()
 Return the internationalised date order.

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. (eg. Wed, 09 Feb 2011 11:25:58 +01:00)

RFC3339 

Another Internet standard format. (eg. 2011-02-09T11:14:41ZZ)

ShortISO8601 

Short form ISO standard format. (eg. 20110209T111108Z)

LongISO8601 

Long form ISO standard format. (eg. 2011-02-09 T 11:13:06 Z)

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.

EpochTime 

Epoch format (e.g. 1234476388.123456)

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 ( ) [inline]

Create a time object instance.

This initialises the time with the current time in the current time zone.

References SetCurrentTime().

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

Create a time object instance.

This initialises the time to the specified time.

Parameters:
tsecsTime in seconds since 00:00:00 1/1/70 UTC
usecsmicroseconds part of time.

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:
strTime 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:
secondSecond from 0 to 59.
minuteMinute from 0 to 59.
hourHour from 0 to 23.
dayDay of month from 1 to 31.
monthMonth from 1 to 12.
yearYear from 1970 to 2038
tzlocal time or UTC

Member Function Documentation

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

Convert the time to a string representation.

Parameters:
formatCodeStandard format for time.
zoneTime zone for the time.
PString PTime::AsString ( const PString formatStr,
int  zone = Local 
) const

Convert the time to a string representation.

Parameters:
formatStrArbitrary format string for time.
zoneTime zone for the time.
PString PTime::AsString ( const char *  formatPtr,
int  zone = Local 
) const
Parameters:
formatPtrArbitrary format C string pointer for time.
zoneTime zone for the time.
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.

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:
objOther 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.
int PTime::GetDay ( ) const

Get the day of the month of the date.

Returns:
integer in range 1..31.
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:
dayOfWeekCode for day of week.
typeFlag for abbreviated or full name.

Get the day of the week of the date.

Returns:
enum for week days with 0=Sun, 1=Mon, ..., 6=Sat.
int PTime::GetDayOfYear ( ) const

Get the day in the year of the date.

Returns:
integer from 1..366.
int PTime::GetHour ( ) const

Get the hour of the time.

Returns:
integer in range 0..23.
long PTime::GetMicrosecond ( ) const

Get the microsecond part of the time.

Returns:
integer in range 0..999999.
int PTime::GetMinute ( ) const

Get the minute of the time.

Returns:
integer in range 0..59.

Get the month of the date.

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

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

Returns:
string for month.
Parameters:
monthCode for month in year.
typeFlag for abbreviated or full name.
int PTime::GetSecond ( ) const

Get the second of the time.

Returns:
integer in range 0..59.
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:
true is 12 hour, false if 24 hour.
time_t PTime::GetTimeInSeconds ( ) const

Get the total seconds since the epoch.

The epoch is the 1st January 1970.

Returns:
seconds.
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.
PInt64 PTime::GetTimestamp ( ) const

Get the total microseconds since the epoch.

The epoch is the 1st January 1970.

Returns:
microseconds.
static int PTime::GetTimeZone ( ) [static]

Get the time zone offset in minutes.

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:
typeDaylight saving or standard time.

Get the text identifier for the local time zone .

Returns:
Time zone identifier string.
Parameters:
typeDaylight saving or standard time.
int PTime::GetYear ( ) const

Get the year of the date.

Returns:
integer in range 1970..2038.
static PBoolean PTime::IsDaylightSavings ( ) [static]

Get flag indicating daylight savings is current.

Returns:
true if daylight savings time is active.

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

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

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

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

Determine if the timestamp is valid.

This will return true 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.

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:
timeTime 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:
timeTime interval to add to 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:
timeTime to subtract from 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:
timeTime interval 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:
timeTime 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]
bool PTime::Parse ( const PString str)

Parse a string representation of time.

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"

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

Output the time to the stream.

This uses the AsString() function with the ShortDateTime parameter.

Parameters:
strmStream to output the time to.

Reimplemented from PObject.

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:
strmStream to input the time from.

Reimplemented from PObject.

Set the the objects time with the current time in the current time zone.

Referenced by PTime().

void PTime::SetTimestamp ( time_t  seconds,
long  usecs = 0 
)

Set the time in seconds and microseconds.


Member Data Documentation

long PTime::microseconds [protected]

Referenced by PTime().

time_t PTime::theTime [protected]

Number of seconds since 1 January 1970.

Referenced by PTime().


The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines