Abstract base class managing a calendar date. More...

#include <ilog/calendar.h>

Inheritance diagram for IlCalendar:

Public Types
enum	EAmpm { AM, PM }
	Constants for the hour in a 12-hour clock. More...

enum	EDaysOfWeek { SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY }
	Constants for days of the week. More...

enum	EMonths { JANUARY, FEBRUARY, MARCH, APRIL, MAY, JUNE, JULY, AUGUST, SEPTEMBER, OCTOBER, NOVEMBER, DECEMBER, UNDECIMBER }
	Constants for the month. More...

enum	IlDateFields { ERA, YEAR, MONTH, WEEK_OF_YEAR, WEEK_OF_MONTH, DATE, DAY_OF_YEAR, DAY_OF_WEEK, DAY_OF_WEEK_IN_MONTH, AM_PM, HOUR, HOUR_OF_DAY, MINUTE, SECOND, MILLISECOND, ZONE_OFFSET, DST_OFFSET }
	Field IDs for date and time. More...

Public Member Functions
virtual	~IlCalendar ()
	Destructor.

virtual void	add (IlDateFields field, IlInt amount, IlDateErrorCode &status)=0
	An arithmetic function for `IlDate` type. This function adds the specified (signed) amount of time to the given time field, based on the calendar rules. More...

void	adoptTimeZone (IlTimeZone *value)
	Sets the calendar time zone to be the one passed in. More...

IlBoolean	after (const IlCalendar &when, IlDateErrorCode &status) const
	Returns `IlTrue` if this `IlCalendar` current time is after when current time. More...

IlBoolean	before (const IlCalendar &when, IlDateErrorCode &status) const
	Returns `IlTrue` if this `IlCalendar` current time is before when current time. More...

void	clear ()
	Clears the values of all the time fields, making them both unset and assigning them a value of zero. More...

void	clear (IlDateFields field)
	Clears the value in the given time field, both making it unset and assigning it a value of zero. More...

virtual IlCalendar *	clone () const =0
	Creates and returns a polymorphic copy of this calendar.

IlBoolean	equals (const IlCalendar &when, IlDateErrorCode &status) const
	Compares the `IlCalendar` time, whereas `IlCalendar::operator==` compares the equality of `IlCalendar` objects. More...

virtual IlBoolean	equivalentTo (const IlCalendar &other) const
	Returns `IlTrue` if another `IlCalendar` object is equivalent to this one. More...

virtual IlInt	fieldDifference (IlDate when, IlDateFields field, IlDateErrorCode &status)
	Returns the difference between the given time and the time this calendar object is set to. More...

IlInt	get (IlDateFields field, IlDateErrorCode &status) const
	Indicates the value for a given time field. More...

IlInt	getActualMaximum (IlDateFields field, IlDateErrorCode &status) const
	Returns the maximum value that this field could have, given the current date. More...

IlInt	getActualMinimum (IlDateFields field, IlDateErrorCode &status) const
	Returns the minimum value that this field could have, given the current date. More...

EDaysOfWeek	getFirstDayOfWeek () const
	Returns the first day of the week; for example, Sunday in US, Monday in France. More...

virtual IlInt	getGreatestMinimum (IlDateFields field) const =0
	Indicates the highest minimum value for the given field if it varies. More...

virtual IlInt	getLeastMaximum (IlDateFields field) const =0
	Indicates the lowest maximum value for the given field if it varies. More...

virtual IlInt	getMaximum (IlDateFields field) const =0
	Indicates the maximum value for the given time field. More...

IlUChar	getMinimalDaysInFirstWeek () const
	Indicates the minimal days required in the first week of the year. More...

virtual IlInt	getMinimum (IlDateFields field) const =0
	Indicates the minimum value for the given time field. More...

IlDate	getTime (IlDateErrorCode &status) const
	Gets this `IlCalendar` time as milliseconds. More...

const IlTimeZone &	getTimeZone () const
	Returns a reference to the time zone owned by this calendar. More...

virtual IlBoolean	inDaylightTime (IlDateErrorCode &status) const =0
	Queries if the current date for this `IlCalendar` is in Daylight Savings Time. More...

IlBoolean	isLenient () const
	Indicates whether the date/time interpretation is lenient. More...

IlBoolean	isSet (IlDateFields field) const
	Determines if the given time field has a value set. More...

IlBoolean	operator!= (const IlCalendar &that) const
	Compares the inequality of two `IlCalendar` objects. More...

virtual IlBoolean	operator== (const IlCalendar &that) const
	Compares the equality of two `IlCalendar` objects. More...

IlTimeZone *	orphanTimeZone ()
	Returns the time zone owned by this calendar. More...

void	roll (IlDateFields field, IlBoolean up, IlDateErrorCode &status)
	Time Field Rolling function: rolls (up/down) a single unit of time on the given time field. More...

virtual void	roll (IlDateFields field, IlInt amount, IlDateErrorCode &status)=0
	Time Field Rolling function: rolls the given amount on the given time field. More...

void	set (IlDateFields field, IlInt value)
	Sets the given time field with the given value. More...

void	set (IlInt year, IlInt month, IlInt date)
	Sets the values for the fields `YEAR`, `MONTH`, and `DATE`. More...

void	set (IlInt year, IlInt month, IlInt date, IlInt hour, IlInt minute)
	Sets the values for the fields `YEAR`, `MONTH`, `DATE`, `HOUR_OF_DAY`, and `MINUTE`. More...

void	set (IlInt year, IlInt month, IlInt date, IlInt hour, IlInt minute, IlInt second)
	Sets the values for the fields `YEAR`, `MONTH`, `DATE`, `HOUR_OF_DAY`, `MINUTE`, and `SECOND`. More...

void	setFirstDayOfWeek (EDaysOfWeek value)
	Sets the first day of the week; for example, Sunday in US, Monday in France. More...

void	setLenient (IlBoolean lenient)
	Specifies whether or not the date/time interpretation is to be lenient. More...

void	setMinimalDaysInFirstWeek (IlUChar value)
	Sets the minimal days required in the first week of the year. More...

void	setTime (IlDate date, IlDateErrorCode &status)
	Sets this `IlCalendar` current time with the given `IlDate`. More...

void	setTimeZone (const IlTimeZone &zone)
	Sets the calendar time zone to be the same as the one passed in. More...

Static Public Member Functions
static IlCalendar *	createInstance (IlDateErrorCode &success)
	Creates an `IlCalendar` that uses the default time zone and locale. More...

static IlCalendar *	createInstance (IlTimeZone *zoneToAdopt, IlDateErrorCode &success)
	Creates an `IlCalendar` using the given time zone and the default locale. More...

static IlCalendar *	createInstance (const IlTimeZone &zone, IlDateErrorCode &success)
	Creates an `IlCalendar` using the given time zone and the default locale. More...

static IlCalendar *	createInstance (const IlLocale &aLocale, IlDateErrorCode &success)
	Creates an `IlCalendar` using the default time zone and the given locale. More...

static IlCalendar *	createInstance (IlTimeZone *zoneToAdopt, const IlLocale &aLocale, IlDateErrorCode &success)
	Creates an `IlCalendar` using the given time zone and locale. More...

static IlCalendar *	createInstance (const IlTimeZone &zoneToAdopt, const IlLocale &aLocale, IlDateErrorCode &success)
	Gets an `IlCalendar` using the given time zone and given locale. More...

static IlDate	getNow ()
	Returns the current UTC (GMT) time measured in milliseconds since `0:00:00` on `1/1/70` (derived from the system time). More...

Protected Member Functions
	IlCalendar (IlDateErrorCode &success)
	Constructs an `IlCalendar` with the default time zone and locale. More...

	IlCalendar (const IlCalendar &source)
	Copy constructor. More...

	IlCalendar (IlTimeZone *zone, const IlLocale &locale, IlDateErrorCode &success)
	Initializes a new `IlCalendar` with the given time zone and locale. More...

	IlCalendar (const IlTimeZone &zone, const IlLocale &locale, IlDateErrorCode &success)
	Initializes a new `IlCalendar` with the given time zone and locale. More...

void	complete (IlDateErrorCode &status)
	Recomputes the current time from currently set fields. More...

virtual void	computeFields (IlDateErrorCode &status)=0
	Converts GMT as milliseconds to time field values. More...

virtual void	computeTime (IlDateErrorCode &status)=0
	Converts `IlCalendar` time field values to GMT, in milliseconds. More...

double	getTimeInMillis (IlDateErrorCode &status) const
	Gets this `IlCalendar` current time as a long. More...

IlInt	internalGet (IlDateFields field) const
	Gets the value for a given time field. More...

IlDate	internalGetTime () const

void	internalSet (IlDateFields field, IlInt value)
	Sets the value for a given time field. More...

void	internalSetTime (IlDate time)

IlCalendar &	operator= (const IlCalendar &right)
	The default assignment operator.

void	setTimeInMillis (double millis, IlDateErrorCode &status)
	Sets this `IlCalendar` current time from the given long value. More...

Protected Attributes
IlBoolean	fAreAllFieldsSet

IlBoolean	fAreFieldsSet

IlInt	fFields [FIELD_COUNT]

IlBoolean	fIsSet [FIELD_COUNT]

IlBoolean	fIsTimeSet

IlInt	fStamp [FIELD_COUNT]

Detailed Description

Abstract base class managing a calendar date.

Library: ilog

From IBM ICU classes, adapted for Rogue Wave Views libraries.
Copyright (C) 1997-1999, International Business Machines Corporation and others. All Rights Reserved.

IlCalendar is an abstract base class for converting between a IlDate object and a set of integer fields such as YEAR, MONTH, DAY, HOUR, and so on. (A IlDate object represents a specific instant in time with millisecond precision.)

Subclasses of IlCalendar interpret a IlDate according to the rules of a specific calendar system. The Rogue Wave Views library provides one concrete subclass of IlCalendar: IlGregorianCalendar. Future subclasses could represent the various types of lunar calendars in use in many parts of the world.

Like other locale-sensitive classes, IlCalendar provides a class method, getInstance, for getting a generally useful object of this type. IlCalendar getInstance() method returns a IlGregorianCalendar object whose time fields have been initialized with the current date and time:

IlCalendar rightNow = IlCalendar.getInstance();

An IlCalendar object can produce all the time field values needed to implement the date-time formatting for a particular language and calendar style (for example, Japanese-Gregorian, Japanese-Traditional).

When computing a IlDate from time fields, two special circumstances may arise: there may be insufficient information to compute the IlDate (such as only year and month but no day in the month), or there may be inconsistent information (such as "Tuesday, July 15, 1996" – July 15, 1996 is actually a Monday).

Insufficient information. The calendar will use default information to specify the missing fields. This may vary by calendar; for the Gregorian calendar, the default for a field is the same as that of the start of the epoch: that is, YEAR = 1970, MONTH = JANUARY, DATE = 1, and so on.

Inconsistent information. If fields conflict, the calendar will give preference to fields set more recently. For example, when determining the day, the calendar will look for one of the following combinations of fields. The most recent combination, as determined by the most recently set single field, will be used.

MONTH + DAY_OF_MONTH
MONTH + WEEK_OF_MONTH + DAY_OF_WEEK
MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK
DAY_OF_YEAR
DAY_OF_WEEK + WEEK_OF_YEAR

For the time of day:

HOUR_OF_DAY

AM_PM + HOUR

Note: for some non-Gregorian calendars, different fields may be necessary for complete disambiguation. For example, a full specification of the historical Arabic astronomical calendar requires year, month, day-of-month and day-of-week in some cases.

Note

There are possible ambiguities in the interpretation of certain singular times, which are resolved in the following ways:

24:00:00 belongs to the following day. That is, 23:59 on Dec 31, 1969 < 24:00 on Jan 1, 1970 < 24:01:00 on Jan 1, 1970
Although historically not precise, midnight also belongs to am, and noon belongs to pm, so on the same day, 12:00 am (midnight) < 12:01 am, and 12:00 pm (noon) < 12:01 pm

The date or time format strings are not part of the definition of a calendar, as those can be modified or overriden by the user at runtime.

IlCalendar provides an API for field rolling, where fields can be incremented or decremented, but wrap around. For example, rolling the month up in the date December 12, 1996 results in January 12, 1996.

IlCalendar also provides a date arithmetic function for adding the specified (signed) amount of time to a particular time field. For example, subtracting 5 days from the date September 12, 1996 results in September 7, 1996.

Member Enumeration Documentation

enum IlCalendar::EAmpm

Constants for the hour in a 12-hour clock.

Used in IlGregorianCalendar.

Enumerator
AM	Ante meridiem; designates the time from midnight to noon.
PM	Post meridiem; designates the time from noon to midnight.

enum IlCalendar::EDaysOfWeek

Constants for days of the week.

Note: The IlCalendar day-of-week is 1-based.

Users who create locale resources for the field fFirstDayOfWeek should be aware of this. For instance, in the US locale, fFirstDayOfWeek is set to 1, that is, SUNDAY.

Enumerator
SUNDAY	Value indicating Sunday.
MONDAY	Value indicating Monday.
TUESDAY	Value indicating Tuesday.
WEDNESDAY	Value indicating Wednesday.
THURSDAY	Value indicating Thursday.
FRIDAY	Value indicating Friday.
SATURDAY	Value indicating Saturday.

enum IlCalendar::EMonths

Constants for the month.

Note: The IlCalendar month is 0-based.

Enumerator
JANUARY	Value indicating January.
FEBRUARY	Value indicating February.
MARCH	Value indicating March.
APRIL	Value indicating April.
MAY	Value indicating May.
JUNE	Value indicating June.
JULY	Value indicating July.
AUGUST	Value indicating August.
SEPTEMBER	Value indicating September.
OCTOBER	Value indicating October.
NOVEMBER	Value indicating November.
DECEMBER	Value indicating December.
UNDECIMBER	Value indicating the thirteenth month of the year (used by lunar calendars).

enum IlCalendar::IlDateFields

Field IDs for date and time.

Used to specify date/time fields. The ERA is calendar specific. Example ranges given are for illustration only; see specific IlCalendar subclasses for actual ranges.

Enumerator
ERA	Example: `0..1`.
YEAR	Example: `1..`big number.
MONTH	Example: `0..11`.
WEEK_OF_YEAR	Example: `1..53`.
WEEK_OF_MONTH	Example: `1..4`.
DATE	Example: `1..31`.
DAY_OF_YEAR	Example: `1..365`.
DAY_OF_WEEK	Example: `1..7`.
DAY_OF_WEEK_IN_MONTH	Example: `1..4`, may be specified as `-1`.
AM_PM	Example: `0..1`.
HOUR	Example: `0..11`.
HOUR_OF_DAY	Example: `0..23`.
MINUTE	Example: `0..59`.
SECOND	Example: `0..59`.
MILLISECOND	Example: `0..999`.
ZONE_OFFSET	Example: `-12IL_DATE_MILLIS_PER_HOUR..12IL_DATE_MILLIS_PER_HOUR`.
DST_OFFSET	Example: `0` or `IL_MILLIS_PER_HOUR`.

Constructor & Destructor Documentation

IlCalendar::IlCalendar ( IlDateErrorCode & success )

protected

Constructs an IlCalendar with the default time zone and locale.

The time zone is the one returned by IlTimeZone::createInstance().

Parameters

success Indicates the status of the IlCalendar object construction: it is set to IL_DATE_ZERO_ERROR if the object is constructed successfully.

IlCalendar::IlCalendar ( const IlCalendar & source )

protected

Copy constructor.

Copy constructor

IlCalendar::IlCalendar	(	IlTimeZone *	zone,
		const IlLocale &	locale,
		IlDateErrorCode &	success
	)

protected

Initializes a new IlCalendar with the given time zone and locale.

Clients are no longer responsible for deleting the given time zone object after it has been adopted.

Parameters

zone	The given time zone.
locale	The given locale.
success	Indicates the status of the `IlCalendar` object construction. It is set to `IL_DATE_ZERO_ERROR` if initialized successfully.

IlCalendar::IlCalendar	(	const IlTimeZone &	zone,
		const IlLocale &	locale,
		IlDateErrorCode &	success
	)

protected

Initializes a new IlCalendar with the given time zone and locale.

Parameters

zone	The given time zone.
locale	The given locale.
success	Indicates the status of the `IlCalendar` object construction. It is set to `IL_DATE_ZERO_ERROR` if initialized successfully.

Member Function Documentation

virtual void IlCalendar::add	(	IlDateFields	field,
		IlInt	amount,
		IlDateErrorCode &	status
	)

pure virtual

An arithmetic function for IlDate type. This function adds the specified (signed) amount of time to the given time field, based on the calendar rules.

For example, to subtract 5 days from the current time of the calendar, call add(IlCalendar::DATE, -5). When adding on the month or IlCalendar::MONTH field, other fields such as date might conflict and need to be changed. For instance, adding 1 month on the date 01/31/96 will result in 02/29/96.

Parameters

field	Specifies which date field to modify.
amount	The amount of time to be added to the field, in the natural unit for that field (for example, days for the day fields, hours for the hour field).
status	An output parameter set to a success/failure code on exit. If any value previously set in the time field is invalid or restricted by leniency, this will be set to an error status.

Implemented in IlGregorianCalendar.

void IlCalendar::adoptTimeZone ( IlTimeZone * value )

Sets the calendar time zone to be the one passed in.

The IlCalendar takes ownership of the IlTimeZone; the caller is no longer responsible for deleting it. If the given time zone is 0, this function has no effect.

Parameters

value The given time zone.

IlBoolean IlCalendar::after	(	const IlCalendar &	when,
		IlDateErrorCode &	status
	)		const

Returns IlTrue if this IlCalendar current time is after when current time.

Parameters

when	The `IlCalendar` to be compared with this `IlCalendar`. Although this is a `const` parameter, the object may be modified physically.
status	An output parameter set to a success/failure code on exit. If any value previously set in the time field is invalid or restricted by leniency, this will be set to an error status.

Returns: IlTrue if the current time of this IlCalendar is after the time of IlCalendar when; IlFalse otherwise.

IlBoolean IlCalendar::before	(	const IlCalendar &	when,
		IlDateErrorCode &	status
	)		const

Returns IlTrue if this IlCalendar current time is before when current time.

Parameters

when	The `IlCalendar` to be compared with this `IlCalendar`. Although this is a `const` parameter, the object may be modified physically.
status	Output param set to success/failure code on exit. If any value previously set in the time field is invalid or restricted by leniency, this will be set to an error status.

Returns: IlTrue if the current time of this IlCalendar is before the time of IlCalendar when; IlFalse otherwise.

void IlCalendar::clear ( )

Clears the values of all the time fields, making them both unset and assigning them a value of zero.

The field values will be determined during the next resolving of time into time fields.

void IlCalendar::clear ( IlDateFields field )

Clears the value in the given time field, both making it unset and assigning it a value of zero.

This field value will be determined during the next resolving of time into time fields.

Parameters

field The time field to be cleared.

void IlCalendar::complete ( IlDateErrorCode & status )

protected

Recomputes the current time from currently set fields.

After computation, any unset fields in the time field list are set.

Parameters

status An output parameter set to a success/failure code on exit. If any value previously set in the time field is invalid or restricted by leniency, this will be set to an error status.

virtual void IlCalendar::computeFields ( IlDateErrorCode & status )

protectedpure virtual

Converts GMT as milliseconds to time field values.

This allows you to sync up the time field values with a new time that is set for the calendar. This method does NOT recompute the time first; to recompute the time, then the fields, use the method complete().

Parameters

status An output parameter set to a success/failure code on exit.

Implemented in IlGregorianCalendar.

virtual void IlCalendar::computeTime ( IlDateErrorCode & status )

protectedpure virtual

Converts IlCalendar time field values to GMT, in milliseconds.

Parameters

status An output parameter set to a success/failure code on exit. If any value previously set in the time field is invalid or restricted by leniency, this will be set to an error status.

Implemented in IlGregorianCalendar.

static IlCalendar* IlCalendar::createInstance ( IlDateErrorCode & success )

static

Creates an IlCalendar that uses the default time zone and locale.

Users are responsible for deleting the returned object.

Parameters

success Indicates the success/failure of IlCalendar creation. Filled in with IL_ZERO_ERROR if created successfully, set to a failure result otherwise.

Returns: An IlCalendar if created successfully, 0 otherwise.

static IlCalendar* IlCalendar::createInstance	(	IlTimeZone *	zoneToAdopt,
		IlDateErrorCode &	success
	)

static

Creates an IlCalendar using the given time zone and the default locale.

The IlCalendar takes ownership of zoneToAdopt; users should not delete it.

Parameters

zoneToAdopt	The given time zone to be adopted.
success	Indicates the success/failure of `IlCalendar` creation. Filled in with `IL_ZERO_ERROR` if created successfully, set to a failure result otherwise.

Returns: An IlCalendar if created successfully, 0 otherwise.

static IlCalendar* IlCalendar::createInstance	(	const IlTimeZone &	zone,
		IlDateErrorCode &	success
	)

static

Creates an IlCalendar using the given time zone and the default locale.

The IlTimeZone is not adopted; it is the responsibility of the users to delete it.

Parameters

zone	The time zone.
success	Indicates the success/failure of `IlCalendar` creation. Filled in with `IL_ZERO_ERROR` if created successfully, set to a failure result otherwise.

Returns: An IlCalendar if created successfully, 0 otherwise.

static IlCalendar* IlCalendar::createInstance	(	const IlLocale &	aLocale,
		IlDateErrorCode &	success
	)

static

Creates an IlCalendar using the default time zone and the given locale.

Parameters

aLocale	The given locale.
success	Indicates the success/failure of `IlCalendar` creation. Filled in with `IL_ZERO_ERROR` if created successfully, set to a failure result otherwise.

Returns: An IlCalendar if created successfully, 0 otherwise.

static IlCalendar* IlCalendar::createInstance	(	IlTimeZone *	zoneToAdopt,
		const IlLocale &	aLocale,
		IlDateErrorCode &	success
	)

static

Creates an IlCalendar using the given time zone and locale.

The IlCalendar takes ownership of zoneToAdopt; the client must not delete it.

Parameters

zoneToAdopt	The given time zone to be adopted.
aLocale	The given locale.
success	Indicates the success/failure of `IlCalendar` creation. Filled in with `IL_DATE_ZERO_ERROR` if created successfully, set to a failure result otherwise.

Returns: An IlCalendar if created successfully, 0 otherwise.

static IlCalendar* IlCalendar::createInstance	(	const IlTimeZone &	zoneToAdopt,
		const IlLocale &	aLocale,
		IlDateErrorCode &	success
	)

static

Gets an IlCalendar using the given time zone and given locale.

The IlTimeZone is not adopted; the client is still responsible for deleting it.

Parameters

zoneToAdopt	The time zone.
aLocale	The given locale.
success	Indicates the success/failure of `IlCalendar` creation. Filled in with `IL_DATE_ZERO_ERROR` if created successfully, set to a failure result otherwise.

Returns: An IlCalendar if created successfully, 0 otherwise.

IlBoolean IlCalendar::equals	(	const IlCalendar &	when,
		IlDateErrorCode &	status
	)		const

Compares the IlCalendar time, whereas IlCalendar::operator== compares the equality of IlCalendar objects.

Parameters

when	The `IlCalendar` to be compared with this `IlCalendar`. Although this is a `const` parameter, the object may be modified physically.
status	Output param set to success/failure code on exit. If any value previously set in the time field is invalid or restricted by leniency, this will be set to an error status.

Returns: IlTrue if the current time of this IlCalendar is equal to the time of IlCalendar when; IlFalse otherwise.

virtual IlBoolean IlCalendar::equivalentTo ( const IlCalendar & other ) const

virtual

Returns IlTrue if another IlCalendar object is equivalent to this one.

An equivalent IlCalendar will behave exactly as this one does, but may be set to a different time.

Deprecated:

Reimplemented in IlGregorianCalendar.

virtual IlInt IlCalendar::fieldDifference	(	IlDate	when,
		IlDateFields	field,
		IlDateErrorCode &	status
	)

virtual

Returns the difference between the given time and the time this calendar object is set to.

If this calendar is set before the given time, the returned value will be positive. If this calendar is set after the given time, the returned value will be negative. The field parameter specifies the units of the return value. For example, if fieldDifference(when, IlCalendar.MONTH) returns 3, then this calendar is set to 3 months before when, and possibly some additional time less than one month.

As a side effect of this call, this calendar is advanced toward when by the given amount. That is, calling this method has the side effect of calling add(field, n), where n is the return value.

Usage: To use this method, call it first with the largest field of interest, then with progressively smaller fields. For example:

int y = cal.fieldDifference(when, IlCalendar.YEAR);
int m = cal.fieldDifference(when, IlCalendar.MONTH);
int d = cal.fieldDifference(when, IlCalendar.DATE);

computes the difference between cal and when in years, months, and days.

Note: fieldDifference() is asymmetrical. That is, in the following code:

cal.setTime(date1);
int m1 = cal.fieldDifference(date2, IlCalendar.MONTH);
int d1 = cal.fieldDifference(date2, IlCalendar.DATE);
cal.setTime(date2);
int m2 = cal.fieldDifference(date1, IlCalendar.MONTH);
int d2 = cal.fieldDifference(date1, IlCalendar.DATE);

you might expect that m1 == -m2 && d1 == -d2. However, this is not generally the case, because of irregularities in the underlying calendar system (for example, the Gregorian calendar has a variable number of days per month).

Parameters

when	The date to compare this calendar time to.
field	The field in which to compute the result.
status	An output parameter set to a success/failure code on exit. If any value previously set in the time field is invalid, this will be set to an error status.

Returns: The difference, either positive or negative, between this calendar time and when, in terms of field.

IlInt IlCalendar::get	(	IlDateFields	field,
		IlDateErrorCode &	status
	)		const

Indicates the value for a given time field.

It recalculates the current time field values if the time value has been changed by a call to setTime(). It returns 0 for unset fields if any fields have been explicitly set by a call to set(). To force a recomputation of all fields regardless of the previous state, call complete(). This method is semantically const, but may actually alter the object in memory.

Parameters

field	The given time field.
status	Fill-in parameter which receives the status of the operation.

Returns: The value for the given time field, or 0if the field is unset and set() has been called for any other field.

IlInt IlCalendar::getActualMaximum	(	IlDateFields	field,
		IlDateErrorCode &	status
	)		const

Returns the maximum value that this field could have, given the current date.

For example, with the date Feb 3, 1997 and the DAY_OF_MONTH field, the actual maximum would be 28; for Feb 3, 1996, it is 29.

Similarly, for a Hebrew calendar, for some years the actual maximum for MONTH is 12, and for others it is 13.

The version of this function on IlCalendar uses an iterative algorithm to determine the actual maximum value for the field. There is almost always a more efficient way to accomplish this (in most cases, you can simply return getMaximum()). IlGregorianCalendar overrides this function with a more efficient implementation.

Parameters

field	The given time field.
status	An output parameter set to a success/failure code on exit. If any value previously set in the time field is invalid, this will be set to an error status.

Returns: The maximum value for the given time field and the current date of this IlCalendar.

IlInt IlCalendar::getActualMinimum	(	IlDateFields	field,
		IlDateErrorCode &	status
	)		const

Returns the minimum value that this field could have, given the current date.

For the Gregorian calendar, this is the same as getMinimum() and getGreatestMinimum().

The version of this function on IlCalendar uses an iterative algorithm to determine the actual minimum value for the field. There is almost always a more efficient way to accomplish this (in most cases, you can simply return getMinimum()). IlGregorianCalendar overrides this function with a more efficient implementation.

Parameters

field	The given time field.
status	An output parameter set to a success/failure code on exit. If any value previously set in the time field is invalid, this will be set to an error status.

Returns: The minimum value for the given time field and the current date of this IlCalendar.

EDaysOfWeek IlCalendar::getFirstDayOfWeek ( ) const

Returns the first day of the week; for example, Sunday in US, Monday in France.

Returns: The first day of the week.

virtual IlInt IlCalendar::getGreatestMinimum ( IlDateFields field ) const

pure virtual

Indicates the highest minimum value for the given field if it varies.

Otherwise, the value is the same as getMinimum().

For Gregorian, there is no difference.

Parameters

field The given time field.

Returns: The highest minimum value for the given time field.

Implemented in IlGregorianCalendar.

virtual IlInt IlCalendar::getLeastMaximum ( IlDateFields field ) const

pure virtual

Indicates the lowest maximum value for the given field if it varies.

Otherwise, the value is the same as getMaximum().

For example, for Gregorian DAY_OF_MONTH: 28.

Parameters

field The given time field.

Returns: The lowest maximum value for the given time field.

Implemented in IlGregorianCalendar.

virtual IlInt IlCalendar::getMaximum ( IlDateFields field ) const

pure virtual

Indicates the maximum value for the given time field.

For example, for Gregorian DAY_OF_MONTH: 31.

Parameters

field The given time field.

Returns: The maximum value for the given time field.

Implemented in IlGregorianCalendar.

IlUChar IlCalendar::getMinimalDaysInFirstWeek ( ) const

Indicates the minimal days required in the first week of the year.

For example, if the first week is defined as one that contains the first day of the first month of a year, this method. If the minimal days required must be a full week, it returns 7.

Returns: The minimal days required in the first week of the year.

virtual IlInt IlCalendar::getMinimum ( IlDateFields field ) const

pure virtual

Indicates the minimum value for the given time field.

For example, for Gregorian DAY_OF_MONTH: 1.

Parameters

field The given time field.

Returns: The minimum value for the given time field.

Implemented in IlGregorianCalendar.

static IlDate IlCalendar::getNow ( )

static

Returns the current UTC (GMT) time measured in milliseconds since 0:00:00 on 1/1/70 (derived from the system time).

Returns: The current UTC time in milliseconds.

IlDate IlCalendar::getTime ( IlDateErrorCode & status ) const

Gets this IlCalendar time as milliseconds.

This may involve recalculation of time due to previous calls to set time field values. The time specified is nonlocal UTC (GMT) time. Although this method is const, this object may actually be changed (semantically const).

Parameters

status Output parameter set to a success/failure code on exit. If any value previously set in the time field is invalid or restricted by leniency, this will be set to an error status.

Returns: The current time in UTC (GMT) time, or zero if the operation failed.

double IlCalendar::getTimeInMillis ( IlDateErrorCode & status ) const

protected

Gets this IlCalendar current time as a long.

Parameters

status An output parameter set to a success/failure code on exit.

Returns: The current time as UTC milliseconds from the epoch.

const IlTimeZone& IlCalendar::getTimeZone ( ) const

Returns a reference to the time zone owned by this calendar.

The returned reference is valid only until clients make another call to adoptTimeZone() or setTimeZone(), or this IlCalendar is destroyed.

Returns: The time zone object associated with this calendar.

virtual IlBoolean IlCalendar::inDaylightTime ( IlDateErrorCode & status ) const

pure virtual

Queries if the current date for this IlCalendar is in Daylight Savings Time.

Parameters

status Fill-in parameter which receives the status of this operation.

Returns: IlTrue if the current date for this IlCalendar is in Daylight Savings Time, IlFalse otherwise.

Implemented in IlGregorianCalendar.

IlInt IlCalendar::internalGet ( IlDateFields field ) const

protected

Gets the value for a given time field.

Subclasses can use this function to fetch field values without forcing recomputation of time.

Parameters

field The given time field.

Returns: The value for the given time field.

IlDate IlCalendar::internalGetTime ( ) const

protected

Gets the current time without recomputing.

void IlCalendar::internalSet	(	IlDateFields	field,
		IlInt	value
	)

protected

Sets the value for a given time field.

This is a fast internal method for subclasses. It does not affect the fAreFieldsSet, fIsTimeSet, or areAllFieldsSet flags.

void IlCalendar::internalSetTime ( IlDate time )

protected

Sets the current time without affecting flags or fields.

IlBoolean IlCalendar::isLenient ( ) const

Indicates whether the date/time interpretation is lenient.

Returns: IlTrue if the date/time interpretation is lenient.

See Also: setLenient().

IlBoolean IlCalendar::isSet ( IlDateFields field ) const

Determines if the given time field has a value set.

This can affect the resolving of time in IlCalendar. Unset fields have a value of 0, by definition.

Returns: IlTrue if the given time field has a value set; IlFalse otherwise.

IlBoolean IlCalendar::operator!= ( const IlCalendar & that ) const

Compares the inequality of two IlCalendar objects.

Parameters

that	The `IlCalendar` object to be compared with.

Returns: IlTrue if the given IlCalendar is not the same as this IlCalendar; IlFalse otherwise.

virtual IlBoolean IlCalendar::operator== ( const IlCalendar & that ) const

virtual

Compares the equality of two IlCalendar objects.

Objects of different subclasses are considered unequal. This comparison is very exacting; two IlCalendar objects must be in exactly the same state to be considered equal. To compare based on the represented time, use equals() instead.

Parameters

that	The `IlCalendar` object to be compared with.

Returns: IlTrue if the given IlCalendar is the same as this IlCalendar; IlFalse otherwise.

Reimplemented in IlGregorianCalendar.

IlTimeZone* IlCalendar::orphanTimeZone ( )

Returns the time zone owned by this calendar.

The caller owns the returned object and must delete it when done. After this call, the new time zone associated with this IlCalendar is the default IlTimeZone as returned by IlTimeZone::createDefault().

Returns: The time zone object which was associated with this calendar.

void IlCalendar::roll	(	IlDateFields	field,
		IlBoolean	up,
		IlDateErrorCode &	status
	)

Time Field Rolling function: rolls (up/down) a single unit of time on the given time field.

For example, to roll the current date up by one day, call roll(IlCalendar::DATE, true). When rolling on the year or IlCalendar::YEAR field, it will roll the year value in the range between getMinimum(IlCalendar::YEAR) and the value returned by getMaximum(IlCalendar::YEAR). When rolling on the month or IlCalendar::MONTH field, other fields like date might conflict and, need to be changed. For instance, rolling the month up on the date 01/31/96 will result in 02/29/96. Rolling up always means rolling forward in time; for example, rolling the year up on 100 BC will result in 99 BC, for Gregorian calendar. When rolling on the hour-in-day or IlCalendar::HOUR_OF_DAY field, it will roll the hour value in the range between 0 and 23, which is zero-based.

Note: Do not use this method – use roll(IlDateFields, int, IlDateErrorCode&) instead.

Parameters

field	The time field.
up	Indicates if the value of the specified time field is to be rolled up or rolled down. Use `IlTrue` if rolling up, `IlFalse` otherwise.
status	Output param set to success/failure code on exit. If any value previously set in the time field is invalid or restricted by leniency, this will be set to an error status.

virtual void IlCalendar::roll	(	IlDateFields	field,
		IlInt	amount,
		IlDateErrorCode &	status
	)

pure virtual

Time Field Rolling function: rolls the given amount on the given time field.

For example, to roll the current date up by one day, call roll(IlCalendar::DATE, +1, status). When rolling on the month or IlCalendar::MONTH field, other fields such as date might conflict and need to be changed. For instance, rolling the month up on the date 01/31/96 will result in 02/29/96. Rolling by a positive value always means rolling forward in time; for example, rolling the year by +1 on 100 BC will result in 99 BC, for the Gregorian calendar. When rolling on the hour-in-day or IlCalendar::HOUR_OF_DAY field, it will roll the hour value in the range between 0 and 23, which is zero-based.

The only difference between roll() and add() is that roll() does not change the value of more significant fields when it reaches the minimum or maximum of its range, whereas add() does.

Parameters

field	The time field.
amount	The amount to roll.
status	An output parameter set to a success/failure code on exit. If any value previously set in the time field is invalid, this will be set to an error status.

Implemented in IlGregorianCalendar.

void IlCalendar::set	(	IlDateFields	field,
		IlInt	value
	)

Sets the given time field with the given value.

Parameters

field	The given time field.
value	The value to be set for the given time field.

void IlCalendar::set	(	IlInt	year,
		IlInt	month,
		IlInt	date
	)

Sets the values for the fields YEAR, MONTH, and DATE.

Other field values are retained; call clear() first if this is not desired.

Parameters

year	The value used to set the `YEAR` time field.
month	The value used to set the `MONTH` time field. The month value is 0-based, for example, `0` for January.
date	The value used to set the `DATE` time field.

void IlCalendar::set	(	IlInt	year,
		IlInt	month,
		IlInt	date,
		IlInt	hour,
		IlInt	minute
	)

Sets the values for the fields YEAR, MONTH, DATE, HOUR_OF_DAY, and MINUTE.

Other field values are retained; call clear() first if this is not desired.

Parameters

year	The value used to set the `YEAR` time field.
month	The value used to set the `MONTH` time field. The month value is 0-based, for example, `0` for January.
date	The value used to set the `DATE` time field.
hour	The value used to set the `HOUR_OF_DAY` time field.
minute	The value used to set the `MINUTE` time field.

void IlCalendar::set	(	IlInt	year,
		IlInt	month,
		IlInt	date,
		IlInt	hour,
		IlInt	minute,
		IlInt	second
	)

Sets the values for the fields YEAR, MONTH, DATE, HOUR_OF_DAY, MINUTE, and SECOND.

Other field values are retained; call clear() first if this is not desired.

Parameters

year	The value used to set the `YEAR` time field.
month	The value used to set the `MONTH` time field. The month value is 0-based, for example, `0` for January.
date	The value used to set the `DATE` time field.
hour	The value used to set the `HOUR_OF_DAY` time field.
minute	The value used to set the `MINUTE` time field.
second	The value used to set the `SECOND` time field.

void IlCalendar::setFirstDayOfWeek ( EDaysOfWeek value )

Sets the first day of the week; for example, Sunday in US, Monday in France.

Parameters

value The given first day of the week.

void IlCalendar::setLenient ( IlBoolean lenient )

Specifies whether or not the date/time interpretation is to be lenient.

With lenient interpretation, a date such as February 942, 1996 will be treated as being equivalent to the 941st day after February 1, 1996. With strict interpretation, such dates will cause an error when computing time from the time field values representing the dates.

Parameters

lenient If IlTrue, specifies the date/time interpretation to be lenient.

void IlCalendar::setMinimalDaysInFirstWeek ( IlUChar value )

Sets the minimal days required in the first week of the year.

For example, if the first week is defined as one that contains the first day of the first month of a year, call the method with value 1. If it must be a full week, use value 7.

Parameters

value The given minimal days required in the first week of the year.

void IlCalendar::setTime	(	IlDate	date,
		IlDateErrorCode &	status
	)

Sets this IlCalendar current time with the given IlDate.

The time specified should be in nonlocal UTC (GMT) time.

Parameters

date	The given `IlDate` in UTC (GMT) time.
status	An output parameter set to a success/failure code on exit. If any value previously set in the time field is invalid, this will be set to an error status.

void IlCalendar::setTimeInMillis	(	double	millis,
		IlDateErrorCode &	status
	)

protected

Sets this IlCalendar current time from the given long value.

Parameters

millis	The new time in UTC milliseconds from the epoch.
status	An output parameter set to a success/failure code on exit.

void IlCalendar::setTimeZone ( const IlTimeZone & zone )

Sets the calendar time zone to be the same as the one passed in.

The IlTimeZone passed in is not adopted; the client is still responsible for deleting it.

Parameters

zone	The given time zone.

Member Data Documentation

IlBoolean IlCalendar::fAreAllFieldsSet

protected

IlTrue if all of the fields have been set.

This is initially IlFalse, and set to IlTrue by computeFields().

IlBoolean IlCalendar::fAreFieldsSet

protected

If set to IlTrue, the fields are in sync with the currently set time of this IlCalendar.

If set to IlFalse, then the next attempt to get the value of a field will trigger a recomputation of all fields from the current value of the time field.

This should really be named areFieldsInSync, but the old name is retained for backward compatibility.

IlInt IlCalendar::fFields[FIELD_COUNT]

protected

The time fields containing values into which the millis are computed.

IlBoolean IlCalendar::fIsSet[FIELD_COUNT]

protected

The flags which tell if a specified time field for the calendar is set.

IlBoolean IlCalendar::fIsTimeSet

protected

The flag which indicates if the current time is set in the calendar.

IlInt IlCalendar::fStamp[FIELD_COUNT]

protected

Pseudo-time-stamps that specify when each field was set.

There are two special values, kUnset and kInternallySet. Values from kMinimumUserStamp to the maximal value for IlInt are valid.

Rogue Wave ViewsFoundation Package API Reference Guide

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

Rogue Wave Views
Foundation Package API Reference Guide