Class: TDateTimeFormatter

Declaration: DateTime.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TFormatter

Inherited By:

TPatternBasedDateTimeFormatter

Purpose:

An abstract base class for formatting and scanning date/time information. It defines the protocol to map a TTime or set of fields to textual representation and vice versa. The mappings can have variations, such as abbreviated month names, or 2/4 digit years. For example, text field values can include text such as Sept., September, Oct., October, Friday, and so on. Any field can have text representations--some calendars have names for the days of the month. TDateTimeFormatter descends from TFormatter and can be used in a TParameterFormatter. This class uses a TCalendar internally to map TTime to TDateTimeFields. Note that a date/time formatter only works correctly with a single TCalendar. For each TCalendar derived class, there should be at least one corresponding TDateTimeFormatter derived class. For example, TGregorianCalendar and TGregorianDateTimeFormatter, TLunarCalendar and TLunarDateTimeFormatter, and so on.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

TDateTimeFormatter is an abstract base class. Deriving classes must override the pure virtual functions TimeToText, TextToTime, and GetCalendar. The concrete class TGregorianDateTimeFormatter is provided.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TDateTimeFormatter::~TDateTimeFormatter

virtual ~ TDateTimeFormatter ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDateTimeFormatter::Format

virtual void Format (const TFormattable & value, TText & text) const
virtual void Format (const TFormattable & value, TText & text, TFormatResult & conversionResult) const

Interface Category:

API.

Purpose:

Given a TFormattableTime value, returns the formatted text.
Given a TFormattableTime value, returns the formatted text. Also returns information about the accuracy of the formatting.

Calling Context:

Call this function directly.
Call this function directly.

Parameters:

const TFormattable & value -The value to format.
TText & text -Receives the formatted text.
const TFormattable & value -The value to format.
TText & text -Receives the formatted text.
TFormatResult & conversionResult -Receives information about the accuracy of the formatting operation.

Return Value:

None.

Exceptions:

Throws an exception if the TFormattable argument is not a TFormattableTime object.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDateTimeFormatter::Scan

virtual void Scan (const TText & text, const TTextRange & inputRange, TFormattable & value, TScanResult & conversionResult) const

Interface Category:

API.

Purpose:

Given a text object, scans and parses it to return a time value.

Calling Context:

Call this function directly.

Parameters:

const TText & text -The input text to scan.
const TTextRange & inputRange -The range of text to scan.
TFormattable & value -Receives the resulting time value.
TScanResult & conversionResult -Receives information about the accuracy of the scanning operation.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDateTimeFormatter::CreateFormattable

virtual TFormattable * CreateFormattable () const

Interface Category:

API.

Purpose:

Creates the formattable, TFormattableTime, used for this formatter.

Calling Context:

Called by the Scan function.

Parameters:

Takes no parameters.

Return Value:

Returns a TFormattableTime object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDateTimeFormatter::CreateScanResult

virtual TScanResult * CreateScanResult () const

Interface Category:

API.

Purpose:

Creates the scanning accuracy result object, TScanResult, used by this formatter.

Calling Context:

Called by the Scan function.

Parameters:

Takes no parameters.

Return Value:

Returns a TScanResult object. The caller owns the storage.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDateTimeFormatter::CreateFormatResult

virtual TFormatResult * CreateFormatResult () const

Interface Category:

API.

Purpose:

Creates the formatting accuracy result object, TFormatResult, used by this formatter.

Calling Context:

Called by the Format function.

Parameters:

Takes no parameters.

Return Value:

Returns a TFormatResult object. The caller owns the storage.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDateTimeFormatter::SetMilitaryTime

virtual void SetMilitaryTime (bool flag)

Interface Category:

API.

Purpose:

Specifies whether military time (24-hour clock) should be used. For example, 15:00 instead of 3:00 p.m.

Calling Context:

Call this function directly.

Parameters:

bool flag -Whether or not military time should be used.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDateTimeFormatter::IsMilitaryTime

virtual bool IsMilitaryTime () const

Interface Category:

API.

Purpose:

Queries whether military time (24 hour clock) should be used. For example, 15:00 instead of 3:00 p.m..

Calling Context:

Called during conversion operations to query this field.

Parameters:

Takes no parameters.

Return Value:

Returns true if military time should be used.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDateTimeFormatter::SetAbbreviateYear

virtual void SetAbbreviateYear (bool flag)

Interface Category:

API.

Purpose:

Specifies whether the year should be abbreviated to two digits. For example, '93 instead of 1993.

Calling Context:

Call this function directly.

Parameters:

bool flag -Whether or not the year should be abbreviated to two digits.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDateTimeFormatter::IsAbbreviateYear

virtual bool IsAbbreviateYear () const

Interface Category:

API.

Purpose:

Queries whether the year should be abbreviated to two digits. For example, '93 instead 1993.

Calling Context:

Called during conversion operations to query this field.

Parameters:

Takes no parameters.

Return Value:

Returns true if the year should be abbreviated to two digits.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDateTimeFormatter::SetNumberFormat

virtual void SetNumberFormat (const TNumberFormatter & format)

Interface Category:

API.

Purpose:

Specifies the number formatter to be used by this formatter.

Calling Context:

Called to specify a number formatter for use when formatting numeric fields.

Parameters:

const TNumberFormatter & format -The number formatter to be used by this formatter.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDateTimeFormatter::SetFlexibleScanning

virtual void SetFlexibleScanning (bool flag)

Interface Category:

API.

Purpose:

Specifies whether flexible scanning should be used; that is, whether or not the scanning operation should allow alternate text matches. The scanning operation is faster when it does not perform flexible scanning, but this limits the range of input. By default, flexible scanning is performed.

Calling Context:

Call this function directly.

Parameters:

bool flag -Whether or not flexible scanning should be used.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDateTimeFormatter::GetFlexibleScanning

bool GetFlexibleScanning () const

Interface Category:

API.

Purpose:

Queries whether flexible scanning should be used.

Calling Context:

Called during the scanning operation to query this field.

Parameters:

Takes no parameters.

Return Value:

Returns true if flexible scanning should be used.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDateTimeFormatter::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value.

Calling Context:

Called to generate a hash value.

Parameters:

Takes no parameters.

Return Value:

The numeric value of the hash.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDateTimeFormatter::operator=

TDateTimeFormatter & operator =(const TDateTimeFormatter & format)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TDateTimeFormatter & format -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: TDateTimeFormatter::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: TDateTimeFormatter::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: TDateTimeFormatter::TDateTimeFormatter

TDateTimeFormatter ()
TDateTimeFormatter (const TDateTimeFormatter & format)

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 TDateTimeFormatter & format -The object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDateTimeFormatter::TimeToText

virtual void TimeToText (TCalendar & calendar, TText & text, TFormatResult & result) const

Interface Category:

API.

Purpose:

Converts the time as represented in the calendar to a textual form. Also returns the format accuracy result.

Calling Context:

Called during the formatting operation.

Parameters:

TCalendar & calendar -The calendar with the time to be formatted.
TText & text -Receives the output text.
TFormatResult & result -Receives the formatting accuracy result.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDateTimeFormatter::TextToTime

virtual void TextToTime (const TText & text, const TTextRange & inputRange, TCalendar & calendar, TScanResult & result) const

Interface Category:

API.

Purpose:

Scans a text object and attempts to parse it into date/time information, setting the fields of a calendar accordingly. It also returns the scan accuracy result.

Calling Context:

Called during the scanning operation.

Parameters:

const TText & text -The text to scan.
const TTextRange & inputRange -The range of text to scan.
TCalendar & calendar -The calendar whose fields are set according to the scanned values.
TScanResult & result -Receives the scanning accuracy result.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDateTimeFormatter::GetCalendar

virtual TCalendar * GetCalendar () const

Interface Category:

API.

Purpose:

A given formatter only works in conjunction with a particular calendar. Hence, this pure virtual function is overridden by the derived class to provide an appropriate calendar.

Calling Context:

Called by Format and Scan.

Parameters:

Takes no parameters.

Return Value:

Returns the appropriate TCalendar derived class.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDateTimeFormatter::GetNumberFormatter

TNumberFormatter * GetNumberFormatter () const

Interface Category:

API.

Purpose:

Returns the number formatter used by this formatter.

Calling Context:

Call by format and scan.

Parameters:

Takes no parameters.

Return Value:

Returns the number formatter.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDateTimeFormatter::SetCalendar

virtual void SetCalendar (const TCalendar & calendar)

Interface Category:

API.

Purpose:

Set the calendar for the formatter.

Calling Context:

Called to set the calendar for the formatter.

Parameters:

const TCalendar & calendar -the calendar to be used by the formatter.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Member Function: TDateTimeFormatter::SetName

virtual void SetName (const TLocalizableName & name)

Interface Category:

API.

Purpose:

Set the localizable name of the formatter.

Calling Context:

Called to set the localizable name of the formatter.

Parameters:

const TLocalizableName & name -the localizable name of the formatter.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Member Function: TDateTimeFormatter::GetName

virtual void GetName (TLocalizableName & name) const

Interface Category:

API.

Purpose:

Get the localizable name of this formatter.

Calling Context:

Called to get the localizable name of the formatter.

Parameters:

TLocalizableName & name -the localizable name of the formatter.

Return Value:

None.

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.