VCF::DateTime

VCF::DateTime Class Reference

This class is used to represent a point in time. More...

#include <vcf/FoundationKit/DateTime.h>

Inheritance diagram for VCF::DateTime:


Public Types
enum	{ ONEDAY = 24 * 60 * 60 * 1000, ONEHOUR = 60601000, ONEMINUTE = 60*1000, ONESECOND = 1000 }
enum	Months { Jan = 1, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec }
enum	WeekDay { Sun = 0, Mon, Tue, Wed, Thu, Fri, Sat }
enum	DayTime { AM = 0, PM }
Public Member Functions
	DateTime ()
	Constructs a blank/empty date time object.
	DateTime (time_t newTime)
	Constructs a date time object from a C time `time_t` value.
	DateTime (uint32 year, uint32 month, uint32 day)
	Constructs a date time object given a year, month, and a day.
	DateTime (uint32 year, uint32 month, uint32 day, uint32 hour, uint32 minute, uint32 second)
	Constructs a date time object given a year, month, day, hour, minute, and second.
uint64	getMilliseconds () const
	Returns a 64 bit unsigned integer that contains the total number of milliseconds in this object.
void	setMilliseconds (const uint64 &milliseconds)
	Sets the total number of milliseconds.
void	set (const uint32 &year, const uint32 &month, const uint32 &day, const uint32 &hour=0, const uint32 &minutes=0, const uint32 &seconds=0, const uint32 &milliseconds=0)
	Allows you to modify the date/time of this object.
void	setDate (const uint32 &year, const uint32 &month, const uint32 &day)
	Setting the date causes the current time to reset to 0:0:0.
void	setTime (const uint32 &hour, const uint32 &minutes, const uint32 &seconds)
	Setting the time via this function keeps the current date.
void	get (uint32 year, uint32 month, uint32 day, uint32 hour, uint32 minute, uint32 second, uint32 *millsecond=NULL) const
	Gets all the components of date/time.
void	getDate (uint32 year, uint32 month, uint32 *day) const
	Gets all the components of the date.
void	getTime (uint32 hour, uint32 minute, uint32 second, uint32 millsecond=NULL) const
	Gets all the components of the time.
DateTime	toLocal () const
	Converts the time to the system's local time.
DateTime	toUTC () const
	Converts the time to UTC time.
DateTime &	operator= (const DateTime &rhs)
	allows for assignment between this date time object and another.
	operator uint64 () const
	allows conversion to a uint64 ( POD ) data type
DateTime &	operator= (const time_t &rhs)
	Allows for assignment of C time values to this date time object.
DateTime	operator+ (const DateTimeSpan &rhs) const
	Allows you to add a time span to the value of this date object and return the new date object.
DateTime	operator- (const DateTimeSpan &rhs) const
	Allows you to subtract a time span from the value of this date object and return the new date object.
DateTimeSpan	operator- (const DateTime &rhs) const
	Allows you to subtract one date time object from another and returns the date time span between them.
bool	operator> (const DateTime &rhs) const
bool	operator>= (const DateTime &rhs) const
bool	operator< (const DateTime &rhs) const
bool	operator<= (const DateTime &rhs) const
bool	operator== (const DateTime &rhs) const
bool	operator!= (const DateTime &rhs) const
DayTime	getDayTime () const
bool	isAM () const
	Is the current time in the AM or not.
bool	isPM () const
	Is the current time in the PM or not.
bool	firstDayOfTheWeek () const
bool	lastDayOfTheWeek () const
bool	firstDayOfTheMonth () const
bool	lastDayOfTheMonth () const
bool	firstDayOfTheYear () const
bool	lastDayOfTheYear () const
bool	isLeapYear () const
time_t	getCTime () const
uint32	getYear () const
uint32	getMonth () const
uint32	getDay () const
uint32	getHour () const
uint32	getMinute () const
uint32	getSecond () const
uint32	getMillisecond () const
WeekDay	getWeekDay () const
uint32	getDayOfYear () const
uint32	getDaysInYear () const
uint32	getNumberOfDaysInMonth () const
uint32	getWeekOfYearStartingSun () const
uint32	getWeekOfYearStartingMon () const
uint32	getWeeksInYear () const
virtual String	toString ()
	returns a string representation of the object
virtual void	loadFromStream (InputStream *stream)
	Read the object from the specified input stream.
virtual void	saveToStream (OutputStream *stream)
	Write the object to the specified output stream.
DateTime &	incrYear (const uint32 &by=1)
	increments the year of this date object.
DateTime &	incrMonth (const uint32 &by=1)
	increments the month of this date object.
DateTime &	incrDay (const uint32 &by=1)
	increments the day of this date object.
DateTime &	incrHour (const uint32 &by=1)
	increments the hour of this date object.
DateTime &	incrMinute (const uint32 &by=1)
	increments the minute of this date object.
DateTime &	incrSecond (const uint32 &by=1)
	increments the second of this date object.
DateTime &	incrMilliSecond (const uint32 &by=1)
	increments the millisecond of this date object.
DateTime &	decrYear (const uint32 &by=1)
	decrements the year of this date object
DateTime &	decrMonth (const uint32 &by=1)
	decrements the month of this date object.
DateTime &	decrDay (const uint32 &by=1)
	decrements the day of this date object
DateTime &	decrHour (const uint32 &by=1)
	decrements the hour of this date object
DateTime &	decrMinute (const uint32 &by=1)
	decrements the minute of this date object
DateTime &	decrSecond (const uint32 &by=1)
	decrements the second of this date object
DateTime &	decrMilliSecond (const uint32 &by=1)
	decrements the millisecond of this date object
Static Public Member Functions
static DateTime	now ()
	Static utility function to get the current local date on the computer the framework is running on.
static void	getYearMonthDay (const DateTime &dt, uint32 year, uint32 month, uint32 *day)
static void	getHourMinuteSecond (const DateTime &dt, uint32 hour, uint32 minute, uint32 second, uint32 millsecond=NULL)
static uint32	getNumberOfDaysInMonth (uint32 year, Months month)
static bool	isGregorianCalendarDate (const uint32 &year, const uint32 &month, const uint32 &day)
static bool	isGregorianCalendarDate (const DateTime &dt)
static bool	isLeapYear (uint32 year)
Protected Member Functions
void	setAndAdjustForGregorianDay (const uint32 &year, const uint32 &month, const uint32 &day, const uint32 &hour, const uint32 &minutes, const uint32 &seconds, const uint32 &milliseconds)
Static Protected Member Functions
static void	setCurrent (DateTime &dt)
Protected Attributes
uint64	time_
	time is stored as the number of milliseconds since 1 January 4713 BC.
Friends
class	DateTimeSpan
Classes
class	Iterator
	templatized class for iterating a date, either forward or backard in time, where the template type DateLogic is a class with the following static methods: More...

Detailed Description

This class is used to represent a point in time.

The internal structure is a 64bit unsigned integer that counts the number of milliseconds from ~ 4700BC. The calendar used is the Gregorian calendar. There is logic to support switching to the Julian calendar for days before the Gregorian switch. At the moment there is no time zone support. This will be coming next.

There are a wide number of functions for retrieving all sorts of handy date/time info, such as :

getting the Month enumeration
getting the day of the week
getting the day of the year
getting the week of the year (starting on either Sun or Mon)
getting the number of days in a year
getting the number of weeks in a year
getting the number of weeks in a year
getting AM or PM
getting the time as C time(i.e. positive number of seconds since Jan 1, 1970)

There is iteration support in the form of the DateTime::Iterator class which allows templatized iterator logic and lets you:

incrementing or decrementing dates by a single unit in millisecond, second, minute, hour, day, month, or year resolution. This is done with the operator++ or operator --.
incrementing or decrementing dates by a 1 or more units in millisecond, second, minute, hour, day, month, or year resolution. This is done with the operator+=(n) or operator -=(n).

Since the iterator template type is customizable, you can create your own iteration logic classes to perform custom iteration logic.

You can modify the date time object in a variety of ways, by specifying the year, month, day, or set the time specifying hour, minute, second, or have more control by setting all fields (year, month, day, hour, minute, second, millisecond).

Most of the algorithms that this class uses come from: http://www.tondering.dk/claus/cal/

Member Enumeration Documentation

anonymous enum

Enumerator:

ONEDAY

ONEHOUR

ONEMINUTE

ONESECOND

enum VCF::DateTime::DayTime

Enumerator:

AM

PM

enum VCF::DateTime::Months

Enumerator:

Jan

Feb

Mar

Apr

May

Jun

Jul

Aug

Sep

Oct

Nov

Dec

enum VCF::DateTime::WeekDay

Enumerator:

Sun

Mon

Tue

Wed

Thu

Fri

Sat

Constructor & Destructor Documentation

VCF::DateTime::DateTime ( ) [inline]

Constructs a blank/empty date time object.

VCF::DateTime::DateTime ( time_t newTime )

Constructs a date time object from a C time time_t value.

VCF::DateTime::DateTime ( uint32 year,

uint32 month,

uint32 day

)

Constructs a date time object given a year, month, and a day.
The time will be set to 00:00:00. If the month or day is an invalid value, a BadDateFormat exception will be thrown. Valid ranges for months are between 1 and 12. Valid ranges for days are between 1 and the maximum day for the specified month and year (i.e. for Feb 2004 the range would be 1-29, while Feb 2003 the range would be 1-28). An example:
DateTime bobs31stBirthday(2004,2,24); //valid date - February 24, 2004 00:00:00 DateTime bobs32stBirthday(2005,14,24); //invalid date! BadDateFormat will be thrown

Exceptions:

BadDateFormat

VCF::DateTime::DateTime ( uint32 year,

uint32 month,

uint32 day,

uint32 hour,

uint32 minute,

uint32 second

)

Constructs a date time object given a year, month, day, hour, minute, and second.
If the month or day is an invalid value, a BadDateFormat exception will be thrown. If the hour, minute, or second is invalid a BadTimeFormat exception will be thrown. The Valid range for the hour value is between 0 and 23, and valid ranges for minutes, or seconds are between 0 and 59. An example:
DateTime bobs31stBirthday(2004,2,24,10,32,12); //valid date - February 24, 2004 10:32:12 DateTime bobs32stBirthday(2005,2,24,60,32,12); //invalid date! BadTimeFormat will be thrown

Exceptions:

BadDateFormat

BadTimeFormat

Member Function Documentation

DateTime& VCF::DateTime::decrDay ( const uint32 & by = 1 )

decrements the day of this date object

Parameters:

uint32 the amount to decrement the day by

Returns:
the object itself

DateTime& VCF::DateTime::decrHour ( const uint32 & by = 1 )

decrements the hour of this date object

Parameters:

uint32 the amount to decrement the hour by

Returns:
the object itself

DateTime& VCF::DateTime::decrMilliSecond ( const uint32 & by = 1 )

decrements the millisecond of this date object

Parameters:

uint32 the amount to decrement the millisecond by

Returns:
the object itself

DateTime& VCF::DateTime::decrMinute ( const uint32 & by = 1 )

decrements the minute of this date object

Parameters:

uint32 the amount to decrement the minute by

Returns:
the object itself

DateTime& VCF::DateTime::decrMonth ( const uint32 & by = 1 )

decrements the month of this date object.
See the incrMonth() method for more details on the behaviour of this function.
Parameters:

uint32 the amount to decrement the month by

See also:
incrMonth()

Returns:
the object itself

DateTime& VCF::DateTime::decrSecond ( const uint32 & by = 1 )

decrements the second of this date object

Parameters:

uint32 the amount to decrement the second by

Returns:
the object itself

DateTime& VCF::DateTime::decrYear ( const uint32 & by = 1 )

decrements the year of this date object

Parameters:

uint32 the amount to decrement the millisecond by

Returns:
the object itself

bool VCF::DateTime::firstDayOfTheMonth ( ) const

bool VCF::DateTime::firstDayOfTheWeek ( ) const

bool VCF::DateTime::firstDayOfTheYear ( ) const

void VCF::DateTime::get ( uint32 * year,

uint32 * month,

uint32 * day,

uint32 * hour,

uint32 * minute,

uint32 * second,

uint32 * millsecond = NULL

) const [inline]

Gets all the components of date/time.

Parameters:

pointer to uint32 accepting the year.

pointer to uint32 accepting the month.

pointer to uint32 accepting the day.

pointer to uint32 accepting the hour.

pointer to uint32 accepting the minute.

pointer to uint32 accepting the second.

pointer to uint32 accepting the millisecond. Any pointer that is NULL does not accept any value.

time_t VCF::DateTime::getCTime ( ) const

void VCF::DateTime::getDate ( uint32 * year,

uint32 * month,

uint32 * day

) const [inline]

Gets all the components of the date.

Parameters:

pointer to uint32 accepting the year.

pointer to uint32 accepting the month.

pointer to uint32 accepting the day. Any pointer that is NULL does not accept any value.

uint32 VCF::DateTime::getDay ( ) const

uint32 VCF::DateTime::getDayOfYear ( ) const

uint32 VCF::DateTime::getDaysInYear ( ) const

DayTime VCF::DateTime::getDayTime ( ) const

uint32 VCF::DateTime::getHour ( ) const

static void VCF::DateTime::getHourMinuteSecond ( const DateTime & dt,

uint32 * hour,

uint32 * minute,

uint32 * second,

uint32 * millsecond = NULL

) [static]

uint32 VCF::DateTime::getMillisecond ( ) const

uint64 VCF::DateTime::getMilliseconds ( ) const

Returns a 64 bit unsigned integer that contains the total number of milliseconds in this object.

uint32 VCF::DateTime::getMinute ( ) const

uint32 VCF::DateTime::getMonth ( ) const

static uint32 VCF::DateTime::getNumberOfDaysInMonth ( uint32 year,

Months month

) [static]

uint32 VCF::DateTime::getNumberOfDaysInMonth ( ) const

uint32 VCF::DateTime::getSecond ( ) const

void VCF::DateTime::getTime ( uint32 * hour,

uint32 * minute,

uint32 * second,

uint32 * millsecond = NULL

) const [inline]

Gets all the components of the time.

Parameters:

pointer to uint32 accepting the minute.

pointer to uint32 accepting the second.

pointer to uint32 accepting the millisecond. Any pointer that is NULL does not accept any value.

WeekDay VCF::DateTime::getWeekDay ( ) const

uint32 VCF::DateTime::getWeekOfYearStartingMon ( ) const

uint32 VCF::DateTime::getWeekOfYearStartingSun ( ) const

uint32 VCF::DateTime::getWeeksInYear ( ) const

uint32 VCF::DateTime::getYear ( ) const

static void VCF::DateTime::getYearMonthDay ( const DateTime & dt,

uint32 * year,

uint32 * month,

uint32 * day

) [static]

DateTime& VCF::DateTime::incrDay ( const uint32 & by = 1 )

increments the day of this date object.

Parameters:

uint32 the amount to increment the day by

Returns:
the object itself

DateTime& VCF::DateTime::incrHour ( const uint32 & by = 1 )

increments the hour of this date object.

Parameters:

uint32 the amount to increment the hour by

Returns:
the object itself

DateTime& VCF::DateTime::incrMilliSecond ( const uint32 & by = 1 )

increments the millisecond of this date object.

Parameters:

uint32 the amount to increment the millisecond by

Returns:
the object itself

DateTime& VCF::DateTime::incrMinute ( const uint32 & by = 1 )

increments the minute of this date object.

Parameters:

uint32 the amount to increment the minute by

Returns:
the object itself

DateTime& VCF::DateTime::incrMonth ( const uint32 & by = 1 )

increments the month of this date object.
This takes into account increments greater than 12 (which would then also increment the year). It also treats the end of the month as follows: if the day of the object falls on the very last day of the month prior to the increment then the algorithm will "pin" the day, shortening or lengthening it depending on the newly incremented months value. For example, if the current date instance is set to Jan 31, 2003, and you increment the month by 1 unit, then the new value will be set to Feb 28, 2003.
Parameters:

uint32 the amount to increment the month by

Returns:
the object itself

DateTime& VCF::DateTime::incrSecond ( const uint32 & by = 1 )

increments the second of this date object.

Parameters:

uint32 the amount to increment the second by

Returns:
the object itself

DateTime& VCF::DateTime::incrYear ( const uint32 & by = 1 )

increments the year of this date object.

Parameters:

uint32 the amount to increment the year by

Returns:
the object itself

bool VCF::DateTime::isAM ( ) const

Is the current time in the AM or not.

Returns:
bool true if the current time is less than 12 hours

static bool VCF::DateTime::isGregorianCalendarDate ( const DateTime & dt ) [static]

static bool VCF::DateTime::isGregorianCalendarDate ( const uint32 & year,

const uint32 & month,

const uint32 & day

) [static]

static bool VCF::DateTime::isLeapYear ( uint32 year ) [static]

bool VCF::DateTime::isLeapYear ( ) const

bool VCF::DateTime::isPM ( ) const

Is the current time in the PM or not.

Returns:
bool true if the current time is greater than or equal to 12 hours

bool VCF::DateTime::lastDayOfTheMonth ( ) const

bool VCF::DateTime::lastDayOfTheWeek ( ) const

bool VCF::DateTime::lastDayOfTheYear ( ) const

virtual void VCF::DateTime::loadFromStream ( InputStream * stream ) [virtual]

Read the object from the specified input stream.

Implements VCF::Persistable.

static DateTime VCF::DateTime::now ( ) [inline, static]

Static utility function to get the current local date on the computer the framework is running on.
Resolution will be in milliseconds.

VCF::DateTime::operator uint64 ( ) const [inline]

allows conversion to a uint64 ( POD ) data type

bool VCF::DateTime::operator!= ( const DateTime & rhs ) const

DateTime VCF::DateTime::operator+ ( const DateTimeSpan & rhs ) const

Allows you to add a time span to the value of this date object and return the new date object.

DateTimeSpan VCF::DateTime::operator- ( const DateTime & rhs ) const

Allows you to subtract one date time object from another and returns the date time span between them.

DateTime VCF::DateTime::operator- ( const DateTimeSpan & rhs ) const

Allows you to subtract a time span from the value of this date object and return the new date object.

bool VCF::DateTime::operator< ( const DateTime & rhs ) const

bool VCF::DateTime::operator<= ( const DateTime & rhs ) const

DateTime& VCF::DateTime::operator= ( const time_t & rhs )

Allows for assignment of C time values to this date time object.
For example:
time_t ctime = 0; time( &ctime ); DateTime dt; dt = ctime;

DateTime& VCF::DateTime::operator= ( const DateTime & rhs ) [inline]

allows for assignment between this date time object and another.

bool VCF::DateTime::operator== ( const DateTime & rhs ) const

bool VCF::DateTime::operator> ( const DateTime & rhs ) const

bool VCF::DateTime::operator>= ( const DateTime & rhs ) const

virtual void VCF::DateTime::saveToStream ( OutputStream * stream ) [virtual]

Write the object to the specified output stream.

Implements VCF::Persistable.

void VCF::DateTime::set ( const uint32 & year,

const uint32 & month,

const uint32 & day,

const uint32 & hour = 0,

const uint32 & minutes = 0,

const uint32 & seconds = 0,

const uint32 & milliseconds = 0

)

Allows you to modify the date/time of this object.

Parameters:

uint32 the year

uint32 the month. This must be a value between 1 and 12. Values outside of this range will cause a BadDateFormat exception to be thrown.

uint32 the day. This must be a value between 1 and the maximum day for the specified month and year. Values outside of this range will cause a BadDateFormat exception to be thrown.

uint32 the hour. This must be a value between 0 and 59. Values outside of this range will cause a BadTimeFormat exception to be thrown.

uint32 the minutes. This must be a value between 0 and 59. Values outside of this range will cause a BadTimeFormat exception to be thrown.

uint32 the seconds. This must be a value between 0 and 59. Values outside of this range will cause a BadTimeFormat exception to be thrown.

uint32 the milliseconds. This must be a value between 0 and 999. Values outside of this range will cause a BadTimeFormat exception to be thrown.

Exceptions:

BadDateFormat

BadTimeFormat

void VCF::DateTime::setAndAdjustForGregorianDay ( const uint32 & year,

const uint32 & month,

const uint32 & day,

const uint32 & hour,

const uint32 & minutes,

const uint32 & seconds,

const uint32 & milliseconds

) [protected]

static void VCF::DateTime::setCurrent ( DateTime & dt ) [static, protected]

void VCF::DateTime::setDate ( const uint32 & year,

const uint32 & month,

const uint32 & day

)

Setting the date causes the current time to reset to 0:0:0.
So if you have a DateTime object that is set to Jan 23, 2123 12:23:22, and you call setDate( 2003, 6, 12 ), the result will be a DateTime object set to June 12, 2003 00:00:00.

Parameters:

uint32 the year

uint32 the month. This must be a value between 1 and 12. Values outside of this range will cause a BadDateFormat exception to be thrown.

uint32 the day. This must be a value between 1 and the maximum day for the specified month and year. Values outside of this range will cause a BadDateFormat exception to be thrown.

Exceptions:

BadDateFormat

void VCF::DateTime::setMilliseconds ( const uint64 & milliseconds )

Sets the total number of milliseconds.

void VCF::DateTime::setTime ( const uint32 & hour,

const uint32 & minutes,

const uint32 & seconds

)

Setting the time via this function keeps the current date.
So if you have a DateTime object that is set to Jan 23, 2123 12:23:22, and you call setTime( 16, 2, 45 ) , the result will be a DateTime object set to Jan 23, 2123 16:02:45.

Parameters:

uint32 the hour. This must be a value between 0 and 23. Values outside of this range will cause a BadTimeFormat exception to be thrown.

uint32 the minutes. This must be a value between 0 and 59. Values outside of this range will cause a BadTimeFormat exception to be thrown.

uint32 the seconds. This must be a value between 0 and 59. Values outside of this range will cause a BadTimeFormat exception to be thrown.

Exceptions:

BadTimeFormat

DateTime VCF::DateTime::toLocal ( ) const

Converts the time to the system's local time.

virtual String VCF::DateTime::toString ( ) [virtual]

returns a string representation of the object

Reimplemented from VCF::Object.

DateTime VCF::DateTime::toUTC ( ) const

Converts the time to UTC time.

Friends And Related Function Documentation

friend class DateTimeSpan [friend]

Member Data Documentation

uint64 VCF::DateTime::time_ [protected]

time is stored as the number of milliseconds since 1 January 4713 BC.
This is also known as the Julian Day used by astronomers

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

vcf/FoundationKit/DateTime.h

VCF::DateTime Class Reference

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes