Rogue Wave Views
Foundation Package API Reference Guide
Product Documentation:

Rogue Wave Views
Documentation Home
List of all members | Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes
IlCalendar Class Referenceabstract

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

#include <ilog/calendar.h>

Inheritance diagram for IlCalendar:
IlGregorianCalendar

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 IlCalendarclone () 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 IlTimeZonegetTimeZone () 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...
 
IlTimeZoneorphanTimeZone ()
 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...
 
IlDate set (const char *date, IlDateErrorCode &status)
 Sets the date from the provided ISO 8601 string. 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 IlCalendarcreateInstance (IlDateErrorCode &success)
 Creates an IlCalendar that uses the default time zone and locale. More...
 
static IlCalendarcreateInstance (IlTimeZone *zoneToAdopt, IlDateErrorCode &success)
 Creates an IlCalendar using the given time zone and the default locale. More...
 
static IlCalendarcreateInstance (const IlTimeZone &zone, IlDateErrorCode &success)
 Creates an IlCalendar using the given time zone and the default locale. More...
 
static IlCalendarcreateInstance (const IlLocale &aLocale, IlDateErrorCode &success)
 Creates an IlCalendar using the default time zone and the given locale. More...
 
static IlCalendarcreateInstance (IlTimeZone *zoneToAdopt, const IlLocale &aLocale, IlDateErrorCode &success)
 Creates an IlCalendar using the given time zone and locale. More...
 
static IlCalendarcreateInstance (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
 Gets the current time without recomputing.
 
void internalSet (IlDateFields field, IlInt value)
 Sets the value for a given time field. More...
 
void internalSetTime (IlDate time)
 Sets the current time without affecting flags or fields.
 
IlCalendaroperator= (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
 Indicates if all of the fields have been set. More...
 
IlBoolean fAreFieldsSet
 
IlInt fFields [FIELD_COUNT]
 
IlBoolean fIsSet [FIELD_COUNT]
 
IlBoolean fIsTimeSet
 
IlInt fStamp [FIELD_COUNT]
 Pseudo-time-stamps that specify when each field was set. More...
 

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.

For the time of day:

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:
  1. 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
  2. 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

§ 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.

§ 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.

§ 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).

§ 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: -12*IL_DATE_MILLIS_PER_HOUR..12*IL_DATE_MILLIS_PER_HOUR.

DST_OFFSET 

Example: 0 or IL_MILLIS_PER_HOUR.

Constructor & Destructor Documentation

§ IlCalendar() [1/4]

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
successIndicates the status of the IlCalendar object construction: it is set to IL_DATE_ZERO_ERROR if the object is constructed successfully.

§ IlCalendar() [2/4]

IlCalendar::IlCalendar ( const IlCalendar source)
protected

Copy constructor.

Copy constructor

§ IlCalendar() [3/4]

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
zoneThe given time zone.
localeThe given locale.
successIndicates the status of the IlCalendar object construction. It is set to IL_DATE_ZERO_ERROR if initialized successfully.

§ IlCalendar() [4/4]

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

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

Parameters
zoneThe given time zone.
localeThe given locale.
successIndicates the status of the IlCalendar object construction. It is set to IL_DATE_ZERO_ERROR if initialized successfully.

Member Function Documentation

§ add()

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
fieldSpecifies which date field to modify.
amountThe 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).
statusAn 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.

§ adoptTimeZone()

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
valueThe given time zone.

§ after()

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

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

Parameters
whenThe IlCalendar to be compared with this IlCalendar. Although this is a const parameter, the object may be modified physically.
statusAn 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.

§ before()

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

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

Parameters
whenThe IlCalendar to be compared with this IlCalendar. Although this is a const parameter, the object may be modified physically.
statusOutput 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.

§ clear() [1/2]

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.

§ clear() [2/2]

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
fieldThe time field to be cleared.

§ complete()

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
statusAn 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.

§ computeFields()

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
statusAn output parameter set to a success/failure code on exit.

Implemented in IlGregorianCalendar.

§ computeTime()

virtual void IlCalendar::computeTime ( IlDateErrorCode status)
protectedpure virtual

Converts IlCalendar time field values to GMT, in milliseconds.

Parameters
statusAn 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.

§ createInstance() [1/6]

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
successIndicates 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.

§ createInstance() [2/6]

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
zoneToAdoptThe given time zone to be adopted.
successIndicates 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.

§ createInstance() [3/6]

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
zoneThe time zone.
successIndicates 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.

§ createInstance() [4/6]

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

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

Parameters
aLocaleThe given locale.
successIndicates 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.

§ createInstance() [5/6]

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
zoneToAdoptThe given time zone to be adopted.
aLocaleThe given locale.
successIndicates 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.

§ createInstance() [6/6]

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
zoneToAdoptThe time zone.
aLocaleThe given locale.
successIndicates 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.

§ equals()

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

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

Parameters
whenThe IlCalendar to be compared with this IlCalendar. Although this is a const parameter, the object may be modified physically.
statusOutput 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.

§ equivalentTo()

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.

§ fieldDifference()

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
whenThe date to compare this calendar time to.
fieldThe field in which to compute the result.
statusAn 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.

§ get()

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
fieldThe given time field.
statusFill-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.

§ getActualMaximum()

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
fieldThe given time field.
statusAn 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.

§ getActualMinimum()

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
fieldThe given time field.
statusAn 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.

§ getFirstDayOfWeek()

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.

§ getGreatestMinimum()

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
fieldThe given time field.
Returns
The highest minimum value for the given time field.

Implemented in IlGregorianCalendar.

§ getLeastMaximum()

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
fieldThe given time field.
Returns
The lowest maximum value for the given time field.

Implemented in IlGregorianCalendar.

§ getMaximum()

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
fieldThe given time field.
Returns
The maximum value for the given time field.

Implemented in IlGregorianCalendar.

§ getMinimalDaysInFirstWeek()

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.

§ getMinimum()

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
fieldThe given time field.
Returns
The minimum value for the given time field.

Implemented in IlGregorianCalendar.

§ getNow()

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.

§ getTime()

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
statusOutput 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.

§ getTimeInMillis()

double IlCalendar::getTimeInMillis ( IlDateErrorCode status) const
protected

Gets this IlCalendar current time as a long.

Parameters
statusAn output parameter set to a success/failure code on exit.
Returns
The current time as UTC milliseconds from the epoch.

§ getTimeZone()

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.

§ inDaylightTime()

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

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

Parameters
statusFill-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.

§ internalGet()

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
fieldThe given time field.
Returns
The value for the given time field.

§ internalSet()

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.

§ isLenient()

IlBoolean IlCalendar::isLenient ( ) const

Indicates whether the date/time interpretation is lenient.

Returns
IlTrue if the date/time interpretation is lenient.
See also
setLenient().

§ isSet()

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.

§ operator!=()

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

Compares the inequality of two IlCalendar objects.

Parameters
thatThe IlCalendar object to be compared with.
Returns
IlTrue if the given IlCalendar is not the same as this IlCalendar; IlFalse otherwise.

§ operator==()

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
thatThe IlCalendar object to be compared with.
Returns
IlTrue if the given IlCalendar is the same as this IlCalendar; IlFalse otherwise.

Reimplemented in IlGregorianCalendar.

§ orphanTimeZone()

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.

§ roll() [1/2]

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
fieldThe time field.
upIndicates if the value of the specified time field is to be rolled up or rolled down. Use IlTrue if rolling up, IlFalse otherwise.
statusOutput 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.

§ roll() [2/2]

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
fieldThe time field.
amountThe amount to roll.
statusAn 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.

§ set() [1/5]

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

Sets the given time field with the given value.

Parameters
fieldThe given time field.
valueThe value to be set for the given time field.

§ set() [2/5]

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
yearThe value used to set the YEAR time field.
monthThe value used to set the MONTH time field. The month value is 0-based, for example, 0 for January.
dateThe value used to set the DATE time field.

§ set() [3/5]

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
yearThe value used to set the YEAR time field.
monthThe value used to set the MONTH time field. The month value is 0-based, for example, 0 for January.
dateThe value used to set the DATE time field.
hourThe value used to set the HOUR_OF_DAY time field.
minuteThe value used to set the MINUTE time field.

§ set() [4/5]

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
yearThe value used to set the YEAR time field.
monthThe value used to set the MONTH time field. The month value is 0-based, for example, 0 for January.
dateThe value used to set the DATE time field.
hourThe value used to set the HOUR_OF_DAY time field.
minuteThe value used to set the MINUTE time field.
secondThe value used to set the SECOND time field.

§ set() [5/5]

IlDate IlCalendar::set ( const char *  date,
IlDateErrorCode status 
)

Sets the date from the provided ISO 8601 string.

Parameters
dateThe date to be parsed, as defined in the ISU 8601 standard.
statusSet to a potential error code on return. It is set to IL_DATE_ILLEGAL_ARGUMENT_ERROR if the string is not a valid ISO 8601 date representation.
Returns
the converted date value, now held by this calendar.

§ setFirstDayOfWeek()

void IlCalendar::setFirstDayOfWeek ( EDaysOfWeek  value)

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

Parameters
valueThe given first day of the week.

§ setLenient()

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
lenientIf IlTrue, specifies the date/time interpretation to be lenient.

§ setMinimalDaysInFirstWeek()

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
valueThe given minimal days required in the first week of the year.

§ setTime()

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
dateThe given IlDate in UTC (GMT) time.
statusAn 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.

§ setTimeInMillis()

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

Sets this IlCalendar current time from the given long value.

Parameters
millisThe new time in UTC milliseconds from the epoch.
statusAn output parameter set to a success/failure code on exit.

§ setTimeZone()

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
zoneThe given time zone.

Member Data Documentation

§ fAreAllFieldsSet

IlBoolean IlCalendar::fAreAllFieldsSet
protected

Indicates if all of the fields have been set.

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

§ fAreFieldsSet

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.

§ fFields

IlInt IlCalendar::fFields[FIELD_COUNT]
protected

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

§ fIsSet

IlBoolean IlCalendar::fIsSet[FIELD_COUNT]
protected

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

§ fIsTimeSet

IlBoolean IlCalendar::fIsTimeSet
protected

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

§ fStamp

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.


© Copyright 2018, Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.