PDateTime Class Reference

Detailed Description

The PDateTime class provides date and time functions, including time-zone management and UTC conversions; PDateTime instances are immutable (thread-safe).

A PDateTime object contains a calendar date (PDate) and a clock time (PTime). It is always stored in UTC.

PDateTime can read the current datetime from the system clock.

It provides functions for comparing datetimes and for manipulating a datetime.

Definition at line 38 of file PDateTime.h.

#include <PDateTime.h>

Member Enumeration Documentation

◆ EDateTimeZone

Constants to specify if a datetime uses a local time zone or UTC.

Enumerator
E_LOCALTIME 

Locale dependent time.

E_UTC 

Coordinated Universal Time.

Definition at line 44 of file PDateTime.h.

Constructor & Destructor Documentation

◆ PDateTime() [1/4]

PDateTime::PDateTime ( )

Constructs an invalid datetime.

See also
IsValid()

◆ PDateTime() [2/4]

PDateTime::PDateTime ( const PDate date,
const PTime time,
EDateTimeZone  timeZone = PDateTime::E_UTC 
)
explicit

Constructs a datetime from a PDate object, a PTime object and a time zone.

The datetime is always stored in UTC. If date is valid and time is not, the time will be set to midnight.

See also
IsValid()

◆ PDateTime() [3/4]

PDateTime::PDateTime ( const PDateTime other)

Constructs a shared copy of other.

◆ PDateTime() [4/4]

PDateTime::PDateTime ( const PString ISOdateTime)
explicit

Constructs a datetime from a string.

Assumes the string is an ISO 8601 extended format: either YYYY-MM-DD for dates or YYYY-MM-DDTHH:MM:SS, YYYY-MM-DDTHH:MM:SSTZD, YYYY-MM-DDTHH:MM:SS.nnnTZD (e.g. 1997-07-16T19:20:30+01:00 or 1997-07-16T19:20:30.123Z) for combined dates and times.

See also
IsValid()

◆ ~PDateTime()

virtual PDateTime::~PDateTime ( )
virtual

Destroys this object.

Member Function Documentation

◆ AddMillisecond()

PDateTime PDateTime::AddMillisecond ( papillon::int64  n) const

Returns a PDateTime object n milliseconds later than the datetime of this object (or earlier if n is negative).

Returns an invalid datetime if the current datetime is invalid or the new datetime is out of range.

◆ Bad()

static const PDateTime& PDateTime::Bad ( )
inlinestatic

Returns the constant holding the bad instance of a PDateTime.

Definition at line 53 of file PDateTime.h.

◆ Compare()

papillon::int32 PDateTime::Compare ( const PDateTime other) const

Compares this datetime with another one, then returns 0 if equal, a negative number if this datetime is earlier than other, a positive number if this datetime is later than other.

◆ Current()

static PDateTime PDateTime::Current ( )
static

Returns the current datetime as reported by the system clock, in the local time zone.

◆ CurrentUTC()

static PDateTime PDateTime::CurrentUTC ( )
static

Returns the current datetime as reported by the system clock, in UTC.

◆ FromMicrosecondsSinceEpoch()

static PDateTime PDateTime::FromMicrosecondsSinceEpoch ( papillon::int64  n)
static

Returns the datetime corresponding to the specified number of microseconds that have passed since 1970-01-01T00:00:00.000 UTC.

◆ FromMillisecondsSinceEpoch()

static PDateTime PDateTime::FromMillisecondsSinceEpoch ( papillon::int64  n)
static

Returns the datetime corresponding to the specified number of milliseconds that have passed since 1970-01-01T00:00:00.000 UTC.

◆ GetDate()

PDate PDateTime::GetDate ( ) const

Returns the date of this datetime.

◆ GetMillisecondsTo()

papillon::int64 PDateTime::GetMillisecondsTo ( const PDateTime d) const

Returns the number of milliseconds from this datetime to d.

If d is earlier than this datetime, the number of milliseconds returned is negative. Returns 0 if either this datetime or d is invalid.

◆ GetOffsetFromUTCInSeconds()

papillon::int32 PDateTime::GetOffsetFromUTCInSeconds ( ) const

Returns the number of seconds to add to this date time (UTC) to obtain the local time.

This includes any daylight time offset that may be in effect. The result can be positive or negative.

◆ GetTime()

PTime PDateTime::GetTime ( ) const

Returns the time of this datetime.

◆ IsValid()

bool PDateTime::IsValid ( ) const

Returns true if this datetime is valid; otherwise returns false.

◆ operator!=()

bool PDateTime::operator!= ( const PDateTime d) const

Returns true if this datetime is different from d; otherwise returns false.

◆ operator<()

bool PDateTime::operator< ( const PDateTime d) const

Returns true if this datetime is earlier than d; otherwise returns false.

◆ operator<=()

bool PDateTime::operator<= ( const PDateTime d) const

Returns true if this datetime is earlier than or equal to d; otherwise returns false.

◆ operator=()

PDateTime& PDateTime::operator= ( const PDateTime other)

Performs a shared copy of other to this object.

◆ operator==()

bool PDateTime::operator== ( const PDateTime d) const

Returns true if this datetime is equal to d; otherwise returns false.

◆ operator>()

bool PDateTime::operator> ( const PDateTime d) const

Returns true if this datetime is later than d; otherwise returns false.

◆ operator>=()

bool PDateTime::operator>= ( const PDateTime d) const

Returns true if this datetime is later than or equal to d; otherwise returns false.

◆ ToLocalTime()

PDateTime PDateTime::ToLocalTime ( ) const

Returns a copy of this datetime converted to local time.

◆ ToMillisecondsSinceEpoch()

papillon::int64 PDateTime::ToMillisecondsSinceEpoch ( ) const

Returns the number of milliseconds that have passed since 1970-01-01T00:00:00.000 UTC, in local time.

◆ ToString()

PString PDateTime::ToString ( const PString format = PString("yyyy-MM-dd hh:mm:ss,zzzt")) const

Returns the datetime as a string.

By default, use the format "yyyy-MM-dd hh:mm:ss,zzz".

The format parameter determines the format of the result string. These expressions may be used for the date:

  • d: the day as number without a leading zero (1 to 31)
  • dd: the day as number with a leading zero (01 to 31)
  • ddd: the abbreviated localized day name (e.g. 'Mon' to 'Sun')
  • dddd: the long localized day name (e.g. 'Monday' to 'Sunday')
  • M: the month as number without a leading zero (1-12)
  • MM: the month as number with a leading zero (01-12)
  • MMM: the abbreviated localized month name (e.g. 'Jan' to 'Dec')
  • MMMM: the long localized month name (e.g. 'January' to 'December')
  • yy: the year as two digit number (00-99)
  • yyyy: the year as four digit number

These expressions may be used for the time:

  • h: the hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display)
  • hh: the hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display)
  • H: the hour without a leading zero (0 to 23, even with AM/PM display)
  • HH: the hour with a leading zero (00 to 23, even with AM/PM display)
  • m: the minute without a leading zero (0 to 59)
  • mm: the minute with a leading zero (00 to 59)
  • s: the second without a leading zero (0 to 59)
  • ss: the second with a leading zero (00 to 59)
  • z: the milliseconds without leading zeros (0 to 999)
  • zzz: the milliseconds with leading zeros (000 to 999)
  • AP or A: use AM/PM display. A/AP will be replaced by either "AM" or "PM".
  • ap or a: use am/pm display. a/ap will be replaced by either "am" or "pm".
  • t: the timezone (for example "UTC")

All other input characters will be ignored. Any sequence of characters that are enclosed in single quotes will be treated as text and not be used as an expression. Two consecutive single quotes ("''") are replaced by a single quote in the output. Formats without separators (e.g. "HHmm") are currently not supported.

◆ ToStringISO()

PString PDateTime::ToStringISO ( ) const

Returns the ISO 8601 string corresponding to the datetime (it does not contain milliseconds).

Format is "YYYY-MM-DDThh:mm:ssZ" for a UTC date/time, see https://en.wikipedia.org/wiki/ISO_8601 to learn more.

◆ ToStringISOWithMs()

PString PDateTime::ToStringISOWithMs ( ) const

Returns the ISO 8601 string corresponding to the datetime, including milliseconds.

Format is "YYYY-MM-DDThh:mm:ss.zzzZ" for a UTC date/time, see https://en.wikipedia.org/wiki/ISO_8601 to learn more.

◆ ToUTC()

PDateTime PDateTime::ToUTC ( ) const

Returns a copy of this datetime converted to UTC time.