PTime Class Reference

#include <ptime.h>

Inheritance diagram for PTime:

List of all members.

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...
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
Months	GetMonth () const
int	GetYear () const
Weekdays	GetDayOfWeek () const
int	GetDayOfYear () const
BOOL	IsPast () const
BOOL	IsFuture () const
Time Zone configuration functions
enum	TimeZoneType { StandardTime, DaylightSavings }
	Flag for time zone adjustment on daylight savings. More...
static BOOL	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 BOOL	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 ()
Public Member Functions
Overrides from class PObject
PObject *	Clone () 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
PTime &	operator+= (const PTimeInterval &time)
PTimeInterval	operator- (const PTime &time) const
PTime	operator- (const PTimeInterval &time) const
PTime &	operator-= (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

---

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.

enum PTime::Months

Month codes.

Enumerator:

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

enum PTime::Weekdays

Days of the week.

Enumerator:

Sunday
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday

enum PTime::TimeZoneType

Flag for time zone adjustment on daylight savings.

Enumerator:

StandardTime
DaylightSavings

enum PTime::TimeFormat

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

enum PTime::NameType

Flag for returning language dependent string names.

Enumerator:

FullName
Abbreviated

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.

---

Constructor & Destructor Documentation

PTime::PTime

(

)

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

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

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

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.

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.

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.

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.

PINLINE BOOL 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.

PINLINE PInt64 PTime::GetTimestamp

(

)

const

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

Returns:

microseconds.

PINLINE time_t PTime::GetTimeInSeconds

(

)

const

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

Returns:

seconds.

PINLINE long PTime::GetMicrosecond

(

)

const

Get the microsecond part of the time.

Returns:

integer in range 0..999999.

PINLINE int PTime::GetSecond

(

)

const

Get the second of the time.

Returns:

integer in range 0..59.

PINLINE int PTime::GetMinute

(

)

const

Get the minute of the time.

Returns:

integer in range 0..59.

PINLINE int PTime::GetHour

(

)

const

Get the hour of the time.

Returns:

integer in range 0..23.

PINLINE int PTime::GetDay

(

)

const

Get the day of the month of the date.

Returns:

integer in range 1..31.

PINLINE PTime::Months PTime::GetMonth

(

)

const

Get the month of the date.

Returns:

enum for month.

PINLINE int PTime::GetYear

(

)

const

Get the year of the date.

Returns:

integer in range 1970..2038.

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.

PINLINE int PTime::GetDayOfYear

(

)

const

Get the day in the year of the date.

Returns:

integer from 1..366.

PINLINE BOOL 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.

PINLINE BOOL 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.

static BOOL PTime::IsDaylightSavings

(

)

[static]

Get flag indicating daylight savings is current.

Returns:

TRUE if daylight savings time is active.

PINLINE 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:

type	Daylight saving or standard time.

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.

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.

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

)

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.

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.

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.

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.

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.

static PString PTime::GetTimeSeparator

(

)

[static]

Get the internationalised time separator.

Returns:

string for time separator.

static BOOL PTime::GetTimeAMPM

(

)

[static]

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

Returns:

TRUE is 12 hour, FALSE if 24 hour.

static PString PTime::GetTimeAM

(

)

[static]

Get the internationalised time AM string.

Returns:

string for AM.

static PString PTime::GetTimePM

(

)

[static]

Get the internationalised time PM string.

Returns:

string for PM.

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.

static PString PTime::GetDateSeparator

(

)

[static]

Get the internationalised date separator.

Returns:

string for date separator.

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.

static DateOrder PTime::GetDateOrder

(

)

[static]

Return the internationalised date order.

Returns:

code for date ordering.

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

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

---

Member Data Documentation

time_t PTime::theTime [protected]

Number of seconds since 1 January 1970.

long PTime::microseconds [protected]

---

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

• ptime.h
• osutil.inl

---