DateTime

#include <icy/datetime.h>

This class represents an instant in time, expressed in years, months, days, hours, minutes, seconds and milliseconds based on the Gregorian calendar. The class is mainly useful for conversions between UTC, Julian day and Gregorian calendar dates.

The date and time stored in a DateTime is always in UTC (Coordinated Universal Time) and thus independent of the timezone in effect on the system.

Conversion calculations are based on algorithms collected and described by Peter Baum at http://vsg.cape.com/~pbaum/date/date0.htm

Internally, this class stores a date/time in two forms (UTC and broken down) for performance reasons. Only use this class for conversions between date/time representations. Use the Timestamp class for everything else.

Notes:

Zero is a valid year (in accordance with ISO 8601 and astronomical year numbering)
Year zero (0) is a leap year
Negative years (years preceding 1 BC) are not supported

For more information, please see:

Public Methods

Return	Name	Description
	`DateTime`	Creates a DateTime for the current date and time.
	`DateTime`	Creates a DateTime for the date and time given in a Timestamp.
	`DateTime`	Creates a DateTime for the given Gregorian date and time.
	`DateTime`	Creates a DateTime for the given Julian day.
	`DateTime`	Creates a DateTime from an UtcTimeVal and a TimeDiff.
	`DateTime`	Copy constructor. Creates the DateTime from another one.
	`~DateTime`	Destroys the DateTime.
`DateTime &`	`operator=`	Assigns another DateTime.
`DateTime &`	`operator=`	Assigns a Timestamp.
`DateTime &`	`operator=`	Assigns a Julian day.
`DateTime &`	`assign`	Assigns a Gregorian date and time.
`void`	`swap`	Swaps the DateTime with another one.
`int`	`year` `const` `inline`	Returns the year.
`int`	`month` `const` `inline`	Returns the month (1 to 12).
`int`	`week` `const`	Returns the week number within the year. FirstDayOfWeek should be either SUNDAY (0) or MONDAY (1). The returned week number will be from 0 to 53. Week number 1 is the week containing January 4. This is in accordance to ISO 8601.
`int`	`day` `const` `inline`	Returns the day witin the month (1 to 31).
`int`	`dayOfWeek` `const`	Returns the weekday (0 to 6, where 0 = Sunday, 1 = Monday, ..., 6 = Saturday).
`int`	`dayOfYear` `const`	Returns the number of the day in the year. January 1 is 1, February 1 is 32, etc.
`int`	`hour` `const` `inline`	Returns the hour (0 to 23).
`int`	`hourAMPM` `const` `inline`	Returns the hour (0 to 12).
`bool`	`isAM` `const` `inline`	Returns true if hour < 12;.
`bool`	`isPM` `const` `inline`	Returns true if hour >= 12.
`int`	`minute` `const` `inline`	Returns the minute (0 to 59).
`int`	`second` `const` `inline`	Returns the second (0 to 59).
`int`	`millisecond` `const` `inline`	Returns the millisecond (0 to 999)
`int`	`microsecond` `const` `inline`	Returns the microsecond (0 to 999)
`double`	`julianDay` `const`	Returns the julian day for the date and time.
`Timestamp`	`timestamp` `const` `inline`	Returns the date and time expressed as a Timestamp.
`Timestamp::UtcTimeVal`	`utcTime` `const` `inline`	Returns the date and time expressed in UTC-based time. UTC base time is midnight, October 15, 1582. Resolution is 100 nanoseconds.
`bool`	`operator==` `const` `inline`
`bool`	`operator!=` `const` `inline`
`bool`	`operator<` `const` `inline`
`bool`	`operator<=` `const` `inline`
`bool`	`operator>` `const` `inline`
`bool`	`operator>=` `const` `inline`
`DateTime`	`operator+` `const`
`DateTime`	`operator-` `const`
`Timespan`	`operator-` `const`
`DateTime &`	`operator+=`
`DateTime &`	`operator-=`
`void`	`makeUTC`	Converts a local time into UTC, by applying the given time zone differential.
`void`	`makeLocal`	Converts a UTC time into a local time, by applying the given time zone differential.

DateTime

DateTime()

Creates a DateTime for the current date and time.

DateTime

DateTime(const Timestamp & timestamp)

Creates a DateTime for the date and time given in a Timestamp.

DateTime

DateTime(int year, int month, int day, int hour, int minute, int second, int millisecond, int microsecond)

Creates a DateTime for the given Gregorian date and time.

year is from 0 to 9999.
month is from 1 to 12.
day is from 1 to 31.
hour is from 0 to 23.
minute is from 0 to 59.
second is from 0 to 59.
millisecond is from 0 to 999.
microsecond is from 0 to 999.

DateTime

DateTime(double julianDay)

Creates a DateTime for the given Julian day.

DateTime

DateTime(Timestamp::UtcTimeVal utcTime, Timestamp::TimeDiff diff)

Creates a DateTime from an UtcTimeVal and a TimeDiff.

Mainly used internally by DateTime and friends.

DateTime

DateTime(const DateTime & dateTime)

Copy constructor. Creates the DateTime from another one.

~DateTime

~DateTime()

Destroys the DateTime.

operator=

DateTime & operator=(const DateTime & dateTime)

Assigns another DateTime.

operator=

DateTime & operator=(const Timestamp & timestamp)

Assigns a Timestamp.

operator=

DateTime & operator=(double julianDay)

Assigns a Julian day.

assign

DateTime & assign(int year, int month, int day, int hour, int minute, int second, int millisecond, int microseconds)

Assigns a Gregorian date and time.

year is from 0 to 9999.
month is from 1 to 12.
day is from 1 to 31.
hour is from 0 to 23.
minute is from 0 to 59.
second is from 0 to 59.
millisecond is from 0 to 999.
microsecond is from 0 to 999.

swap

void swap(DateTime & dateTime)

Swaps the DateTime with another one.

year

const inline

inline int year() const

Returns the year.

month

const inline

inline int month() const

Returns the month (1 to 12).

week

const

int week(int firstDayOfWeek) const

Returns the week number within the year. FirstDayOfWeek should be either SUNDAY (0) or MONDAY (1). The returned week number will be from 0 to 53. Week number 1 is the week containing January 4. This is in accordance to ISO 8601.

The following example assumes that firstDayOfWeek is MONDAY. For 2005, which started on a Saturday, week 1 will be the week starting on Monday, January 3. January 1 and 2 will fall within week 0 (or the last week of the previous year).

For 2007, which starts on a Monday, week 1 will be the week startung on Monday, January 1. There will be no week 0 in 2007.

day

const inline

inline int day() const

Returns the day witin the month (1 to 31).

dayOfWeek

const

int dayOfWeek() const

Returns the weekday (0 to 6, where 0 = Sunday, 1 = Monday, ..., 6 = Saturday).

dayOfYear

const

int dayOfYear() const

Returns the number of the day in the year. January 1 is 1, February 1 is 32, etc.

hour

const inline

inline int hour() const

Returns the hour (0 to 23).

hourAMPM

const inline

inline int hourAMPM() const

Returns the hour (0 to 12).

isAM

const inline

inline bool isAM() const

Returns true if hour < 12;.

isPM

const inline

inline bool isPM() const

Returns true if hour >= 12.

minute

const inline

inline int minute() const

Returns the minute (0 to 59).

second

const inline

inline int second() const

Returns the second (0 to 59).

millisecond

const inline

inline int millisecond() const

Returns the millisecond (0 to 999)

microsecond

const inline

inline int microsecond() const

Returns the microsecond (0 to 999)

julianDay

const

double julianDay() const

Returns the julian day for the date and time.

timestamp

const inline

inline Timestamp timestamp() const

Returns the date and time expressed as a Timestamp.

utcTime

const inline

inline Timestamp::UtcTimeVal utcTime() const

Returns the date and time expressed in UTC-based time. UTC base time is midnight, October 15, 1582. Resolution is 100 nanoseconds.

operator==

const inline

inline bool operator==(const DateTime & dateTime) const

operator!=

const inline

inline bool operator!=(const DateTime & dateTime) const

operator<

const inline

inline bool operator<(const DateTime & dateTime) const

operator<=

const inline

inline bool operator<=(const DateTime & dateTime) const

operator>

const inline

inline bool operator>(const DateTime & dateTime) const

operator>=

const inline

inline bool operator>=(const DateTime & dateTime) const

operator+

const

DateTime operator+(const Timespan & span) const

operator-

const

DateTime operator-(const Timespan & span) const

operator-

const

Timespan operator-(const DateTime & dateTime) const

operator+=

DateTime & operator+=(const Timespan & span)

operator-=

DateTime & operator-=(const Timespan & span)

makeUTC

void makeUTC(int tzd)

Converts a local time into UTC, by applying the given time zone differential.

makeLocal

void makeLocal(int tzd)

Converts a UTC time into a local time, by applying the given time zone differential.

Public Static Methods

Return	Name	Description
`bool`	`isLeapYear` `static` `inline`	Returns true if the given year is a leap year; false otherwise.
`int`	`daysOfMonth` `static`	Returns the number of days in the given month and year. Month is from 1 to 12.
`bool`	`isValid` `static`	Checks if the given date and time is valid (all arguments are within a proper range).

isLeapYear

static inline

static inline bool isLeapYear(int year)

Returns true if the given year is a leap year; false otherwise.

daysOfMonth

static

static int daysOfMonth(int year, int month)

Returns the number of days in the given month and year. Month is from 1 to 12.

isValid

static

static bool isValid(int year, int month, int day, int hour, int minute, int second, int millisecond, int microsecond)

Checks if the given date and time is valid (all arguments are within a proper range).

Returns true if all arguments are valid, false otherwise.

Protected Methods

Return	Name	Description
`void`	`computeGregorian`	Computes the Gregorian date for the given Julian day. See http://vsg.cape.com/~pbaum/date/injdimp.htm, section 3.3.1 for the algorithm.
`void`	`computeDaytime`	Extracts the daytime (hours, minutes, seconds, etc.) from the stored utcTime.

computeGregorian

void computeGregorian(double julianDay)

Computes the Gregorian date for the given Julian day. See http://vsg.cape.com/~pbaum/date/injdimp.htm, section 3.3.1 for the algorithm.

computeDaytime

void computeDaytime()

Extracts the daytime (hours, minutes, seconds, etc.) from the stored utcTime.

Public Types

Name	Description
`Months`	Symbolic names for month numbers (1 to 12).
`DaysOfWeek`	Symbolic names for week day numbers (0 to 6).

Months

enum Months

Symbolic names for month numbers (1 to 12).

Value	Description
`JANUARY`
`FEBRUARY`
`MARCH`
`APRIL`
`MAY`
`JUNE`
`JULY`
`AUGUST`
`SEPTEMBER`
`OCTOBER`
`NOVEMBER`
`DECEMBER`

DaysOfWeek

enum DaysOfWeek

Symbolic names for week day numbers (0 to 6).

Value	Description
`SUNDAY`
`MONDAY`
`TUESDAY`
`WEDNESDAY`
`THURSDAY`
`FRIDAY`
`SATURDAY`

Private Attributes

Return	Name	Description
`Timestamp::UtcTimeVal`	`_utcTime`
`short`	`_year`
`short`	`_month`
`short`	`_day`
`short`	`_hour`
`short`	`_minute`
`short`	`_second`
`short`	`_millisecond`
`short`	`_microsecond`

_utcTime

Timestamp::UtcTimeVal _utcTime

_year

short _year

_month

short _month

_day

short _day

_hour

short _hour

_minute

short _minute

_second

short _second

_millisecond

short _millisecond

_microsecond

short _microsecond

Private Methods

Return	Name	Description
`void`	`checkLimit`	Utility functions used to correct the overflow in computeGregorian.
`void`	`normalize`

checkLimit

void checkLimit(short & lower, short & higher, short limit)

Utility functions used to correct the overflow in computeGregorian.

normalize

void normalize()