rwsf::DateTime
Group: General- Local Index
- Header File
- Description
- Example
- Enumerations
- Static Constant Data Members
- Public Constructors
- Operators
- Public Member Functions
- Static Public Member Functions
- Related Global Operators
Local Index
Members
Non-Members
Header File
#include <rwsf/core/DateTime.h>
Description
Class rwsf::DateTime 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 rwsfint64.
rwsf::DateTime supports the ISO 8601 international standard for the formatting of dates and times.
rwsf::DateTime is based on the Gregorian Calendar. 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. rwsf::DateTime 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.
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 rwsf::DateTime 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.
rwsf::DateTimes can be converted to and from the Standard C Library type struct tm defined in <time.h>,and listed here in Table 2.
Table 2: 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, which facilitates creating a large array, as follows:
// Creates an array with 5000 undefined dates and times rwsf::DateTime v[5000];
rwsf::DateTime 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 rwsf::DateTime whose value is not yet determined.
Example
#include <rwsf/core/DateTime.h>
#include <iostream>
int main() {
// Today's date
rwsf::DateTime dt(rwsf::DateTime::setCurrentTime);
// Last Sunday's date
rwsf::DateTime lastSunday = dt.previous("Sunday");
std::cout << dt.asString('c').data() << std::endl;
std::cout << lastSunday.asString('c').data()
<< std::endl;
}
Program output:
12/22/04 09:00:08 12/19/04 09:00:08
Enumerations
enum
InitialState { invalid, null, setCurrentTime }
Specifies whether the constructor should construct an invalid, null, or current rwsf::DateTime. Default is to set an invalid rwsf::DateTime, with an undefined date and time.
enum
setType { setDate, setTime, setBoth }
Specifies whether the constructor should set just the date, just the time or both. Default is to set both.
enum
Format { iso8601, http };
Specifies the format to be used for converting between std::string and rwsf::DateTime using either the ISO 8601 standard, or HTTP specification date formats.
enum
ImplType { implDouble, implLong };
Static Constant Data Members
static const rwsfint64 DateTime::futureSentinel
Sentinel values representing future rwsf::DateTimes.
static const rwsfint64 DateTime::invalidSentinel
Sentinel values for invalid rwsf::DateTime sentinels.
static const rwsfint64 DateTime::maxDateTime
The maximum number of milliseconds that an rwsf::DateTime may hold.
static const rwsfint64 DateTime::millisecsInDay
The number of milliseconds in a day.
static const rwsfint64 DateTime::millisecsInHour
The number of milliseconds in a hour.
static const rwsfint64 DateTime::millisecsInMin
The number of milliseconds in a minute.
static const rwsfint64 DateTime::millisecsInSec
The number of milliseconds in a second.
static const rwsfint64 DateTime::minDateTime
The minimum number of milliseconds that an rwsf::DateTime may hold.
static const rwsfint64 DateTime::nullSentinel
Sentinel values for null rwsf::DateTime sentinels.
static const rwsfint64 DateTime::pastSentinel
Sentinel values representing past rwsf::DateTimes.
static const rwsfint64 DateTime::userSentinelStart
The starting value for user-defined sentinels.
static const rwsfint64 DateTime::jday0
The millisecond count at noon on Julian day zero.
static const rwsfint64 DateTime::midnightJday0
The millisecond count at midnight on Julian day zero.
Public Constructors
DateTime(InitialState init_state = invalid);
Default constructor. Constructs an rwsf::DateTime with undefined date and time. If init_state is set to DateTime::setCurrentTime, an instance with the current date and time is created. If init_state is set to DateTime::null, an instance set to null is created.
DateTime(const DateTime& dt);
Copy constructor.
DateTime(rwsfint64 msec);
Constructs an rwsf::DateTime from the number of milliseconds since 1 January 1901 00:00:00:000 UTC. rwsfint64 is at least a 64 bit integral type. msec may be negative for representing times prior to midnight 01/01/1901. Note: This constructor must be passed an instance of a rwsfint64 to ensure unambiguous construction.
For example, here is how to construct an rwsf::DateTime representing a time 230,375 milliseconds after midnight UTC on 01/01/1901:
rwsf::DateTime correct(rwsfint64(230375));// correct rwsf::DateTime incorrect(230375) // Error! Ambiguous
DateTime(const struct tm*, unsigned ms=0,
const rwsf::TimeZone& = rwsf::TimeZone::local());
Constructs an rwsf::DateTime 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 rwsf::DateTime as specified by ms. 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 rwsf::DateTime arguments, which start at the number 1. The arguments included in struct tm are shown above in Table 2.
DateTime(unsigned, const char* month, unsigned year,
unsigned h, unsigned m, unsigned s,
unsigned ms,
const rwsf::Locale& loc = rwsf::Locale::global(),
const rwsf::TimeZone& zone = rwsf::TimeZone::local());
Constructs an rwsf::DateTime 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 is used to convert the month name.
DateTime(unsigned day, unsigned month, unsigned year,
unsigned h=0, unsigned m=0, unsigned s=0,
unsigned ms=0,
const rwsf::TimeZone& = rwsf::TimeZone::local());
Constructs an rwsf::DateTime using the specified day, month, year, hour, minute, second, and millisecond, all relative to the time zone specified, which defaults to local time.
DateTime(const std::string& str, SetType set_type = setBoth,
const rwsf::Locale& loc = rwsf::Locale::global(),
const rwsf::TimeZone& zone = rwsf::TimeZone::local());
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 rwsf::Locale locale. The constructor expects the date and time portions of the std::string to be separated by a semicolon when both date and time are being set. The locale argument is used to convert the month name. The member function isValid() must be used to test whether the results are a valid date. Because rwsf::Locale cannot rigorously check date input, dates created this way should also be recon-firmed by the user.
Example:
rwsf::DateTime("April 4, 1998; 10:00 am",
rwsf::DateTime::setBoth,
rwsf::Locale::global()); // sets date and time
rwsf::DateTime("April 4, 1998",
rwsf::DateTime::setDate,
rwsf::Locale::global()); // sets date and
// initializes time to 00:00:00
rwsf::DateTime("10:00 am",
rwsf::DateTime::setTime,
rwsf::Locale::global()); // initializes date to
// today at time 10:00
DateTime(const std::string& str, Format f,
const rwsf::Locale& loc = rwsf::Locale::global(),
const rwsf::TimeZone& zone = rwsf::TimeZone::
local());
Constructs an rwsf::DateTime from the string str using the format specified by f. rwsf::DateTime currently supports the ISO 8601 format which is numeric and locale-neutral; as such the rwsf::Locale argument is ignored for ISO 8601, but is reserved for future use. The constructor uses the rwsf::TimeZone argument unless the string specifies the UTC time zone or an offset from UTC, in which case the rwsf::TimeZone argument is ignored in favor of UTC.
Two Examples:
// Construct an rwsf::DateTime of 11:59:59 PM on December
// 24th,2001 in the rwsf::TimeZone::local() time zone.
rwsf::DateTime("2001-12-24T23:59:59",
rwsf::DateTime::iso8601);
P
// Construct an rwsf::DateTime of 8 AM, April 12th, 1985 in
// the GMT time zone
rwsf::DateTime("1985-04-12T08:00:00Z",
rwsf::DateTime::iso8601);
For a date or time supplied singly (for example, "2001-12-24" or "23:59:59"), rwsf::DateTime calls the system to retrieve the current date or time.
Operators
DateTime& operator=(const DateTime& dt);
Assignment operator.
Public Member Functions
std::string
asString(char format,
const rwsf::Locale& loc = rwsf::Locale::global(),
const rwsf::TimeZone& = rwsf::TimeZone::
local()) const;
Returns the date and time as a string, formatted by the optional locale argument. The function defaults to using the rwsf::Locale global locale.
Formats are as defined in the pre-1999 Standard C Library function strftime(), explained in the description for rwsf::Locale.
std::string
asString(const char* format,
const rwsf::Locale& loc = rwsf::Locale::global()
const rwsf::TimeZone& = rwsf::TimeZone::local()) const;
Returns the date and time as a string, formatted by the optional locale argument. The function defaults to using the rwsf::Locale global locale.
Formats are as defined in the pre-1999 Standard C Library function strftime(), explained in the description for rwsf::Locale.
std::string asString(Format f,
const rwsf::Locale& loc = rwsf::Locale::global(),
const rwsf::TimeZone& = rwsf::TimeZone::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 rwsf::Locale argument.
bool between(const DateTime& a, const DateTime& b) const;
Returns true if self is between a and b, inclusive.
int compareTo(const DateTime& dt) const;
Compares self to the rwsf::DateTime referenced by dt and returns:
0 if self == d;
1 if self > d;
-1 if self < d.
int compareTo(const DateTime* dt) const;
Compares self to the rwsf::DateTime pointed to by dt and returns:
0 if self == *d;
1 if self > *d;
-1 if self < *d.
unsigned correctedJulian() const;
Returns the value of the Julian day number. This value is one day less than the value of DateTime::julian() if the time is before noon UTC (GMT).
NOTE -- The method correctedJulian() is the only rwsf::DateTime method that uses the original Julian day number, instead of the Modified Julian day number.
unsigned day(const rwsf::TimeZone& = rwsf::TimeZone::local()) const;
Returns the day of the year (1-366) for this date. Default for optional time zone argument is local.
unsigned dayGMT() const;
Returns the day of the year (1-366) for this date relative to UTC (GMT).
unsigned dayOfMonth(const rwsf::TimeZone& = rwsf::TimeZone::local()) const;
Returns the day of the month (1-31) for this date. Default for optional time zone argument is local.
unsigned dayOfMonthGMT();
Returns the day of the month (1-31) for this date relative to UTC (GMT).
DateTime& decrementHour(const rwsfint64 hour);
Decrements the class's milliseconds data member by hour*DateTime::millisecsInHour, then returns self. Note: If this operation results in crossing a DST boundary in the instance's time zone, outputting the date will present with a DST offset as well.
DateTime&
decrementMillisecond(const rwsfint64 millisecond);
Decrements the classes' milliseconds data member by millisecond, then returns self. Note: If this operation results in crossing a DST boundary in the instance's time zone, outputting the date will present with a DST offset as well.
DateTime& decrementMinute(const rwsfint64 minute);
Decrements the classes' milliseconds data member by minute*DateTime::millisecsInMin, then returns self. Note: If this operation results in crossing a DST boundary in the instance's time zone, outputting the date will present with a DST offset as well.
DateTime& decrementSecond((const rwsfint64 second);
Decrements the classes' milliseconds data member by second*DateTime::millisecsInSec, then returns self. Note: if this operation results in crossing a DST boundary in the instance's time zone, outputting the date will present with a DST offset as well.
NOTE -- The decrement operations can cause rwsf::DateTime to cross a Daylight Saving Time boundary; if so, the returned rwsf::DateTime will have a daylight-saving offset.
void
extract(struct tm* tmbuf,
const rwsf::TimeZone& = rwsf::TimeZone::
local()) const;
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 rwsf::DateTime. If the date is invalid, all fields are set to -1. Default for optional time zone argument is local.
void extractGMT(struct tm* tmbuf) const;
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 rwsf::DateTime. If the date is invalid, all fields are set to -1.
unsigned
firstDayOfMonth(unsigned mon,
const rwsf::TimeZone& = rwsf::TimeZone::
local()) const;
Returns the day of the year (1-366) corresponding to the first day of mon in this rwsf::DateTime's year. Default for optional time zone argument is local.
unsigned firstDayOfMonth(const rwsf::TimeZone& = rwsf::TimeZone::
local()) const;
Returns the day of the year (1-366) corresponding to the first day of this rwsf::DateTime's month and year.
unsigned hash() const;
Returns a suitable hashing value.
unsigned hour(const rwsf::TimeZone& = rwsf::TimeZone::local()) const;
Returns the hour relative to the time zone specified. Default for optional time zone argument is local.
unsigned hourGMT() const;
Returns the hour relative to UTC (GMT).
DateTime& incrementHour(const rwsfint64 hour);
Increments the class' milliseconds data member by hour*DateTime::millisecsInHour, then returns self. Note: If this operation results in crossing a DST boundary in the instance's time zone, outputting the date will present with a DST offset as well.
DateTime&
incrementMillisecond(const rwsfint64 millisecond);
Increments the class' milliseconds data member by millisecond, then returns self. Note: If this operation results in crossing a DST boundary in the instance's time zone, outputting the date will present with a DST offset as well.
DateTime& incrementMinute(const rwsfint64 minute);
Increments the classes' milliseconds data member by minute*DateTime::millisecsInMin, then returns self. Note: If this operation results in crossing a DST boundary in the instance's time zone, outputting the date will present with a DST offset as well.
DateTime& incrementSecond(const rwsfint64 second);
Increments the classes' milliseconds data member by second*DateTime::millisecsInSec, then returns self. Note: If this operation results in crossing a DST boundary in the instance's time zone, outputting the date will present with a DST offset as well.
NOTE -- The increment operations can cause rwsf::DateTime to cross a Daylight Saving Time boundary; if so, the returned rwsf::DateTime will have a daylight-saving offset.
bool isDST(const rwsf::TimeZone& = rwsf::TimeZone::local()) const;
Returns true if self is during daylight saving time in the time zone given by zone, false otherwise.
bool isFuture() const;
Returns true if self is a future sentinel.
bool isInvalid() const;
Returns true if self is an invalid sentinel.
bool isNull() const;
Returns true if self is a null sentinel.
bool isPast() const;
Returns true if self is a past sentinel.
bool isSentinel() const;
Returns true if self is a sentinel of any kind.
bool isValid() const;
Returns true if self represents an actual time or is the null sentinel, false otherwise.
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.
unsigned julian() const;
Returns the value of the Modified Julian day number.
void julian(unsigned j);
Sets the value of the Modified Julian day number to j.
double 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 Greenwich meridian - a different time zone modifies the result of julianDay).
void 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 rwsf::DateTime objects that have different time zones).
bool leap(const rwsf::TimeZone& = rwsf::TimeZone::local()) const;
Returns true if self is a leap year relative to the rwsf::TimeZone argument.
bool leapGMT();
Returns true if self is a leap year relative to UTC (GMT).
DateTime max(const DateTime& t) const;
Returns the later rwsf::DateTime of self or t.
DateTime min(const DateTime& t) const;
Returns the earlier rwsf::DateTime of self or t.
unsigned milliSecond() const;
Returns the millisecond part of self.
rwsfint64 milliSeconds() const;
Returns the number of milliseconds since 00:00:00:000 January 1, 1901 UTC.
unsigned minute(const rwsf::TimeZone& = rwsf::TimeZone::local()) const;
Returns the minute, adjusted to the time zone specified.
unsigned minuteGMT() const;
Returns the minute relative to UTC (GMT).
unsigned month(const rwsf::TimeZone& = rwsf::TimeZone::local()) const;
Returns the month (1-12) for this date. Default for optional time zone argument is local.
unsigned monthGMT() const;
Returns the month (1-12) for this date relative to UTC (GMT).
std::string
monthName(const rwsf::Locale loc,
const rwsf::TimeZone& = rwsf::TimeZone::
local()) const;
Returns the name of the month for this date, according to the optional locale argument. The function defaults to using the rwsf::Locale global locale.
DateTime next(unsigned dayNum, const rwsf::TimeZone& = rwsf::TimeZone::
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. Default for optional time zone argument is local.
DateTime
next(const char* dayName,
const rwsf::Locale loc = rwsf::Locale::global();
const rwsf::TimeZone& = rwsf::TimeZone::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.
DateTime
previous(unsigned dayNum,
const rwsf::TimeZone& = rwsf::TimeZone::local()) const;
Returns the date of the previous numbered day of the week, where Monday = 1, ..., Sunday = 7. The variable dayNum must be between 1and 7, inclusive. Default for optional time zone argument is local.
DateTime previous(const char* dayName,
const rwsf::Locale& loc = rwsf::Locale::global(),
const rwsf::TimeZone& = rwsf::TimeZone::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 rwsf::Locale global locale.
unsigned second() const;
Returns the second; local time or UTC (GMT).
unsigned weekDay(const rwsf::TimeZone& = rwsf::TimeZone::local()) const;
Returns the number of the day of the week for this date, where Monday = 1, ..., Sunday = 7.
unsigned weekDayGMT() const;
Returns the number of the day of the week for this date relative to UTC (GMT).
std::string
weekDayName(const rwsf::Locale& loc = rwsf::Locale::global(),
const rwsf::TimeZone& = rwsf::TimeZone::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 rwsf::Locale global locale.
unsigned year(const rwsf::TimeZone& = rwsf::TimeZone::local()) const;
Returns the year of self. Default for optional time zone argument is local.
unsigned yearGMT() const;
Returns the year of self relative to UTC (GMT).
Static Public Member Functions
static DateTime beginDST(unsigned year, const rwsf::TimeZone& =
rwsf::TimeZone::local());
Returns the start of daylight saving time (DST) for the given year, in the given time zone. Returns an "invalid" time if DST is not observed in that year and zone.
static unsigned
dayOfWeek(const char* day,
const rwsf::Locale& loc = rwsf::Locale::global());
Returns the number of the day of the week corresponding to the given day name, where Monday = 1, ..., Sunday = 7. Names are interpreted according to the optional locale argument. The function defaults to using the rwsf::Locale global locale.
static unsigned daysInMonthYear(unsigned month, unsigned year);
Returns the number of days in a given month and year. Returns 0 if month is not between 1 and 12 inclusive.
static unsigned daysInYear(unsigned year);
Returns the number of days in a given year.
static bool dayWithinMonth(unsigned month, unsigned day, unsigned yr) ;
Returns true if a day (1-31) is within a given month in a given year.
static DateTime
endDST(unsigned year,const
rwsf::TimeZone&=rwsf::TimeZone::local());
Returns the end of daylight saving time for the given year, in the given time zone. Returns an "invalid time" if DST is not observed in that year and zone.
static unsigned hash(const DateTime& dt);
Returns the hash value of dt as returned by dt.hash().
static unsigned
indexOfMonth(const char* month,
const rwsf::Locale& loc = rwsf::Locale::global());
Returns a number between 1 and 12 corresponding to the given month name. Returns 0 for no match. Months are interpreted by the optional locale argument. The function defaults to using the rwsf::Locale global locale.
static bool leapYear(unsigned year);
Returns true if a given year is a leap year.
static std::string
nameOfMonth(unsigned monthNum,
const rwsf::Locale& loc = rwsf::Locale::global());
Returns the name of month, where January = 1, ..., December = 12. Months are interpreted by the optional locale argument. The function defaults to using the rwsf::Locale global locale.
static DateTime now();
Returns current date and time.
static DateTime userSentinel(int i);
Returns user-defined sentinel number i. Throws rwsf::OutOfBoundsException if the argument is outside the range 0 to 127.
static std::string
weekDayName(unsigned dayNum,
const rwsf::Locale& loc = rwsf::Locale::global());
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 rwsf::Locale global locale.
Related Global Operators
rwsfint64 operator-(const DateTime &dt1, const DateTime &dt2);
Returns the number of milliseconds between dt1 and dt2.
bool operator<(const DateTime& t1, const DateTime& t2);
Returns true if t1 is before t2.
bool operator<=(const DateTime& l, const DateTime& r);
Returns true if l is before or the same as r.
bool operator>(const DateTime& l, const DateTime& r);
Returns true if l is after r.
bool operator>=(const DateTime& l, const DateTime& r);
Return true if l is after or the same as r.
bool operator==(const DateTime& t1, const DateTime& t2);
Returns true if t1 is the same as t2.
bool operator!=(const DateTime& l, const DateTime& r);
Returns true if l is not the same as r.
DateTime operator+(const DateTime& dt, rwsfint64 ms); DateTime operator+(rwsfint64 ms, const DateTime& dt);
Returns the date ms milliseconds in the future from the date dt.
DateTime operator-(const DateTime& dt, rwsfint64 ms);
Returns the date ms milliseconds in the past from dt.
©2004-2007 Copyright Quovadx, Inc. All Rights Reserved.
Quovadx and Rogue Wave are registered trademarks and HydraSDO is a trademark 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.