Rogue Wave banner
Previous fileTop of DocumentContentsIndex pageNext file
Essential Tools Module Reference Guide

RWDateTime

Module:  Essential Tools Module   Group:  Date and Time


Does not inherit

Local Index

Members

Non-Members

Synopsis

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

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 now supports the ISO 8601 international standard for the formatting of dates and times. For information and formatting syntax, see Section 3.3, "International Standards for Dates and Times," in the User's Guide.

RWDateTime is based on the Gregorian Calendar, and its range extends for thousands of years beyond that of 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 was 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 User's Guide provides more information.


NOTE -- The modern Modified Julian Day (MJD) was introduced in the 1950's and starts at midnight, as opposed to the historic Julian Day (JD), which began at 12 noon. It 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 the Essential Tools Module RWDateTime function correctly from Modified Julian day 0, but can only be converted to month, date, year for Modified Julian days that fall within the Gregorian Calendar.

Note that two-digit year specifiers assume the century 1900, so you will want to create programs that use four-digit year specifiers.

RWDateTime can be converted to and from RWTimes and RWDates. Because of the greater accuracy and range, RWDateTime is the preferred class to use for dates and times. RWDateTimes can also be converted to and from the Standard C Library type struct tm defined in <time.h>,and listed here in Table 17.

Table 17: Elements of 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:

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 it is applied to hold 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 Section 3.5.2, "RWDateTime Sentinels," in the User's Guide.

Persistence

Simple

Example

Program output:

Enumeration

enum
RWDateTime::InitialState { invalid, null, setCurrentTime }
enum
RWDateTime::setType { setDate, setTime, setBoth }
enum 
RWDateTime::Format { iso8601 };

Static Const Data Members

static const rwint64 RWDateTime::futureSentinel
static const rwint64 RWDateTime::invalidSentinel
static const rwint64 RWDateTime::maxDateTime
static const rwint64 RWDateTime::millisecsInDay
static const rwint64 RWDateTime::millisecsInHour
static const rwint64 RWDateTime::millisecsInMin
static const rwint64 RWDateTime::millisecsInSec
static const rwint64 RWDateTime::minDateTime
static const rwint64 RWDateTime::nullSentinel
static const rwint64 RWDateTime::pastSentinel 
static const rwint64 RWDateTime::userSentinelStart 

Public Constructors

RWDateTime(InitialState init_state = invalid);  
RWDateTime(const RWDateTime& dt);
explicit RWDateTime(rwint64 msec);
RWDateTime(const struct tm*, unsigned msec = 0,
           const RWZone& = RWZone::local());
RWDateTime(unsigned, const char* month, unsigned year, 
           unsigned h, unsigned m, unsigned s,
           unsigned ms, 
           const RWLocale& loc = RWLocale::global(),
           const RWZone& zone = RWZone::local());
RWDateTime(unsigned day, unsigned month, unsigned year, 
           unsigned h=0, unsigned m=0, unsigned s=0,
           unsigned ms=0, const RWZone& = RWZone::local());
RWDateTime(const RWCString& str, SetType set_type 
           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(const RWTime& t, unsigned msec=0);
RWDateTime(const RWCString& Format, unsigned h=0, unsigned m=0, 
           unsigned s=0, unsigned ms=0,
           const RWZone& = RWZone::local());
RWDateTime(const RWCString&, Format,
           const RWLocale& = RWLocale::global(),
           const RWZone&   = RWZone::local());

Operators

RWDateTime&
operator=(const RWDateTime&);

Public Member Functions

RWCString
asString(char format, 
         const RWLocale& loc = RWLocale::global(),
         const RWZone& = RWZone::local()) const;
RWCString
asString(const char* format, 
         const RWLocale& loc = RWLocale::global()
         const RWZone& = RWZone::local()) const;
RWCString 
asString(Format f,
const RWLocale& loc = RWLocale::global(),
const RWZone& = 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; 

NOTE -- The method correctedJulian() is the only RWDateTime method that uses the original Julian day number, instead of the Modified Julian day number.
unsigned 
day(const RWZone& = RWZone::local()) const; 
unsigned
dayGMT() const; 
unsigned 
dayOfMonth(const RWZone& = RWZone::local()) const; 
unsigned
dayOfMonthGMT();
RWDateTime& 
decrementHour(const rwint64 hour); 
RWDateTime& 
decrementMillisecond(const rwint64 msec);
RWDateTime& 
decrementMinute(const rwint64 minute); 
RWDateTime& 
decrementSecond((const rwint64 second); 

NOTE -- The decrement operations can cause RWDateTime to cross a Daylight Saving Time boundary; if so, the returned RWDateTime will have a daylight-saving offset.
void 
extract(struct tm* tmbuf, 
        const RWZone& = RWZone::local()) const; 
void 
extractGMT(struct tm* tmbuf) const; 
unsigned
firstDayOfMonth(unsigned mon, 
                const RWZone& = RWZone::local()) const; 
unsigned
firstDayOfMonth(const RWZone& = RWZone::local()) const;
unsigned
hash() const; 
unsigned
hour(const RWZone& = RWZone::local())  const;
unsigned
hourGMT() const;
RWDateTime& 
incrementHour(const rwint64 hour); 
RWDateTime&
incrementMillisecond(const rwint64 msec);
RWDateTime& 
incrementMinute(const rwint64 minute); 
RWDateTime& 
incrementSecond(const rwint64 second);

NOTE -- The increment operations can cause RWDateTime to cross a Daylight Saving Time boundary; if so, the returned RWDateTime will have a daylight-saving offset.
bool
isDST(const RWZone& = RWZone::local()) const; 
bool
isFuture() const;
bool
isInvalid() const;
bool
isNull() const;
bool
isPast() const;
bool
isSentinel() const;
bool
isValid() const;

NOTE -- The next four functions let you manipulate the date via Modified Julian days. 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 User's Guide provides more information.
unsigned
julian() const; 
void
julian(unsigned j);
double
julianDay() const;
void
julianDay(double j);
bool
leap(const RWZone& = RWZone::local()) const; 
bool 
leapGMT();
RWDateTime
max(const RWDateTime& t) const; 
unsigned
milliSecond() const; 
rwint64
milliSeconds() const; 
RWDateTime
min(const RWDateTime& t) const; 
unsigned
minute(const RWZone& = RWZone::local()) const; 
unsigned 
minuteGMT() const; 
unsigned
month(const RWZone& = RWZone::local()) const; 
unsigned
monthGMT() const; 
RWCString
monthName(const RWLocale loc, 
          const RWZone& = RWZone::local()) const;
RWDateTime
next(unsigned dayNum, const RWZone& = RWZone::local()) const; 
RWDateTime
next(const char* dayName,
     const RWLocale loc = RWLocale::global();
     const RWZone& = RWZone::local()) const;
RWDateTime
previous(unsigned dayNum, 
         const RWZone& = RWZone::local()) const; 
RWDateTime
previous(const char* dayName, 
const RWLocale& loc = RWLocale::global(),
const RWZone& = RWZone::local()const;
std::istream&
readDate(std::istream& is); 
std::istream&
readTime(std::istream& is); 
void 
restoreFrom(RWFile&);
void 
restoreFrom(RWvistream&);
void 
saveOn(RWFile&) const;
void 
saveOn(RWvostream&) const;
unsigned
second() const; 
RWDate
toRWDate(const RWZone& = RWZone::local()) const; 
RWTime
toRWTime() const; 
unsigned
weekDay(const RWZone& = RWZone::local()) const; 
unsigned
weekDayGMT() const; 
RWCString
weekDayName(const RWLocale& loc = RWLocale::global(),
            const RWZone& = RWZone::local()) const;
std::ostream&
writeDate(std::ostream& os); 
std::ostream&
writeTime(std::ostream& os); 
unsigned
year(const RWZone& = RWZone::local()) const; 
unsigned 
yearGMT() const; 

Static Public Member Functions

static RWDateTime
beginDST(unsigned year, const RWZone& = RWZone::local());
static unsigned
dayOfWeek(const char* day,
   const RWLocale& loc = RWLocale::global());
static unsigned
daysInMonthYear(unsigned month, unsigned year); 
static unsigned
daysInYear(unsigned year); 
static bool
dayWithinMonth(unsigned month, unsigned day, unsigned year) ;
static RWDateTime
endDST(unsigned year, const RWZone& = RWZone::local());
static unsigned
hash(const RWDateTime& dt);
static unsigned
indexOfMonth(const char* month,
   const RWLocale& loc = RWLocale::global());
static bool
leapYear(unsigned year); 
static RWCString
nameOfMonth(unsigned monthNum,
   const RWLocale& loc = RWLocale::global());
static RWDateTime
now();
static RWDateTime
userSentinel(int n);
static RWCString
weekDayName(unsigned dayNum, 
            const RWLocale& loc = RWLocale::global());

Related Global Operators

rwint64
operator-(const RWDateTime &dt1, const RWDateTime &dt2);
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);
RWDateTime
operator+(const RWDateTime& d, rwint64 s);
RWDateTime
operator+(rwint64 s, const RWDateTime& d);
RWDateTime
operator-(const RWDateTime& d, rwint64 s);
std::ostream&
operator<<(std::ostream& s, const RWDateTime& dt); 
std::istream&
operator>>(std::istream& s, RWDateTime& dt); 
RWvostream&
operator<<(RWvostream&, const RWDateTime& dt);
RWFile&
operator<<(RWFile&,const RWDateTime& dt);
RWvistream&
operator>>(RWvistream&, RWDateTime& dt);
RWFile&
operator>>(RWFile&, RWDateTime& dt);
RWvistream&
operator>>(RWvistream&, RWDateTime*& dt);
RWFile&
operator>>(RWFile&, RWDateTime*& dt);


Previous fileTop of DocumentContentsIndex pageNext file

©2004 Copyright Quovadx, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Quovadx, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.