PTime Class Reference

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

`#include <ptime.h>`

Inheritance diagram for PTime:

## Public Member Functions

Overrides from class PObject
PObject * | Clone () const
| Create a copy of the time on the heap. More...
virtual Comparison | Compare (const PObject &obj) const
| Determine the relative rank of the specified times. More...
virtual void | PrintOn (ostream &strm) const
| Output the time to the stream. More...
virtual void | ReadFrom (istream &strm)
| Input the time from the specified stream. More...
Operations
PTime | operator+ (const PTimeInterval &time) const
| Add the interval to the time to yield a new time. More...
PTime & | operator+= (const PTimeInterval &time)
| Add the interval to the time changing the instance. More...
PTimeInterval | operator- (const PTime &time) const
| Calculate the difference between two times to get a time interval. More...
PTime | operator- (const PTimeInterval &time) const
| Subtract the interval from the time to yield a new time. More...
PTime & | operator-= (const PTimeInterval &time)
| Subtract the interval from the time changing the instance. More...
Public Member Functions inherited from PObject
virtual | ~PObject ()
virtual PINDEX | HashFunction () const
| This function yields a hash value required by the `PDictionary` class. More...
virtual const char * | GetClass (unsigned ancestor=0) const
| Get the current dynamic type of the object instance. More...
PBoolean | IsClass (const char *cls) const
virtual PBoolean | InternalIsDescendant (const char *clsName) const
| Determine if the dynamic type of the current instance is a descendent of the specified class. More...
virtual Comparison | CompareObjectMemoryDirect (const PObject &obj) const
| Determine the byte wise comparison of two objects. More...
bool | operator== (const PObject &obj) const
| Compare the two objects. More...
bool | operator!= (const PObject &obj) const
| Compare the two objects. More...
bool | operator< (const PObject &obj) const
| Compare the two objects. More...
bool | operator> (const PObject &obj) const
| Compare the two objects. More...
bool | operator<= (const PObject &obj) const
| Compare the two objects. More...
bool | operator>= (const PObject &obj) const
| Compare the two objects. More...

## 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)
Static Public Member Functions inherited from PObject
static const char * | Class ()
| Get the name of the class as a C string. More...
static Comparison | InternalCompareObjectMemoryDirect (const PObject *obj1, const PObject *obj2, PINDEX size)
| Internal function caled from CompareObjectMemoryDirect() More...

## Protected Attributes

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

## Construction

enum | { UTC = 0, GMT = UTC, Local = 9999 }
| Time Zone special codes. More...
| PTime ()
| Create a time object instance. More...
| PTime (time_t tsecs, long usecs=0)
| Create a time object instance. More...
| PTime (const PString &str)
| Create a time object instance. More...
| PTime (int second, int minute, int hour, int day, int month, int year, int tz=Local)
| Create a time object instance. More...

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

## 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. More...
static int | GetTimeZone ()
| Get the time zone offset in minutes. More...
static int | GetTimeZone (TimeZoneType type)
| Get the time zone offset in minutes. More...
static PString | GetTimeZoneString (TimeZoneType type=StandardTime)
| Get the text identifier for the local time zone . More...

## 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. More...
PString | AsString (const PString &formatStr, int zone=Local) const
| Convert the time to a string representation. More...
PString | AsString (const char *formatPtr, int zone=Local) const
bool | Parse (const PString &str)
| Parse a string representation of time. More...

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

## Additional Inherited Members

Public Types inherited from PObject
enum | Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 }
| Result of the comparison operation performed by the `Compare()` function. More...
Protected Member Functions inherited from PObject
| PObject ()
| Constructor for PObject, made protected so cannot ever create one on its own. More...

## 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

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.

## DateOrder

enum PTime::DateOrder

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.

## Months

enum PTime::Months

Month codes.

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

## NameType

enum PTime::NameType

Flag for returning language dependent string names.

Enumerator
FullName |
Abbreviated |

## TimeFormat

enum PTime::TimeFormat

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 |

## TimeZoneType

enum PTime::TimeZoneType

Flag for time zone adjustment on daylight savings.

Enumerator
StandardTime |
DaylightSavings |

## Weekdays

enum PTime::Weekdays

Days of the week.

Enumerator
Sunday |
Monday |
Tuesday |
Wednesday |
Thursday |
Friday |
Saturday |

## Constructor & Destructor Documentation

## PTime() [1/4]

PTime::PTime | ( |  | ) |

inline

Create a time object instance.

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

References SetCurrentTime().

Referenced by PTime().

## PTime() [2/4]

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
  usecs | microseconds part of time.

References Clone(), Compare(), GetDay(), GetHour(), GetMicrosecond(), GetMinute(), GetSecond(), GetTimeInSeconds(), GetTimestamp(), IsValid(), Local, microseconds, PrintOn(), PTime(), ReadFrom(), SetCurrentTime(), SetTimestamp(), and theTime.

## PTime() [3/4]

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

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

## AsString() [1/3]

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.

## AsString() [2/3]

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.

## AsString() [3/3]

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.

## Clone()

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.

Referenced by PTime().

## Compare()

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.

Referenced by PTime().

## GetDateOrder()

static DateOrder PTime::GetDateOrder | ( |  | ) |

static

Return the internationalised date order.

Returns
  code for date ordering.

## GetDateSeparator()

static PString PTime::GetDateSeparator | ( |  | ) |

static

Get the internationalised date separator.

Returns
  string for date separator.

## GetDay()

int PTime::GetDay | ( |  | ) | const

Get the day of the month of the date.

Returns
  integer in range 1..31.

Referenced by PTime().

## GetDayName()

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.

## GetDayOfWeek()

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.

## GetDayOfYear()

int PTime::GetDayOfYear | ( |  | ) | const

Get the day in the year of the date.

Returns
  integer from 1..366.

## GetHour()

int PTime::GetHour | ( |  | ) | const

Get the hour of the time.

Returns
  integer in range 0..23.

Referenced by PTime().

## GetMicrosecond()

long PTime::GetMicrosecond | ( |  | ) | const

Get the microsecond part of the time.

Returns
  integer in range 0..999999.

Referenced by PTime().

## GetMinute()

int PTime::GetMinute | ( |  | ) | const

Get the minute of the time.

Returns
  integer in range 0..59.

Referenced by PTime().

## GetMonth()

Months PTime::GetMonth | ( |  | ) | const

Get the month of the date.

Returns
  enum for month.

## GetMonthName()

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.

## GetSecond()

int PTime::GetSecond | ( |  | ) | const

Get the second of the time.

Returns
  integer in range 0..59.

Referenced by PTime().

## GetTimeAM()

static PString PTime::GetTimeAM | ( |  | ) |

static

Get the internationalised time AM string.

Returns
  string for AM.

## GetTimeAMPM()

static PBoolean PTime::GetTimeAMPM | ( |  | ) |

static

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

Returns
  true is 12 hour, false if 24 hour.

## GetTimeInSeconds()

time_t PTime::GetTimeInSeconds | ( |  | ) | const

Get the total seconds since the epoch.

The epoch is the 1st January 1970.

Returns
  seconds.

Referenced by PTime().

## GetTimePM()

static PString PTime::GetTimePM | ( |  | ) |

static

Get the internationalised time PM string.

Returns
  string for PM.

## GetTimeSeparator()

static PString PTime::GetTimeSeparator | ( |  | ) |

static

Get the internationalised time separator.

Returns
  string for time separator.

## GetTimestamp()

PInt64 PTime::GetTimestamp | ( |  | ) | const

Get the total microseconds since the epoch.

The epoch is the 1st January 1970.

Returns
  microseconds.

Referenced by PTime().

## GetTimeZone() [1/2]

static int PTime::GetTimeZone | ( |  | ) |

static

Get the time zone offset in minutes.

## GetTimeZone() [2/2]

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.

## GetTimeZoneString()

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.

## GetYear()

int PTime::GetYear | ( |  | ) | const

Get the year of the date.

Returns
  integer in range 1970..2038.

## IsDaylightSavings()

static PBoolean PTime::IsDaylightSavings | ( |  | ) |

static

Get flag indicating daylight savings is current.

Returns
  true if daylight savings time is active.

## IsFuture()

PBoolean PTime::IsFuture | ( |  | ) | const

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

Returns
  true if time is after the current real time.

## IsPast()

PBoolean PTime::IsPast | ( |  | ) | const

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

Returns
  true if time is before the current real time.

## IsValid()

PBoolean PTime::IsValid | ( |  | ) | const

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.

Referenced by PTime().

## operator+()

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.

## operator+=()

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.

## operator-() [1/2]

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.

## operator-() [2/2]

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.

## operator-=()

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.

## os_gmtime()

static struct tm* PTime::os_gmtime | ( | const time_t * | clock,
|  | struct tm * | t
| ) |  |

static

## os_localtime()

static struct tm* PTime::os_localtime | ( | const time_t * | clock,
|  | struct tm * | t
| ) |  |

static

## Parse()

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"

## PrintOn()

virtual 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.

Referenced by PTime().

## ReadFrom()

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.

Referenced by PTime().

## SetCurrentTime()

void PTime::SetCurrentTime | ( |  | ) |

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

Referenced by PTime().

## SetTimestamp()

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

Set the time in seconds and microseconds.

Referenced by PTime().

## Member Data Documentation

## microseconds

long PTime::microseconds

protected

Referenced by PTime().

## theTime

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:

- ptime.h