IDate

IDate represents specified dates. It returns language-sensitive information, such as names of days and months, in the language defined by the user's system. It also provides general day-handling and date-handling functions. Externally, dates are composed of :

Internally, dates are stored a true Julian date, i.e. the number of days from January 1, 4713 B.C, taking into account the Gregorian reforms. The day offset is stored as an unsigned long value, so it can represent dates up to approximately 11,700,000 year A.D.

The Open Class Library also lets you specify the day within the year.


IDate - Member Functions and Data by Group

Constructors & Destructor

You can construct objects of this class in the following ways:


[view class]
IDate
This constructor creates a date object from a number of different types of date specifications.


Overload 1
Constructs an IDate from the year and day of the year.
public:
IDate(int aYear, int aDay)

Use this constructor to create an IDate from the year and day of the year. The day of year is the number of days starting at January 1.

aYear
The year to construct from. The passed day must be a legal day within this year.
aDay
The day within the year to construct from.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IDate(Month aMonth, int aDay, int aYear)

Use this constructor to pass parameters in month/day/year order.

aYear
The year to construct from. The passed day must be a legal day within this year and month.
aMonth
The month within the passed year to construct from.
aDay
The day within the month to construct from.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
Constructs an IDate by copying another IDate object.
public:
IDate(const IDate& aDate)

Use this constructor to create an IDate by copying another IDate object.

aDate
The source IDate object to copy construct from.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
Constructs a date object from a Julian day number.
public:
IDate(unsigned long julianDayNumber)

Use this constructor to create an IDate from a Julian day number, as a long.

julianDayNumber
The Julian date to construct from.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
Constructs an IDate from an ICnrDate structure.
public:
IDate(const ICnrDate& cnrDate)

Use this constructor to create an IDate from a container details ICnrDate structure.

cnrDate
The ICnrDate object to construct from.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 6
public:
IDate(int aDay, Month aMonth, int aYear)

Use this constructor to construct a date object from parameters specified in day/month/year order.

aYear
The year to construct from. The passed day must be a legal day within this year and month.
aMonth
The month within the passed year to construct from.
aDay
The day within the month to construct from.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 7
Creates a date object containing the current day.
public:
IDate()

Use this constructor to return the current day; it's the default.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Comparisons

Use these members to compare two IDates. Use any of the full complement of comparison operators and apply the natural meaning.


[view class]
operator !=
Compares two date objects for inequality.
public:
bool operator !=(const IDate& aDate) const
This function compares this object to another date object for inequality.

aDate
The other date object to compare to this one for inequality.

Return
true if this object is not equal to the passed object, else false.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator <
public:
bool operator <(const IDate& aDate) const
This function compares this object to another date object for relative magnitude.

aDate
The date to compare to this object for relative magnitude.

Return
true if this object represents a date prior to the passed date.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator <=
public:
bool operator <=(const IDate& aDate) const
This function compares this object to another date object for relative magnitude or equality.

aDate
The date to compare to this object for relative magnitude or equality.

Return
true if this object represents a date prior to or equal to the passed date.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator ==
public:
bool operator ==(const IDate& aDate) const
This function compares this object to another object for equality.

aDate
The other date object to compare to this one for equality.

Return
true if this object is equal to the passed date object, else false.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator >
Compares two data objects.
public:
bool operator >(const IDate& aDate) const
This function compares this object to another date object for relative magnitude.

aDate
The date to compare to this object for relative magnitude.

Return
true if this object represents a date subsequent to the passed date.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator >=
public:
bool operator >=(const IDate& aDate) const
This function compares this object to another date object for relative magnitude or equality.

aDate
The date to compare to this object for relative magnitude or equality.

Return
true if this object represents a date subsequent to or equal to the passed date.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Conversions

Use these members to retrieve other representations of the date.


[view class]
asICnrDate
Returns a container ICnrDate structure.
public:
ICnrDate asICnrDate() const
This function returns a container ICnrDate structure for this date.

Return
An ICnrDate structure with this object's date information in it.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
julianDate
Returns the Julian day number of this object.
public:
unsigned long julianDate() const
This function returns the Julian day number of this object. The function uses the true definition of a Julian date, which means it returns the number of days from January 1, 4713 B.C.

Return
The Julian date of this object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Current Date

Use this member when you need the current date.


[view class]
today
public:
static IDate today()

This function returns the current date. This static function can be used as an IDate constructor.

Return
A date object representing today.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Day Queries

Use these members to access the day portion of an IDate object.


[view class]
dayName
This function returns the name of the day of week, either of this object's date or of a passed day of week enum.


Overload 1
Returns the name of the day of week.
public:
static IString dayName(DayOfWeek aDay)

aDay
The day of week whose formatted name to get.

Return
Returns an IString object with the formatted day name.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Returns the name of the weekday.
public:
IString dayName() const

Return
An IString object with the formatted day name.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
dayOfMonth
Returns the day of the month as an integer.
public:
int dayOfMonth() const
This function returns the day in the receiver's month as an integer from 1 to 31.

Return
Returns the day of the month index.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
dayOfWeek
Returns the index of the day of the week for the current object.
public:
DayOfWeek dayOfWeek() const
This function returns the index of this object's day of the week: Monday through Sunday.

Return
Returns the day of the week enumeration value of this date.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
dayOfYear
Returns the day in the receiver's year as an integer.
public:
int dayOfYear() const
This function returns the day in the receiver's year as an integer from 1 to 366.

Return
Returns the day of the year of this date.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Diagnostics

These members provide an IString representation for an IDate object and have the capability to output the object to a stream. The formats include both mm-dd-yy and strftime conversion specifications. Often, you use these members to write trace information when debugging.


[view class]
asString
This function returns the IDate as a string. By default, the string is formatted according to the system specification (mm-dd-yy).


Overload 1
Returns the date as a string.
public:
IString asString(const char* fmt) const
Use this function to format the date using a string of formatting parameters. These parameters give you total control over the fields to be formatted and where they are placed.

fmt
Gives the conversion specifier, which is a character string you can use to describe how to format the date. Use the date specifiers that are valid in the C function strftime. The conversion specifiers that apply to IDate and their meanings are listed in the following table.

ITime::asString provides the conversion specifiers that apply to ITime. For more information about the strftime function, refer to the VisualAge for C++: C Library Reference:

Specifier Meaning
%a Insert abbreviated weekday name of locale.
%A Insert full weekday name of locale.
%b Insert abbreviated month name of locale.
%B Insert full month name of locale.
%c Insert date and time of locale.
%d Insert day of the month (01-31).
%j Insert day of the year (001-366).
%m Insert month (01-12).
%U Insert week number of the year (00-53) where Sunday is the first day of the week.
%w Insert weekday (0-6) where Sunday is 0.
%W Insert week number of the year (00-53) where Monday is the first day of the week.
%x Insert date representation of locale.
%y Insert year without the century (00-99).
%Y Insert year with the century (e.g. 1998).

Return
asString returns a string with the formatted date text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Returns the date as a string.
public:
IString asString(YearFormat yearFmt = yy) const
Use this function to format the date using one of a set of standard formats represented by the YearFormat enum.

yearFmt
Specifies how the system should display the year. If you do not specify the format, the default is yy. Use the enumeration IDate::YearFormat for valid values.

Return
An IString with the formatted date text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

OS/2 Considerations

To obtain locale-sensitive result, you must enable locale-based string operation by calling IString::enableInternationalization().

Windows Considerations

To obtain locale-sensitive result, you must enable locale-based string operation by calling IString::enableInternationalization().


General Date Queries

These members are static. They provide general IDate utilities independent of specific IDates. Typically, you use them to determine calendar information or to convert IDate enumeration data to string values.


[view class]
daysInMonth
public:
static int daysInMonth(Month aMonth, int aYear)
This function returns the number of days in a specified month of a specified year. You must specify the year in yyyy format, that is, not relative to 1900.

aMonth
The month whose days to get.
aYear
The year within which the month falls. Specify this value in yyyy format, that is, not relative to 1900.

Return
Returns the number of days in the indicated month.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
daysInYear
Returns the number of days in the given year.
public:
static int daysInYear(int aYear)
This function returns the number of days in a specified year. You must specify the year in in yyyy format, that is, not relative to 1900.

aYear
The year whose days to get. You must specify this value in yyyy format, that is, not relative to 1900.

Return
The days in the indicated year

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Implementation

These members initialize an IDate object.


[view class]
initialize
protected:
IDate& initialize(Month aMonth, int aDay, int aYear)
This function calculates the Julian day number and sets this object's date to that Julian date.

aYear
The year to initialize from. The passed day must be a legal day within this year and month.
aMonth
The month within the passed year to initialize from.
aDay
The day within the month to initialize from.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Manipulation

Use these members to update an IDate object using addition or subtraction of another IDate object. Use any of the full complement of addition or subtraction operators and apply the natural meaning.


[view class]
operator +
public:
IDate operator +(int numDays) const
This function adds an integral number of days to the left-hand operand, yielding a new IDate which is returned by value.

numDays
The number of days to add to this object to create the return value.

Return
A new date object with the resulting date.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator +=
Adds a number of days to the date object.
public:
IDate& operator +=(int numDays)
This function adds the given number of days to this date object.

numDays
An integer specifying the number of days to add to this date object.

Return
A reference to this object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator -
This function subtracts an integral number of days from the left-hand operand, yielding a new IDate. If the right-hand operand is also an IDate, the operator returns the number of days between the dates. If the right-hand operand is a number of days, then the operator returns a new date object representing the resulting date.


Overload 1
public:
IDate operator -(int numDays) const

numDays
The number of days to subtract from this date to create the return value.

Return
A date representing this date minus the number of days passed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
long operator -(const IDate& aDate) const

aDate
The date to subtract from this object.

Return
The number of days in between this date and the passed date.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator -=
Subtracts a number of days from the date object.
public:
IDate& operator -=(int numDays)
This function subtracts the given number of days from this date object.

numDays
An integer specifying the number of days to subtract from this date object.

Return
A reference to this object

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Month Queries

Use these members to access the month portion of an IDate object.


[view class]
monthName
This function returns the name of the month of either this object's month, or of a passed month enumeration value.


Overload 1
public:
static IString monthName(Month aMonth)

aMonth
The month whose name to format.

Return
The name of the passed month.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Returns the name of the month.
public:
IString monthName() const

Return
The name of the month of this object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
monthOfYear
Returns the index of this object's month.
public:
Month monthOfYear() const
This function returns the index of this object's month of the year: January through December.

Return
The month of the year of this object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Streaming Operators

Use these members to stream IData objects.


[view class]
operator <<=
public:
void operator <<=(IDataStream& fromWhere)
This function streams this object in from the passed data stream. Any existing content is overwritten by the streamed in information.

fromWhere
The stream to stream this object in from.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator >>=
public:
void operator >>=(IDataStream& toWhere)
This function streams this date object out to the passed data stream.

toWhere
The stream to stream this object out to.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Validation

Use these static members to validate the passed-date data. They test the validity of a given day and provide a leap year test for a given year.


[view class]
isLeapYear
public:
static bool isLeapYear(int aYear)
This function returns a Boolean indicating whether the specified year is a leap year. You must specify the year in yyyy format, that is, not relative to 1900.

aYear
The year to test for leap year. You must specify this value in yyyy form, that is, not relative to 1900.

Return
true if the passed year is a leap year, else false.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isValid
This function indicates whether the specified date is valid. You must specify the year in yyyy format, that is, not relative to 1900.


Overload 1
Determines whether the specified date is valid.
public:
static bool isValid(int aYear, int aDay)
Use this function to determine if the date is valid for a date that you pass in as a year and day.

aYear
The year to test for validity. You must specify this value in yyyy form, that is, not relative to 1900.
aDay
The day within the year to test for validity.

Return
true if the passed year and day are valid, else false.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
static bool isValid(int aDay, Month aMonth, int aYear)
Use this function to determine if the date is valid for a date that you pass in as a day, month, and year.

aYear
The year to test for validity. You must specify this value in yyyy form, that is, not relative to 1900.
aMonth
The month within the passed year to test for validity.
aDay
The day within the month to test for validity.

Return
true if the passed day, month, and year are valid, else false.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
static bool isValid(Month aMonth, int aDay, int aYear)
Use this function to determine whether a date is valid for a date you pass in as a month, a day, and a year.

aYear
The year to test for validity. You must specify this value in yyyy form, that is not relative to 1900.
aMonth
The month within the passed year to test for validity.
aDay
The day within the month to test for validity.

Return
true if the passed month, day, and year are valid, else false.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Year Queries

Use this member to access the year portion of an IDate object.


[view class]
year
public:
int year() const
This function returns the receiver's year. The returned value is in the yyyy format.

Return
The year of this object's date.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IDate - Type Definitions


[view class]
Month
typedef enum { January = 1 , February , March , April , May , June , July , August , September , October , November , December } Month

A typedef that provides the values January through December for the months of the year.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
DayOfWeek
typedef enum { Monday = 0 , Tuesday , Wednesday , Thursday , Friday , Saturday , Sunday } DayOfWeek

A typedef that provides the values Monday through Sunday for the days of the week.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
YearFormat
typedef enum { yy , yyyy } YearFormat

A typedef that specifies the number of digits in the year for the default asString format (yy or yyyy).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IDate - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

IDate

Inherited Protected Functions

IDate

Inherited Protected Data