Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
MCollectible
Inherited By:
TGregorianCalendar
Purpose:
An abstract class that defines the protocol for all calendar classes. Its primary function is to map a TTime object to a set of fields (or textual representation) and vice versa. It uses a TTimeZone to map UTC to local time. By default, calendars use the time zone specified in the current user's locale. Clients can also explicitly get/set the time zone in a TCalendar. This base class also enforces a policy when setting shifting, and rolling fields. This helps ensure consistent behavior among derived classes when dealing with invalid or out-of-bounds fields.
Instantiation:
TCalendar is an abstract class and cannot be instantiated directly.
Deriving Classes:
The system provides a concrete derived class, TGregorianCalendar.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
Other Considerations:
None.
~ TCalendar ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called to destroy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::SetTime
virtual void SetTime (const TTime & time)
Interface Category:
API.
Purpose:
Sets the time in this calendar. Converts the TTime to a set of fields by calling the pure virtual protected function DateToFields. The fields can then be retrieved from the calendar by calling GetField.
Calling Context:
Call this function directly.
Parameters:
- const TTime & time -The time with which to set the calendar.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Do not override this function. Instead, override the protected pure virtual function DateToFields.
Member Function: TCalendar::GetTime
virtual void GetTime (TTime & time)
Interface Category:
API.
Purpose:
Retrieves the time represented by this calendar. Converts the a set of fields to a TTime by calling the pure virtual protected function FieldsToDate. This function first checks if all the fields are in sync before returning the time.
Calling Context:
Call this function directly.
Parameters:
- TTime & time -The time represented by this calendar.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Do not override this function. Instead, override the protected pure virtual function FieldsToDate.
Member Function: TCalendar::GetField
virtual DateTimeFieldValue GetField (DateTimeFieldType whichField)
Interface Category:
API.
Purpose:
Returns the value in a given date/time field (for example, month).
Calling Context:
Call this function directly.
Parameters:
- DateTimeFieldType whichField -The field for which you want the value.
Return Value:
Returns the value of the specified field.
Exceptions:
Throws an exception if the field designator is out of bounds.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::GetLimits
virtual void GetLimits (DateTimeFieldType whichField, DateTimeFieldValue & minValue, DateTimeFieldValue & maxValue, DateTimeFieldValue & smallestMaxValue) const
Interface Category:
API.
Purpose:
Returns the range of valid values for a given field. It also returns the smallest maximal value possible. For example, for the month field, the valid range is (1,31), and the smallest maximal value is 28.
Calling Context:
Call this function directly.
Parameters:
- DateTimeFieldType whichField -The field designator (for example, kDayInMonth).
- DateTimeFieldValue & minValue -The minimum valid value for this field (for example, 1).
- DateTimeFieldValue & maxValue -The maximum valid value for this field (for example, 31).
- DateTimeFieldValue & smallestMaxValue -The lower maximum limit for this field (for example, 28 for February).
Return Value:
None.
Exceptions:
Throws an exception if the field designator is out of bounds.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::SetField
virtual void SetField (DateTimeFieldType whichField, DateTimeFieldValue fieldValue)
Interface Category:
API.
Purpose:
Sets the specified field to a given value. Note that other fields can be affected. For example, if you set the day and month fields, the day of week and week of year fields are altered to match the month and day.
Calling Context:
Call this function directly.
Parameters:
- DateTimeFieldType whichField -The field to be set.
- DateTimeFieldValue fieldValue -The value to set the field to.
Return Value:
None.
Exceptions:
Throws an exception if whichField is out of bounds.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::ShiftField
virtual bool ShiftField (DateTimeFieldType whichField, long shiftAmount)
Interface Category:
API.
Purpose:
Shifts a given calendar field by shiftAmount (a negative number causes a shift in the reverse direction). It returns false if the result is invalid. In that case, no change in the field is made. For example, if kEra is 1 (for example, B.C.), then trying to offset it by 10 is invalid. In this case, kEra remains 1 and a false is returned.
Note that shifting one field can change the values in other fields. For example, offsetting kDayInHour to 25 means adding 25 hours to the current date (that is, adding 1 day and 1 hour to the current date).
Calling Context:
Call this function directly.
Parameters:
- DateTimeFieldType whichField -The field to be shifted.
- long shiftAmount -The amount to shift.
Return Value:
Returns true if the shift result is valid.
Exceptions:
Throws an exception if whichField is out of bounds.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::RollField
virtual void RollField (DateTimeFieldType whichField, long rollAmount)
Interface Category:
API.
Purpose:
Changes the field value by rollAmount. This function differs from ShiftField in that the result wraps around. For example, incrementing the month field by one in Dec. 29, 1989 results in Jan 29, 1989. Note that when rolling fields, the other fields remain unaffected. This function is designed to be used by the human interface for change date/time.
Calling Context:
Call this function directly.
Parameters:
- DateTimeFieldType whichField -The field to be changed.
- long rollAmount -The amount to change the field. A negative number rolls the field value in the opposite direction.
Return Value:
None.
Exceptions:
Throws an exception if whichField is out of bounds.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::ClearAllFields
virtual void ClearAllFields ()
Interface Category:
API.
Purpose:
Resets the calendar by setting all fields to zero.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::ClearField
virtual void ClearField (DateTimeFieldType whichField)
Interface Category:
API.
Purpose:
Clears a particular field by setting it to zero.
Calling Context:
Call this function directly.
Parameters:
- DateTimeFieldType whichField -The field to clear.
Return Value:
None.
Exceptions:
Throws an exception if the specified field is out of bounds.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::GetUseZeroHour
bool GetUseZeroHour ()
Interface Category:
API.
Purpose:
Returns whether 12:00 a.m. should be represented as the hour zero. The default is false.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns true if 12:00 a.m. should be represented as the hour zero.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::SetUseZeroHour
virtual void SetUseZeroHour (bool flag)
Interface Category:
API.
Purpose:
Specifies whether 12:00 a.m. should be represented as the hour zero. The default is false.
Calling Context:
Call this function directly.
Parameters:
- bool flag -Whether or not 12:00 a.m. should be represented as the hour zero.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::GetFirstDayOfWeek
DateTimeFieldValue GetFirstDayOfWeek ()
Interface Category:
API.
Purpose:
Returns which day should be the first in a week (for example, Sunday versus Monday). The default is Sunday.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a DateTimeFieldValue denoting the weekday.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::SetFirstDayOfWeek
virtual void SetFirstDayOfWeek (DateTimeFieldValue whichDay)
Interface Category:
API.
Purpose:
Specifies which day should be the first in a week (for example, Sunday versus Monday). The default is Sunday.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a DateTimeFieldValue denoting the weekday.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::GetTimeZone
void GetTimeZone (TTimeZone & timeZone) const
Interface Category:
API.
Purpose:
Returns the time zone used by this calendar.
Calling Context:
Call this function directly.
Parameters:
- TTimeZone & timeZone -The time zone used by this calendar.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::SetTimeZone
virtual void SetTimeZone (const TTimeZone & timeZone)
Interface Category:
API.
Purpose:
Sets a time zone for this calendar to use.
Calling Context:
Call this function directly.
Parameters:
- const TTimeZone & timeZone -The time zone for this calendar to use.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::operator=
TCalendar & operator =(const TCalendar & calendar)
Interface Category:
API.
Purpose:
Assignment operator.
Calling Context:
Called when an object is assigned to another compatible object.
Parameters:
- const TCalendar & calendar -The source object for the assignment.
Return Value:
A non-const reference to the left-hand side object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::operator<<=
virtual TStream & operator <<= (TStream & fromWhere)
Interface Category:
API.
Purpose:
Stream-in operator.
Calling Context:
Called to stream in data.
Parameters:
- TStream & fromWhere -The stream the object is streamed in from.
Return Value:
Returns a reference to the stream the object streams itself in from.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::operator>>=
virtual TStream & operator >>=(TStream & toWhere) const
Interface Category:
API.
Purpose:
Stream-out operator.
Calling Context:
Called to stream out data.
Parameters:
- TStream & toWhere -The stream the object is streamed out to.
Return Value:
Returns a reference to the stream the object streams itself out to.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::Hash
virtual long Hash () const
Interface Category:
API.
Purpose:
Generates a hash value.
Calling Context:
Called to generate a hash value.
Parameters:
Return Value:
The numeric value of the hash.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
- TCalendar ()
- TCalendar (const TCalendar & cal)
Interface Category:
API.
Purpose:
- Default constructor.
- Copy constructor.
Calling Context:
- Called by the stream-in operators.
- Called to copy an object.
Parameters:
- Takes no parameters.
- const TCalendar & cal -The object to copy.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::SecondsToDate
virtual DateTimeFieldValue SecondsToDate (double seconds)
Interface Category:
API.
Purpose:
Converts the seconds to a number of days, and sets the hour, minute and second fields of this calendar. Returns the number of days. If the deriving calendar uses a 24-hour day, it does not override this function.
Calling Context:
Called internally by SetTime.
Parameters:
- double seconds -The number of seconds to convert.
Return Value:
Returns the integral number of days.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::DateToSeconds
virtual double DateToSeconds (DateTimeFieldValue integralDays) const
Interface Category:
API.
Purpose:
Returns the total seconds in this object by converting the day, hour, minute, and second fields of this object into a number of seconds, then adding this number to integralDays.
Calling Context:
Called internally by GetTime.
Parameters:
- DateTimeFieldValue integralDays -The number of integral days.
Return Value:
Returns the number of seconds in this object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::DaysToDate
virtual void DaysToDate (DateTimeFieldValue days)
Interface Category:
API.
Purpose:
Converts the number of days into era, year, month, and day, and sets these fields in this calendar. This function must be overridden by a derived class.
Calling Context:
Called internally by SetTime.
Parameters:
- DateTimeFieldValue days -An integral number of days.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function is pure virtual.
Member Function: TCalendar::DateToDays
virtual DateTimeFieldValue DateToDays () const
Interface Category:
API.
Purpose:
Converts the era, year, month, and day fields into a number of days and returns this value. This function must be overridden by a derived class.
Calling Context:
Called internally by GetTime.
Parameters:
Return Value:
Returns an integral number of days.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::GetValueInField
virtual DateTimeFieldValue GetValueInField (DateTimeFieldType whichField) const
Interface Category:
API.
Purpose:
Returns the value for a specified field in this calendar.
Calling Context:
Call this function directly.
Parameters:
- DateTimeFieldType whichField -The field for which to return a value.
Return Value:
The value for this field.
Exceptions:
Throws an exception if whichField is out of bounds.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::SetValueInField
virtual void SetValueInField (DateTimeFieldType whichField, DateTimeFieldValue value)
Interface Category:
API.
Purpose:
Specifies the value for a field in this calendar.
Calling Context:
Call this function directly.
Parameters:
- DateTimeFieldType whichField -The field for which to specify a value.
- DateTimeFieldValue value -The value for this field.
Return Value:
None.
Exceptions:
Throws an exception if whichField is out of bounds.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::HasValueInField
virtual bool HasValueInField (DateTimeFieldType whichField) const
Interface Category:
API.
Purpose:
Determines if a field contains a value.
Calling Context:
Call this function directly.
Parameters:
- DateTimeFieldType whichField -The field to query about.
Return Value:
Returns true if the field contains a value.
Exceptions:
Throws an exception if whichField is out of bounds.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::IsValidDate
virtual bool IsValidDate (DateTimeFieldType & badField) const
Interface Category:
API.
Purpose:
Determines if the fields in the calendar are consistent with each other. Returns the first invalid field found.
Calling Context:
Called internally by SetField.
Parameters:
- DateTimeFieldType & badField -The first invalid field encountered.
Return Value:
Returns true if all fields are valid.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TCalendar::ClearConflictingFields
virtual void ClearConflictingFields (DateTimeFieldType whichField)
Interface Category:
API.
Purpose:
Clears fields that are in conflict with the field just set. For example, when trying to set kDayInYear in a Gregorian calendar, the conflicting fields to clear are: kDayInMonth, kMonthInYear, kWeekInYear, and kDayInWeek, because just kDayInYear is good enough to uniquely specify a day.
Calling Context:
Called internally by SetField and RollField.
Parameters:
- DateTimeFieldType whichField -The field that you want to set.
Return Value:
None.
Exceptions:
Throws an exception if whichField is out of bounds.
Concurrency:
Not multithread safe.
Other Considerations:
This function is pure virtual. Derived classes should override to specify the conflicting fields for each field.
Member Function: TCalendar::BoundFieldToLimit
virtual void BoundFieldToLimit (DateTimeFieldType whichField)
Interface Category:
API.
Purpose:
Binds the value in a particular field to its closest limit. For example, if the field value is greater than the maximum allowed, it is changed to be the maximal value.
Calling Context:
Called internally by the field-changing public functions SetField, RollField, and ShiftField.
Parameters:
- DateTimeFieldType whichField -The field to bind to its limit.
Return Value:
None.
Exceptions:
Throws an exception if whichField is out of bounds.
Concurrency:
Not multithread safe.
Other Considerations:
This function is pure virtual. Derived classes must override to specify the limits for each field.
Member Function: TCalendar::ResolveConflictingFields
virtual void ResolveConflictingFields ()
Interface Category:
API.
Purpose:
Called by the public field manipulation functions to resolve conflicting values. For example, the user might have set the month to 4 and the day to 31. The resolution scheme it provides is based on field priority (see GetFieldPriority). This function ensures that conflicting fields are handled consistently across all derived classes.
Calling Context:
Called internally by SetField, RollField, and ShiftField.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Derived classes who override this function should call the inherited function first.
Member Function: TCalendar::GetFieldPriority
virtual DateTimeFieldPriority GetFieldPriority (DateTimeFieldType whichField) const
Interface Category:
API.
Purpose:
Returns the priority for a given field where the highest priority has a value of zero. The priority is used in resolving conflicting fields.
Calling Context:
Called internally by SetField and RollField.
Parameters:
- DateTimeFieldType whichField -The field to get the priority for.
Return Value:
The field priority.
Exceptions:
Throws an exception if whichField is out of bounds.
Concurrency:
Not multithread safe.
Other Considerations:
This function is pure virtual. Derived classes must override to specify priority.
Member Function: TCalendar::SetName
virtual void SetName (const TLocalizableName & calendarName)
Interface Category:
API.
Purpose:
Set the name of the calendar.
Calling Context:
Called to set the localizable name of the calendar.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Member Function: TCalendar::GetName
virtual void GetName (TLocalizableName & calendarName) const
Interface Category:
API.
Purpose:
Get the name of the calendar.
Calling Context:
Called to get the localizable name of the calendar.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Member Function: TCalendar::CreateCalendarForLocale
static TCalendar * CreateCalendarForLocale (const TLocale &)
Interface Category:
API.
Purpose:
Createx the calendar for the specified locale. Currently, it always returns a TGregorianCalendar.
Calling Context:
Called to create a calendar for the specified locale.
Parameters:
- const TLocale & -The locale for the calendar.
Return Value:
A pointer to the calendar for the locale. The caller owns the storage of the returned calendar.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.