RWDateTime Class Reference
[Dates and Times]

Represents a date and time stored in milliseconds. More...

#include <rw/tools/datetime.h>

Inheritance diagram for RWDateTime:

Public Types
enum	InitialState { invalid, null, setCurrentTime }
enum	SetType { setDate, setTime, setBoth }
enum	Format { iso8601, iso8601_midnight24 }
Public Member Functions
	RWDateTime (InitialState init_state=invalid)
	RWDateTime (const RWDateTime &dt)
	RWDateTime (rwint64 msec)
	RWDateTime (const struct tm *tmbuf, unsigned msec=0, const RWZone &loc=RWZone::local())
	RWDateTime (const RWTime &t, unsigned msec=0)
	RWDateTime (const RWDate &d, unsigned hours=0, unsigned minutes=0, unsigned seconds=0, unsigned msec=0, const RWZone &zone=RWZone::local())
	RWDateTime (unsigned month_day, const char *month, unsigned year, unsigned hours, unsigned minutes, unsigned seconds, unsigned msec, const RWLocale &loc=RWLocale::global(), const RWZone &zone=RWZone::local())
	RWDateTime (unsigned day, unsigned month, unsigned year, unsigned hours=0, unsigned minutes=0, unsigned seconds=0, unsigned milliseconds=0, const RWZone &zone=RWZone::local())
	RWDateTime (const RWCString &str, SetType set_type=setBoth, const RWLocale &loc=RWLocale::global(), const RWZone &zone=RWZone::local())
	RWDateTime (const RWCString &str, Format f, const RWLocale &loc=RWLocale::global(), const RWZone &zone=RWZone::local())
	RWDateTime (std::istream &s, SetType set_type, const RWLocale &loc=RWLocale::global(), const RWZone &zone=RWZone::local())
RWDateTime &	operator= (const RWDateTime &)
RWCString	asString (char format, const RWLocale &loc=RWLocale::global(), const RWZone &zone=RWZone::local()) const
RWCString	asString (const char *format, const RWLocale &loc=RWLocale::global(), const RWZone &zone=RWZone::local()) const
RWCString	asString (Format format, const RWLocale &loc=RWLocale::global(), const RWZone &zone=RWZone::local()) const
bool	between (const RWDateTime &a, const RWDateTime &b) const
RWspace	binaryStoreSize () const
int	compareTo (const RWDateTime *d) const
int	compareTo (const RWDateTime &d) const
unsigned	correctedJulian () const
unsigned	day (const RWZone &zone=RWZone::local()) const
unsigned	dayGMT () const
unsigned	dayOfMonth (const RWZone &zone=RWZone::local()) const
unsigned	dayOfMonthGMT () const
RWDateTime &	decrementDay (const rwint64 d)
RWDateTime &	decrementHour (const rwint64 h)
RWDateTime &	decrementMinute (const rwint64 m)
RWDateTime &	decrementSecond (const rwint64 s)
RWDateTime &	decrementMillisecond (const rwint64 msec)
void	extract (struct tm *tmbuf, const RWZone &zone=RWZone::local()) const
void	extractGMT (struct tm *tmbuf) const
unsigned	firstDayOfMonth (unsigned mon, const RWZone &zone=RWZone::local()) const
unsigned	firstDayOfMonth (const RWZone &zone=RWZone::local()) const
unsigned	hash () const
unsigned	hour (const RWZone &zone=RWZone::local()) const
unsigned	hourGMT () const
RWDateTime &	incrementDay (const rwint64 d)
RWDateTime &	incrementHour (const rwint64 h)
RWDateTime &	incrementMinute (const rwint64 m)
RWDateTime &	incrementSecond (const rwint64 s)
RWDateTime &	incrementMillisecond (const rwint64 msec)
bool	isDST (const RWZone &zone=RWZone::local()) const
bool	isFuture () const
bool	isPast () const
bool	isNull () const
bool	isInvalid () const
bool	isSentinel () const
bool	isValid () const
double	julianDay () const
void	julianDay (double j)
unsigned	julian () const
void	julian (unsigned j)
bool	leap (const RWZone &zone=RWZone::local()) const
bool	leapGMT () const
RWDateTime	max (const RWDateTime &t) const
RWDateTime	min (const RWDateTime &t) const
rwint64	milliSeconds () const
unsigned	milliSecond () const
unsigned	minute (const RWZone &zone=RWZone::local()) const
unsigned	minuteGMT () const
unsigned	month (const RWZone &zone=RWZone::local()) const
unsigned	monthGMT () const
RWCString	monthName (const RWLocale &loc=RWLocale::global(), const RWZone &zone=RWZone::local()) const
RWDateTime	next (unsigned dayNum, const RWZone &zone=RWZone::local()) const
RWDateTime	next (const char *dayName, const RWLocale &loc=RWLocale::global(), const RWZone &zone=RWZone::local()) const
RWDateTime	previous (unsigned dayNum, const RWZone &zone=RWZone::local()) const
RWDateTime	previous (const char *dayName, const RWLocale &loc=RWLocale::global(), const RWZone &zone=RWZone::local()) const
std::istream &	readTime (std::istream &is)
std::istream &	readDate (std::istream &is)
std::ostream &	writeDate (std::ostream &os) const
std::ostream &	writeTime (std::ostream &os) const
RWDate	toRWDate (const RWZone &zone=RWZone::local()) const
RWTime	toRWTime () const
void	restoreFrom (RWFile &)
void	restoreFrom (RWvistream &)
void	saveOn (RWFile &) const
void	saveOn (RWvostream &) const
unsigned	second (const RWZone &zone=RWZone::local()) const
unsigned	secondGMT () const
unsigned	weekDay (const RWZone &zone=RWZone::local()) const
RWCString	weekDayName (const RWLocale &loc=RWLocale::global(), const RWZone &zone=RWZone::local()) const
unsigned	weekDayGMT () const
unsigned	year (const RWZone &zone=RWZone::local()) const
unsigned	yearGMT () const
Static Public Member Functions
static RWDateTime	beginDST (unsigned year, const RWZone &zone=RWZone::local())
static unsigned	daysInMonthYear (unsigned month, unsigned year)
static unsigned	daysInYear (unsigned year)
static unsigned	dayOfWeek (const char *day, const RWLocale &loc=RWLocale::global())
static bool	dayWithinMonth (unsigned month, unsigned day, unsigned year)
static RWDateTime	endDST (unsigned year, const RWZone &zone=RWZone::local())
static unsigned	hash (const RWDateTime &dt)
static unsigned	indexOfMonth (const char *monthName, const RWLocale &loc=RWLocale::global())
static bool	leapYear (unsigned year)
static RWDateTime	now ()
static RWCString	nameOfMonth (unsigned monthNum, const RWLocale &loc=RWLocale::global())
static RWCString	weekDayName (unsigned dayNum, const RWLocale &loc=RWLocale::global())
static RWDateTime	userSentinel (int n)
Static Public Attributes
static const rwint64	millisecsInSec
static const rwint64	millisecsInMin
static const rwint64	millisecsInHour
static const rwint64	millisecsInDay
static const rwint64	userSentinelStart
static const rwint64	pastSentinel
static const rwint64	futureSentinel
static const rwint64	invalidSentinel
static const rwint64	nullSentinel
static const rwint64	minDateTime
static const rwint64	maxDateTime
Friends
std::ostream &	operator<< (std::ostream &s, const RWDateTime &dt)
std::istream &	operator>> (std::istream &s, RWDateTime &dt)
RWDateTime	operator+ (const RWDateTime &d, rwint64 s)
RWDateTime	operator+ (rwint64 s, const RWDateTime &d)
RWDateTime	operator- (const RWDateTime &d, rwint64 s)
rwint64	operator- (const RWDateTime &dt1, const RWDateTime &dt2)
Related Functions
(Note that these are not member functions.)
RWvistream &	operator>> (RWvistream &str, RWDateTime &t)
RWFile &	operator>> (RWFile &file, RWDateTime &t)
RWvistream &	operator>> (RWvistream &str, RWDateTime *&t)
RWFile &	operator>> (RWFile &file, RWDateTime *&t)
RWvostream &	operator<< (RWvostream &str, const RWDateTime &t)
RWFile &	operator<< (RWFile &file, const RWDateTime &t)
bool	operator== (const RWDateTime &d1, const RWDateTime &d2)
bool	operator!= (const RWDateTime &d1, const RWDateTime &d2)
bool	operator< (const RWDateTime &d1, const RWDateTime &d2)
bool	operator> (const RWDateTime &d1, const RWDateTime &d2)
bool	operator<= (const RWDateTime &d1, const RWDateTime &d2)
bool	operator>= (const RWDateTime &d1, const RWDateTime &d2)

Detailed Description

Class RWDateTime represents a date and time, stored in milliseconds, from January 1, 1901 00:00:00:000 UTC. Milliseconds are stored in a 64-bit integral type, which is represented by the global typedef rwint64.

RWDateTime supports the ISO 8601 international standard for the formatting of dates and times. For information and formatting syntax, see the chapter on internationalization in the Essential Tools Module User's Guide.

RWDateTime is based on the Gregorian Calendar, and its range extends for thousands of years beyond that of the deprecated RWTime. The Gregorian calendar was introduced by Pope Gregory XIII in 1582, and was adopted in various places at various times. It was adopted by England on September 14, 1752, and thus came to the United States. RWDateTime is designed for use with dates after September 14, 1752.

Four public member functions, all starting with julian, let you manipulate the date via Modified Julian days (MJD). Note that the Modified Julian day number is not the same as a date according to the Julian calendar. The Modified Julian day number is calculated using Algorithm 199 from Communications of the ACM, Volume 6, No. 8, (Aug. 1963), p. 444 and is valid for any valid Gregorian date in the Gregorian calendar. The Essential Tools Module User's Guide provides more information.

Note:: The modern Modified Julian Day (MJD) was introduced in the 1950s and starts at midnight, as opposed to the historic Julian Day (JD), which began at 12 noon. MJD is defined as MJD = JD - 2400000.5. The half day is subtracted so that the day starts at midnight in conformance with civil time reckoning.

Modified Julian days in RWDateTime function correctly from Modified Julian day 0, but can be converted only to month, date, year for Modified Julian days that fall within the Gregorian Calendar.

Note:: Two-digit year specifiers assume the century 1900, so you should create programs that use four-digit year specifiers. You can enforce the use of a four-digit year by defining the build macro RW_CENTURY_REQD in RCB when building the libraries. Be aware, however, that defining this macro requires a four-digit year to be provided when constructing an RWDateTime. For more information, see the section on RWDateTime in the Essential Tools Module User's Guide.

RWDateTime can be converted to and from RWTime and RWDate instances. Because of the greater accuracy and range, RWDateTime is the preferred class to use for dates and times.

Note:: RWTime and RWDate are deprecated and so are all methods that either take or return instances of these two classes. Deprecation means that these classes and related methods are no longer supported, and may be removed in a future release.

RWDateTime instances can also be converted to and from the Standard C Library type struct tm defined in <time.h>, and listed below.

The Standard C Library Type struct tm

`int tm_sec;`	`seconds after the minute - [0,59]`
`int tm_min;`	`minutes after the hour - [0,59]`
`int tm_hour;`	`hours since midnight - [0,23]`
`int tm_mday;`	`day of the month - [1,31]`
`int tm_mon;`	`months since January - [0,11]`
`int tm_year;`	`years since 1900`
`int tm_wday;`	`days since Sunday - [0,6]`
`int tm_yday;`	`days since January 1 - [0,365]`
`int tm_isdst;`	`daylight savings time flag`

The default constructor for this class creates an instance with an invalid date and time, unlike RWDate and RWTime, both of which hold the current date by default. Consequently, it is much quicker to create a large array using RWDateTime than it is using RWDate. The example below illustrates the difference:

 RWDate  v[5000];            //  Figures  out  the  current  date  5000  times
 RWDateTime  v[5000];  //  Creates  an  array  with  5000  undefined  dates
 //  and  times

RWDateTime objects can hold a variety of sentinel values that do not refer to actual dates. Consequently it is important to know whether an object holds an actual date before performing many operations. The isSentinel() function returns true when an object holds a sentinel value.

Note that the use of the isValid() function does not determine whether a member function can be successfully applied to an object, since the null sentinel value represents a valid RWDateTime whose value is not yet determined. For more information about RWDateTime sentinels, see the section on RWDateTime Sentinels in the internationalization chapter of the Essential Tools Module User's Guide.

Synopsis

 #include <rw/tools/datetime.h>
 RWDateTime dt(RWDateTime::setCurrentTime); // construct
                                            // today's date

Persistence

Simple

Examples

 #include <rw/tools/datetime.h>
 #include <iostream>
 
 int main() {
       // Today's date
      RWDateTime dt(RWDateTime::setCurrentTime);
 
      // Last Sunday's date
      RWDateTime lastSunday = dt.previous("Sunday");
 
      std::cout << dt << std::endl << lastSunday << std::endl;
 }

Member Enumeration Documentation

enum RWDateTime::Format

Specifies the format to be used for converting between RWCString and RWDateTime using the ISO 8601 standard. This standard converts any date and time to a locale-nonspecific numeric format.

Enumerator:

iso8601	Uses ISO 8601 standard format.
iso8601_midnight24	Uses ISO 8601 standard format. Formats midnight as hour 24 of the previous day rather than hour 0 of the next day.

enum RWDateTime::InitialState

Specifies whether the constructor should construct an invalid, null, or current RWDateTime. Default is to set an invalid RWDateTime, with an undefined date and time.

Enumerator:

invalid	Constructs Invalid RWDateTime.
null	Constructs null RWDateTime.
setCurrentTime	Constructs RWDateTime consisting of current time.

enum RWDateTime::SetType

Specifies whether the constructor should set just the date, just the time, or both. Default is to set both.

Enumerator:

setDate	Sets the date.
setTime	Sets the time.
setBoth	Sets both the date and the time.

Constructor & Destructor Documentation

RWDateTime::RWDateTime ( InitialState init_state = invalid )

Default constructor. Constructs an RWDateTime with undefined date and time. If init_state is set to RWDateTime::setCurrentTime, an instance with the current date and time is created. If init_state is set to RWDateTime::null, an instance set to null is created.

RWDateTime::RWDateTime ( const RWDateTime & dt ) [inline]

Copy constructor.

RWDateTime::RWDateTime ( rwint64 msec ) [inline, explicit]

Constructs an RWDateTime from the number of milliseconds since 1 January 1901 00:00:00:000 UTC. rwint64 is at least a 64-bit integral type. msec may be negative for representing times prior to midnight 01/01/1901.

RWDateTime::RWDateTime	(	const struct tm *	tmbuf,
		unsigned	msec = `0`,
		const RWZone &	loc = `RWZone::local()`
	)

Constructs an RWDateTime from the tm_year, tm_mon, tm_mday, tm_hour, tm_min, tm_sec components of the struct tm argument, with the milliseconds portion of the RWDateTime as specified by msec. The components are understood to be relative to the time zone passed in, which defaults to local time. Note that the numbering of the months and years in a struct tm differs from that used in RWDateTime arguments, which start at the number 1. The arguments included in struct tm are shown above in the class description.

The constructor tests as a precondition the struct tm pointer which cannot be null. If null, it asserts in debug builds and throws an object of type RWInternalErr in optimized builds.

RWDateTime::RWDateTime	(	const RWTime &	t,
		unsigned	msec = `0`
	)

Deprecated:: This constructor uses the deprecated class RWTime.

Constructs an RWDateTime from the given RWTime using the msec argument for the number of milliseconds.

RWDateTime::RWDateTime	(	const RWDate &	d,
		unsigned	hours = `0`,
		unsigned	minutes = `0`,
		unsigned	seconds = `0`,
		unsigned	msec = `0`,
		const RWZone &	zone = `RWZone::local()`
	)

Deprecated:: This constructor uses the deprecated class RWDate.

Constructs an RWDateTime using the RWDate d and the time h:m:s:ms. The time specified defaults to local time.

RWDateTime::RWDateTime	(	unsigned	month_day,
		const char *	month,
		unsigned	year,
		unsigned	hours,
		unsigned	minutes,
		unsigned	seconds,
		unsigned	msec,
		const RWLocale &	loc = `RWLocale::global()`,
		const RWZone &	zone = `RWZone::local()`
	)

Constructs an RWDateTime using the specified day, month, year, hour, minute, second, and millisecond, all relative to the time zone specified, which defaults to local time. The optional locale argument loc is used to convert the month name.

RWDateTime::RWDateTime	(	unsigned	day,
		unsigned	month,
		unsigned	year,
		unsigned	hours = `0`,
		unsigned	minutes = `0`,
		unsigned	seconds = `0`,
		unsigned	milliseconds = `0`,
		const RWZone &	zone = `RWZone::local()`
	)

Constructs an RWDateTime using the specified day, month, year, hour, minute, second, and millisecond, all relative to the time zone specified, which defaults to local time.

RWDateTime::RWDateTime	(	const RWCString &	str,
		SetType	set_type = `setBoth`,
		const RWLocale &	loc = `RWLocale::global()`,
		const RWZone &	zone = `RWZone::local()`
	)			`[explicit]`

Converts the string str to a date and/or time as indicated by set_type, all relative to the time zone specified, which defaults to local time. By default, both the date and time are set using RWLocale loc. The constructor expects the date and time portions of the RWCString to be separated by a semicolon when both date and time are being set. The locale argument is used to convert the month name.

Because RWLocale cannot rigorously check date input, the member function isValid() must be used to test that the results are a valid date.

Example:

 RWDateTime("April  4,  1998;  10:00  am",
 RWDateTime::setBoth,
 RWLocale::global());    //  sets  date  and  time
 RWDateTime("April  4,  1998",
 RWDateTime::setDate,
 RWLocale::global());    //  sets  date  and  initializes
 //  time  to  00:00:00
 RWDateTime("10:00  am",
 RWDateTime::setTime,
 RWLocale::global());    //  initializes  date  to
 //  today  at  time  10:00

RWDateTime::RWDateTime	(	const RWCString &	str,
		Format	f,
		const RWLocale &	loc = `RWLocale::global()`,
		const RWZone &	zone = `RWZone::local()`
	)

Constructs an RWDateTime from the string str using the format specified by f. RWDateTime currently supports the ISO 8601 format which is numeric and locale-neutral; as such the RWLocale argument is ignored for ISO 8601, but is reserved for future use. The constructor uses the RWZone argument unless the string specifies the UTC timezone or an offset from UTC, in which case the RWZone argument is ignored in favor of UTC. For more information, see the section on applying the ISO standard to timezone offsets, in the internationalization chapter of the Essential Tools Module User's Guide.

Note:: Please note that confusion can occur when using a string that contains only a date or only a time indication, since it is not possible to differentiate between some representations of the two formats. For example. the string 190415 could represent either or both of the following:

date: the 15th day of the 4th month of the 19th year in the default century
time: 19:04:15

You can avoid such confusion by using more explicit formats. For example, you can completely and safely avoid all confusion if you are prepend "T" (allowed by the standard in time-only indications) for all times or if you always use extended formats.

For more information, see the section on applying the ISO standard to timezone offsets, in the internationalization chapter of the Essential Tools Module User's Guide.

Two Examples:

 RWDateTime("April 4, 1998; 10:00 am",
            RWDateTime::setBoth,
            RWLocale::global());  // sets date and time
 RWDateTime("April 4, 1998",
            RWDateTime::setDate,
            RWLocale::global());  // sets date and initializes
                                  // time to 00:00:00

 RWDateTime("10:00 am",
            RWDateTime::setTime,
            RWLocale::global());  // initializes date to  
                                  // today at time 10:00

For a date or time supplied singly (for example, "2001-12-24" or "23:59:59"), RWDateTime calls the system to retrieve the current date or time.

RWDateTime::RWDateTime	(	std::istream &	s,
		SetType	set_type,
		const RWLocale &	loc = `RWLocale::global()`,
		const RWZone &	zone = `RWZone::local()`
	)

Reads a full line and converts it to a date and/or time as indicated by the set_type, all relative to the specified time zone, which defaults to local time. By default, both the date and time are set using the global RWLocale loc. The constructor expects the date and time portions of the RWCString to be separated by a semi-colon when both day and time are being set. The locale argument is used to convert the month name.

Because RWLocale cannot rigorously check date input, the member function isValid() must be used to test that the results are a valid date.

Member Function Documentation

RWCString RWDateTime::asString	(	Format	format,
		const RWLocale &	loc = `RWLocale::global()`,
		const RWZone &	zone = `RWZone::local()`
	)			const

Returns the date and time as a string, using the specified format.

Currently supports the ISO 8601 format. This format is numeric and locale-neutral, and as such does not use the RWLocale argument.

For more information, see the section on international standards for dates and times in the internationalization chapter of the Essential Tools Module User's Guide.

RWCString RWDateTime::asString	(	const char *	format,
		const RWLocale &	loc = `RWLocale::global()`,
		const RWZone &	zone = `RWZone::local()`
	)			const

Returns the date and time as a string, formatted by the optional locale argument. The function defaults to using the RWLocale global locale.

Formats are as defined in the C99 Standard C Library function strftime(), explained in the description for RWLocale.

As a precondition, format is tested to determine if it is a null pointer. If null, the method asserts in debug mode, and throws RWInternalError in optimized builds.

RWCString RWDateTime::asString	(	char	format,
		const RWLocale &	loc = `RWLocale::global()`,
		const RWZone &	zone = `RWZone::local()`
	)			const

Returns the date and time as a string, formatted by the optional locale argument. The function defaults to using the RWLocale global locale.

Formats are as defined in the C99 Standard C Library function strftime(), explained in the description for RWLocale.

static RWDateTime RWDateTime::beginDST	(	unsigned	year,
		const RWZone &	zone = `RWZone::local()`
	)			`[static]`

Returns the start of daylight saving time (DST) for the given year, in the given timezone. Returns an "invalid" time if DST is not observed in that year and zone.

bool RWDateTime::between	(	const RWDateTime &	a,
		const RWDateTime &	b
	)			const

Returns true if self is between a and b, inclusive.

RWspace RWDateTime::binaryStoreSize ( ) const

Returns the number of bytes necessary to store the object using the global function:

 RWFile& operator<<(RWFile&, const RWDateTime&);

Reimplemented in RWCollectableDateTime.

int RWDateTime::compareTo ( const RWDateTime & d ) const [inline]

Compares self to the RWDateTime pointed to by d and returns:

 0  if  self  ==  *d;
 1  if  self  >  *d;
 -1  if  self  <  *d.

int RWDateTime::compareTo ( const RWDateTime * d ) const

Compares self to the RWDateTime referenced by d and returns:

 0 if self  ==   d ;
 1  if  self  >   d ;
 -1  if  self  <   d .

As a precondition, d is tested to determine if it is a null pointer. If null, the method asserts in debug mode, and throws RWInternalError in optimized builds.

unsigned RWDateTime::correctedJulian ( ) const [inline]

Returns the value of the Julian day number. This value is one day less than the value of RWDateTime::julian() if the time is before noon UTC (GMT).

unsigned RWDateTime::day ( const RWZone & zone = RWZone::local() ) const

Returns the day of the year (1-366) for this date. The default for the optional timezone argument is local.

unsigned RWDateTime::dayGMT ( ) const

Returns the day of the year (1-366) for this date relative to UTC (GMT).

unsigned RWDateTime::dayOfMonth ( const RWZone & zone = RWZone::local() ) const

Returns the day of the month (1-31) for this date. The default for the optional timezone argument is local.

unsigned RWDateTime::dayOfMonthGMT ( ) const

Returns the day of the month (1-31) for this date relative to UTC (GMT).

static unsigned RWDateTime::dayOfWeek	(	const char *	day,
		const RWLocale &	loc = `RWLocale::global()`
	)			`[static]`

Returns the number of the day of the week corresponding to the given day, where Monday = 1, ..., Sunday = 7. Names are interpreted according to the optional locale argument. The function defaults to using the RWLocale global locale.

As a precondition, day is tested to determine if it is a null pointer. If null, the method asserts in debug mode, and throws RWInternalError in optimized builds.

static unsigned RWDateTime::daysInMonthYear	(	unsigned	month,
		unsigned	year
	)			`[static]`

Returns the number of days in a given month and year. Returns 0 if month is not between 1 and 12 inclusive.

static unsigned RWDateTime::daysInYear ( unsigned year ) [static]

Returns the number of days in a given year.

static bool RWDateTime::dayWithinMonth	(	unsigned	month,
		unsigned	day,
		unsigned	year
	)			`[static]`

Returns true if day (1-31) is within a given month in a given year.

RWDateTime & RWDateTime::decrementDay ( const rwint64 d ) [inline]

Decrements the class's milliseconds data member by d * millisecsInDay(), then returns self.

Note:: if this operation results in crossing a DST boundary in the instance's timezone, outputting the date will present with a DST offset as well.

RWDateTime & RWDateTime::decrementHour ( const rwint64 h ) [inline]

Decrements the class's milliseconds data member by h * millisecsInHour(), then returns self.

Note:: If this operation results in crossing a DST boundary in the instance's timezone, outputting the date will present with a DST offset as well.

RWDateTime & RWDateTime::decrementMillisecond ( const rwint64 msec ) [inline]

Decrements the class's milliseconds data member by msec, then returns self.

Note:: If this operation results in crossing a DST boundary in the instance's timezone, outputting the date will present with a DST offset as well.

RWDateTime & RWDateTime::decrementMinute ( const rwint64 m ) [inline]

Decrements the class's milliseconds data member by m * millisecsInMin(), then returns self.

Note:: If this operation results in crossing a DST boundary in the instance's timezone, outputting the date will present with a DST offset as well.

RWDateTime & RWDateTime::decrementSecond ( const rwint64 s ) [inline]

Decrements the class's milliseconds data member by s * millisecsInSec(), then returns self.

Note:: If this operation results in crossing a DST boundary in the instance's timezone, outputting the date will present with a DST offset as well.

static RWDateTime RWDateTime::endDST	(	unsigned	year,
		const RWZone &	zone = `RWZone::local()`
	)			`[static]`

Returns the end of daylight saving time for the given year, in the given timezone. Returns an "invalid time" if DST is not observed in that year and zone.

void RWDateTime::extract	(	struct tm *	tmbuf,
		const RWZone &	zone = `RWZone::local ()`
	)			const `[inline]`

Returns with the struct tm argument filled out completely. Note that the encoding for months and days of the week used in struct tm differs from that used elsewhere in RWDateTime. If the date is a sentinel, the function throws an exception of type RWInternalErr.

As a precondition, tmbuf is tested to determine if it is a null pointer. If null, the method asserts in debug mode, and throws RWInternalError in optimized builds.

void RWDateTime::extractGMT ( struct tm * tmbuf ) const [inline]

Returns with the struct tm argument filled out completely, relative to UTC (GMT). Note that the encoding for months and days of the week used in struct tm differs from that used elsewhere in RWDateTime. If the date is a sentinel, the function throws an exception of type RWInternalErr.

As a precondition, tmbuf is tested to determine if it is a null pointer. If null, the method asserts in debug mode, and throws RWInternalError in optimized builds.

unsigned RWDateTime::firstDayOfMonth ( const RWZone & zone = RWZone::local () ) const [inline]

Returns the day of the year (1-366) corresponding to the first day of the month and year for this RWDateTime.

unsigned RWDateTime::firstDayOfMonth	(	unsigned	mon,
		const RWZone &	zone = `RWZone::local()`
	)			const

Returns the day of the year (1-366) corresponding to the first day of mon of the year for this RWDateTime. The default for the optional timezone argument is local.

static unsigned RWDateTime::hash ( const RWDateTime & dt ) [inline, static]

Returns the hash value of dt as returned by dt.hash() .

unsigned RWDateTime::hash ( ) const

Returns a suitable hashing value.

Reimplemented in RWCollectableDateTime.

unsigned RWDateTime::hour ( const RWZone & zone = RWZone::local() ) const

Returns the hour relative to the timezone specified. The default for the optional timezone argument is local.

unsigned RWDateTime::hourGMT ( ) const [inline]

Returns the hour relative to UTC (GMT).

RWDateTime & RWDateTime::incrementDay ( const rwint64 d ) [inline]

Increments the class's milliseconds data member by d * millisecsInDay(), then returns self.

Note:: If this operation results in crossing a DST boundary in the instance's timezone, outputting the date will present with a DST offset as well.

RWDateTime & RWDateTime::incrementHour ( const rwint64 h ) [inline]

Increments the class's milliseconds data member by h * millisecsInHour(), then returns self.

Note:: If this operation results in crossing a DST boundary in the instance's timezone, outputting the date will present with a DST offset as well.

RWDateTime & RWDateTime::incrementMillisecond ( const rwint64 msec ) [inline]

Increments the class's milliseconds data member by msec, then returns self.

Note:: If this operation results in crossing a DST boundary in the instance's timezone, outputting the date will present with a DST offset as well.

RWDateTime & RWDateTime::incrementMinute ( const rwint64 m ) [inline]

Increments the class's milliseconds data member by m * millisecsInMin(), then returns self.

Note:: If this operation results in crossing a DST boundary in the instance's timezone, outputting the date will present with a DST offset as well.

RWDateTime & RWDateTime::incrementSecond ( const rwint64 s ) [inline]

Increments the class's milliseconds data member by s * millisecsInSec(), then returns self.

Note:: If this operation results in crossing a DST boundary in the instance's timezone, outputting the date will present with a DST offset as well.

static unsigned RWDateTime::indexOfMonth	(	const char *	monthName,
		const RWLocale &	loc = `RWLocale::global()`
	)			`[static]`

Returns a number between 1 and 12 corresponding to the given month name monthName. Returns 0 for no match. Months are interpreted by the optional locale argument. The function defaults to using the RWLocale global locale.

As a precondition, monthName is tested to determine if it is a null pointer. If null, the method asserts in debug mode, and throws RWInternalError in optimized builds.

bool RWDateTime::isDST ( const RWZone & zone = RWZone::local() ) const

Returns true if self is during daylight saving time in the timezone given by zone, false otherwise.

bool RWDateTime::isFuture ( ) const [inline]

Returns true if self is a future sentinel.

bool RWDateTime::isInvalid ( ) const [inline]

Returns true if self is an invalid sentinel.

bool RWDateTime::isNull ( void ) const [inline]

Returns true if self is a null sentinel.

bool RWDateTime::isPast ( ) const [inline]

Returns true if self is a past sentinel.

bool RWDateTime::isSentinel ( ) const [inline]

Returns true if self is a sentinel of any kind.

bool RWDateTime::isValid ( void ) const [inline]

Returns true if self represents an actual time or is the null sentinel, false otherwise.

void RWDateTime::julian ( unsigned j )

Sets the value of the Modified Julian day number to j.

unsigned RWDateTime::julian ( ) const [inline]

Returns the value of the Modified Julian day number.

void RWDateTime::julianDay ( double j )

Sets the value of the date and time to the Modified Julian day number j. The integer/whole number part of the double indicates the day, and the fractional part indicates the time. For example, the Julian day number for 1/1/1901 is 2415386. Since Julian days start at midnight GMT, 12 a.m. is 2415386.5 and 6 p.m. is 2415386.75 (these values are interpreted differently in RWDateTime objects that have different timezones).

double RWDateTime::julianDay ( ) const

Returns the value of the current date and time as a Modified Julian day number. The integer/whole number part of the double indicates the day, and the fractional part indicates the time. For example, the Modified Julian day number for 1/1/1901 is 2415386. Since Modified Julian days start at midnight GMT, 12 a.m. is 2415386.5 and 6 p.m. is 2415386.75 (these values are computed for the Greenwich meridian - a different timezone modifies the result of julianDay).

bool RWDateTime::leap ( const RWZone & zone = RWZone::local () ) const [inline]

Returns true if self is a leap year relative to the RWZone argument.

bool RWDateTime::leapGMT ( ) const [inline]

Returns true if self is a leap year relative to UTC (GMT).

static bool RWDateTime::leapYear ( unsigned year ) [static]

Returns true if a given year is a leap year.

RWDateTime RWDateTime::max ( const RWDateTime & t ) const [inline]

Returns the later RWDateTime of self or t.

unsigned RWDateTime::milliSecond ( ) const

Returns the millisecond part of self.

rwint64 RWDateTime::milliSeconds ( ) const [inline]

Returns the number of milliseconds since 00:00:00:000 January 1, 1901 UTC.

RWDateTime RWDateTime::min ( const RWDateTime & t ) const [inline]

Returns the earlier RWDateTime of self or t.

unsigned RWDateTime::minute ( const RWZone & zone = RWZone::local() ) const

Returns the minute, adjusted to the timezone specified.

unsigned RWDateTime::minuteGMT ( ) const [inline]

Returns the minute relative to UTC (GMT).

unsigned RWDateTime::month ( const RWZone & zone = RWZone::local() ) const

Returns the month (1-12) for this date. The default for the optional timezone argument is local.

unsigned RWDateTime::monthGMT ( ) const

Returns the month (1-12) for this date relative to UTC (GMT).

RWCString RWDateTime::monthName	(	const RWLocale &	loc = `RWLocale::global()`,
		const RWZone &	zone = `RWZone::local()`
	)			const

Returns the name of the month for this date, according to the optional locale argument. The function defaults to using the RWLocale global locale.

static RWCString RWDateTime::nameOfMonth	(	unsigned	monthNum,
		const RWLocale &	loc = `RWLocale::global()`
	)			`[static]`

Returns the name of month, where January = 1, ..., December = 12. Months are interpreted by the optional locale argument. The function defaults to using the RWLocale global locale.

RWDateTime RWDateTime::next	(	const char *	dayName,
		const RWLocale &	loc = `RWLocale::global()`,
		const RWZone &	zone = `RWZone::local()`
	)			const

Returns the date of the next dayName (for example, the date of the next Monday). The weekday name is interpreted according to the optional locale argument.

As a precondition, dayName is tested to determine if it is a null pointer. If null, the method asserts in debug mode, and throws RWInternalError in optimized builds.

RWDateTime RWDateTime::next	(	unsigned	dayNum,
		const RWZone &	zone = `RWZone::local()`
	)			const

Returns the date of the next day of the week, where Monday = 1, ..., Sunday = 7. The variable dayNum must be between 1 and 7, inclusive. The default for the optional timezone argument is local.

static RWDateTime RWDateTime::now ( ) [inline, static]

Returns current date and time.

RWDateTime& RWDateTime::operator= ( const RWDateTime & )

Assignment operator.

RWDateTime RWDateTime::previous	(	const char *	dayName,
		const RWLocale &	loc = `RWLocale::global()`,
		const RWZone &	zone = `RWZone::local()`
	)			const

Returns the day of the previous dayName; for example, the date of the previous Monday. The weekday name is interpreted according to the optional locale argument. The function defaults to using the RWLocale global locale.

RWDateTime RWDateTime::previous	(	unsigned	dayNum,
		const RWZone &	zone = `RWZone::local()`
	)			const

Returns the date of the previous numbered day of the week, where Monday = 1, ..., Sunday = 7. The variable dayNum must be between 1 and 7, inclusive. The default for the optional timezone argument is local.

std::istream& RWDateTime::readDate ( std::istream & is )

Reads a full line and converts to a date according to the locale imbued on the stream. The member function isValid() must be used to test whether the results are a valid date.

std::istream& RWDateTime::readTime ( std::istream & is )

Reads a full line and converts it to a time according to the locale imbued on the stream. The member function isValid() must be used to test whether the results are a valid time.

void RWDateTime::restoreFrom ( RWvistream & )

Restores an instance of RWDateTime from a reference to a virtual stream into which an instance has been persisted using the method saveOn(RWvostream&)const.

void RWDateTime::restoreFrom ( RWFile & )

Restores an instance of RWDateTime from a reference to an RWFile into which an instance has been persisted using the method saveOn(RWFile&)const.

void RWDateTime::saveOn ( RWvostream & ) const

Saves an instance of RWDateTime to the indicated virtual stream. The RWDateTime can be restored using the method restoreFrom(RWvistream&).

void RWDateTime::saveOn ( RWFile & ) const

Saves an instance of RWDateTime to the indicated RWFile object reference. The RWDateTime can be restored using the method restoreFrom(RWFile&).

unsigned RWDateTime::second ( const RWZone & zone = RWZone::local() ) const

Returns the second, adjusted to the timezone specified.

unsigned RWDateTime::secondGMT ( ) const [inline]

Returns the second relative to UTC (GMT).

RWDate RWDateTime::toRWDate ( const RWZone & zone = RWZone::local() ) const

Converts self to an RWDate.

RWTime RWDateTime::toRWTime ( ) const

Converts self to an RWTime.

static RWDateTime RWDateTime::userSentinel ( int n ) [static]

Returns user-defined sentinel number n.

Exceptions:

RWBoundsErr

Thrown if the argument is outside the range 0 to 127.

unsigned RWDateTime::weekDay ( const RWZone & zone = RWZone::local() ) const

Returns the number of the day of the week for this date, where Monday = 1, ..., Sunday = 7.

unsigned RWDateTime::weekDayGMT ( ) const [inline]

Returns the number of the day of the week for this date relative to UTC (GMT).

static RWCString RWDateTime::weekDayName	(	unsigned	dayNum,
		const RWLocale &	loc = `RWLocale::global()`
	)			`[static]`

Returns the name of the day of the week dayNum where Monday = 1, ..., Sunday = 7. Days are interpreted by the optional locale argument. The function defaults to using the RWLocale global locale.

RWCString RWDateTime::weekDayName	(	const RWLocale &	loc = `RWLocale::global()`,
		const RWZone &	zone = `RWZone::local()`
	)			const

Returns the name of the day of the week for this date, according to the optional locale argument. The function defaults to using the RWLocale global locale.

std::ostream& RWDateTime::writeDate ( std::ostream & os ) const

Outputs the date on the std::ostream os, according to the locale imbued on the stream.

std::ostream& RWDateTime::writeTime ( std::ostream & os ) const

Outputs the time on the std::ostream os, according to the locale imbued on the stream.

unsigned RWDateTime::year ( const RWZone & zone = RWZone::local() ) const

Returns the year of self. The default for the optional timezone argument is local.

unsigned RWDateTime::yearGMT ( ) const

Returns the year of self relative to UTC (GMT).

Friends And Related Function Documentation

bool operator!=	(	const RWDateTime &	d1,
		const RWDateTime &	d2
	)			`[related]`

Returns true if d1 is not the same as d2.

RWDateTime operator+	(	rwint64	s,
		const RWDateTime &	d
	)			`[friend]`

Returns the date s milliseconds in the future from the date d.

RWDateTime operator+	(	const RWDateTime &	d,
		rwint64	s
	)			`[friend]`

Returns the date s milliseconds in the future from the date d.

rwint64 operator-	(	const RWDateTime &	dt1,
		const RWDateTime &	dt2
	)			`[friend]`

Returns the number of milliseconds between dt1 and dt2.

Exceptions:

RWInternalErr

Thrown if either dt1 or dt2 is a sentinel.

RWDateTime operator-	(	const RWDateTime &	d,
		rwint64	s
	)			`[friend]`

Returns the date s milliseconds in the past from d.

bool operator<	(	const RWDateTime &	d1,
		const RWDateTime &	d2
	)			`[related]`

Returns true if d1 is before d2.

RWFile & operator<<	(	RWFile &	file,
		const RWDateTime &	t
	)			`[related]`

Saves t to an RWFile.

RWvostream & operator<<	(	RWvostream &	str,
		const RWDateTime &	t
	)			`[related]`

Saves t to a virtual stream.

std::ostream& operator<<	(	std::ostream &	s,
		const RWDateTime &	dt
	)			`[friend]`

Outputs the date and time stored in dt on std::ostream s, according to the locale imbued on the stream.

bool operator<=	(	const RWDateTime &	d1,
		const RWDateTime &	d2
	)			`[related]`

Returns true if d1 is before or the same as d2.

bool operator==	(	const RWDateTime &	d1,
		const RWDateTime &	d2
	)			`[related]`

Returns true if d1 is the same as d2.

bool operator>	(	const RWDateTime &	d1,
		const RWDateTime &	d2
	)			`[related]`

Returns true if d1 is after d2.

bool operator>=	(	const RWDateTime &	d1,
		const RWDateTime &	d2
	)			`[related]`

Return true if d1 is after or the same as d2.

RWFile & operator>>	(	RWFile &	file,
		RWDateTime *&	t
	)			`[related]`

Restores an RWDateTime from an RWFile by allocating an RWDateTime on the heap and restoring its state.

RWvistream & operator>>	(	RWvistream &	str,
		RWDateTime *&	t
	)			`[related]`

Restores an RWDateTime from a virtual stream by allocating an RWDateTime on the heap and restoring its state.

RWFile & operator>>	(	RWFile &	file,
		RWDateTime &	t
	)			`[related]`

Restores t from an RWFile, replacing the previous contents of t.

RWvistream & operator>>	(	RWvistream &	str,
		RWDateTime &	t
	)			`[related]`

Restores t from a virtual stream, replacing the previous contents of t.

std::istream& operator>>	(	std::istream &	s,
		RWDateTime &	dt
	)			`[friend]`

Reads dt from std::istream s. The function reads one full line, and the string it contains is converted according to the locale imbued on the stream. The function isValid() must be used to test whether the results are a valid date.