Rogue Wave banner
Previous fileTop of DocumentContentsIndex pageNext file
Essential Tools Module User's Guide

3.5 RWDateTime

An RWDateTime may be constructed in several ways. Unlike RWDate and RWTime, described in Section 3.6 and Section 3.7 below, the RWDateTime default constructor does not automatically set the time and date to the current time and date. This change provides an efficient way to construct large arrays of RWDateTime. The current time and date can still be set by using a constructor. Simply include the enum RWDateTime::setCurrentTime in RWDateTime's constructor argument list. See the Essential Tools Module Reference Guide for a complete description of RWDateTime.

For example, to construct an RWDateTime with today's date and current time, use the following:

An RWDateTime can also be constructed from a given date and/or a given time. Or you can use an RWDateTime constructor that takes a string and the enum RWDateTime::SetType, which indicates whether you are setting a date, a time, or both. By default, the constructor expects to set both the date and time. For example, to construct an RWDateTime for a given date, where time is of no concern, use:

Similarly, to construct an RWDateTime for a given time:

Finally, to construct an RWDateTime for a given date and time, you can use the following techniques. Note that when you initialize both the day and time, the date precedes the time and the two values are separated by a semicolon.

or

3.5.1 Member Functions

Class RWDateTime has member functions to compare, store, add, and subtract RWDateTimes. An RWDateTime may return specific time units (days, hours, seconds), or fill a struct tm for any time zone. A complete list of member functions appears in the Essential Tools Module Reference Guide.

For example, here is a code fragment that outputs the hour in local and UTC (GMT) zones, and then the complete local time and date.

3.5.2 RWDateTime Sentinels

RWDateTime has the ability to hold sentinel values that are not necessarily dates, but are convenient to use as comparison values within applications. For example, a "future" sentinel provides a value that represents a date larger than the largest RWDateTime. RWDateTime currently provides four internal, pre-defined sentinels and can accommodate up to 128 user-defined sentinels. The RWDateTime sentinels are described in the following sections.

Table 8 summarizes the responses of RWDateTime operations when applied to various sentinels. The sections that follow Table 8 provide more information about the sentinels.

Table 8: RWDateTime sentinels  

Operator/Function Valid Null Invalid Past/Future User Sentinel
Extract Part

Ok

RWTHROW

RWTHROW

RWTHROW

RWTHROW

Arithmetic

Ok

Propagate to Invalid

Propagate

Propagate Past/Future

Propagate to Invalid

Relational

Ok

Return False

RWTHROW

Ok

Return False

asString()/Output

Ok

"NULL"

"#INVALID#"

"#INVALID#"

"#<num>#"

Read String

Ok

N/A

Ok

N/A

N/A

Create

Ok

Ok

Ok

Ok

Ok

3.5.2.1 The "Invalid" Sentinel

The Essential Tools Module includes an RWDateTime with an "invalid" state that can be compared to other RWDateTime objects for equality, and can be persisted. The default RWDateTime constructor constructs an object with an "invalid" state, and other construction techniques are available, including an RWDateTime::invalidSentinel constant. You can pass this constant to the RWDateTime(rwint64) constructor to create instances of the minimum and maximum RWDateTime as needed, or you can use it to compare directly with the millisecond count returned by RWDateTime::milliSeconds().

No other operations work, other than persisting the invalid object and using it in comparisons for equality. Arithmetic manipulation of an invalid RWDateTime always results in an invalid RWDateTime. Attempts to use other relational operators or any part extraction functions (day(), month(), extract(), etc.) results in an RWInternalErr being thrown by RWTHROW. The asString() family of functions always returns the string "#INVALID#" when called with an invalid RWDateTime.

The following examples show several ways to construct an RWDateTime with an invalid state:

3.5.2.2 The "Null" Sentinel

Sometimes it is convenient to have an RWDateTime that is valid yet holds no specific value. The Essential Tools Module includes the "null" state sentinel for this purpose. You can construct a null RWDateTime or use the constant RWDateTime::nullSentinel in construction by passing the constant RWDateTime::nullSentinel to the RWDateTime(rwint64) constructor. You can also use the constant in direct comparisons with the millisecond count returned by RWDateTime::milliSeconds().

Arithmetic manipulation of a null RWDateTime will result in an invalid RWDateTime being returned. Relational operations involving null RWDateTimes and valid RWDateTimes always return False. Attempts to use any part extraction functions(day(), month(), extract(), etc.) will result in an RWInternalErr being thrown by RWTHROW. The asString() family of functions will always return the string NULL when called for a null RWDateTime.

The following examples show how to construct an RWDateTime with a null state, and demonstrate what happens when it is used in an arithmetic operation:

3.5.2.3 The Past and Future Sentinels

When sorting and searching for RWDateTime objects it is useful to have sentinels that represent "smaller than the smallest" RWDateTime and "larger than the largest" RWDateTime. The "past" and "future" sentinels are special kinds of invalid sentinels.

RWDateTime includes two global static constants to determine the minimum and maximum valid RWDateTime objects: RWDateTime::minDateTime and RWDateTime::maxDateTime. You can pass these constants to the RWDateTime(rwint64) constructor to create instances of the minimum and maximum RWDateTime as needed, or you can use them to compare directly with the millisecond count returned by RWDateTime::milliSeconds().

The past and future sentinels can be used in any relational operation, and every valid RWDateTime falls strictly between the past and future sentinels. Arithmetic manipulation of past or future sentinels will not change their values, nor cause any error. Attempts to use any part extraction functions (day(), month(), extract(), etc.) will result in an RWInternalErr being thrown by RWTHROW. The asString() family of functions always returns the string "#INVALID#" for past and future sentinels.

Here are some examples of constructing and using past and future sentinels:

3.5.2.4 User-Defined Sentinels

RWDateTime also provides for the use of 128 user-defined sentinels numbered 0 through 127. Each of these sentinels behave like the null sentinel for part extraction functions, arithmetic manipulation, and relational operations. The asString() family of functions returns "#<num>#" where num is the user sentinel number. The static method RWDateTime::userSentinel(int) is available for constructing user sentinels. These can be used to define different kind of dates, such as "refused", for cases where a user has declined to enter data in a date field.

Here is an example of constructing and using user-defined sentinels:



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.