Class: TChoiceFormatter

Declaration: Formatter.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TFormatter

Inherited By:

None.

Purpose:

Encapsulates a list of TParameterFormatter objects, identified by numbers. During formatting, the correct TParameterFormatter is chosen based on the value of the parameter. TChoiceFormatter is used within a TParameterFormatter to provide a nested structure.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Clients that want to do other types of conditional formatting, for example, using text rather than numbers as the basis for selection, should derive from this class.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TChoiceFormatter::TChoiceFormatter

TChoiceFormatter ()
TChoiceFormatter (const TChoiceFormatter & toCopy)

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 TChoiceFormatter & toCopy -The object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TChoiceFormatter::~TChoiceFormatter

~ TChoiceFormatter ()

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: TChoiceFormatter::operator=

TChoiceFormatter & operator =(const TChoiceFormatter & toCopy)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TChoiceFormatter & toCopy -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: TChoiceFormatter::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: TChoiceFormatter::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: TChoiceFormatter::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: TChoiceFormatter::Format

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

Interface Category:

API.

Purpose:

Based on the value of a parameter, chooses the correct TParameterFormatter to use.

Calling Context:

Called when Format is called from the TParameterFormatter object to which this choice formatter is attached. Call this function directly when TChoiceFormatter is used independently.

Parameters:

const TFormattable & valueList -The value to use to select a formatter.
TText & text -Receives the formatted text.
TFormatResult & conversionResult -Receives the results of the formatting.

Return Value:

None.

Exceptions:

Throws an exception if an incompatible formattable or format result is passed in.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TChoiceFormatter::Scan

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

Interface Category:

API.

Purpose:

Scans a text string, and by matching the text to its associated value in this formatter, assigns this value to the formattable for this parameter.

Calling Context:

Called when Scan is called from the TParameterFormatter object to which this choice formatter is attached. Call this function directly when TChoiceFormatter is used independently.

Parameters:

const TText & text -The text to scan in.
const TTextRange & inputRange -The range of text to scan in.
TFormattable & value -Receives the value of the matched text.
TScanResult & conversionResult -Receives the results of the scanning.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TChoiceFormatter::SetUseLongestMatchLength

virtual void SetUseLongestMatchLength (bool flag)

Interface Category:

API.

Purpose:

Specifies whether to match text to a choice using the maximum possible number of characters. For example, if you are matching January and the choice values are Jan and January, it matches the first one. Set this option to true to force maximum matching. By default, it does not match the maximum possible number of characters. When this flag is set to true, the choice formatter picks the choice that has the highest confidence and the longest match length.

Calling Context:

Called to change the current setting for this option. Call this function directly.

Parameters:

bool flag -The setting for this option.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TChoiceFormatter::GetUseLongestMatchLength

virtual bool GetUseLongestMatchLength () const

Interface Category:

API.

Purpose:

Queries whether this formatter should match the maximum possible number of characters.

Calling Context:

Called during scanning to determine the behavior of the formatter.

Parameters:

Takes no parameters.

Return Value:

Returns true if the formatter should match the maximum possible number of characters.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TChoiceFormatter::ClearAllPatterns

virtual void ClearAllPatterns ()

Interface Category:

API.

Purpose:

Deletes all formatters attached to this choice formatter.

Calling Context:

Called to reuse this formatter.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TChoiceFormatter::CreateFormattable

virtual TFormattable * CreateFormattable () const

Interface Category:

API.

Purpose:

Creates an object of the TFormattable class used by this formatter, TFormattableNumber.

Calling Context:

Called during the scanning operation.

Parameters:

Takes no parameters.

Return Value:

An object of TFormattableNumber.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TChoiceFormatter::CreateScanResult

virtual TScanResult * CreateScanResult () const

Interface Category:

API.

Purpose:

Creates an object of the TScanResult class used by this formatter.

Calling Context:

Called during the scanning operation.

Parameters:

Takes no parameters.

Return Value:

An object of the TScanResult used by this formatter.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TChoiceFormatter::CreateFormatResult

virtual TFormatResult * CreateFormatResult () const

Interface Category:

API.

Purpose:

Creates an object of the TFormatResult class used by this formatter.

Calling Context:

Called during the formatting operation.

Parameters:

Takes no parameters.

Return Value:

An object of the TFormatResult class used by this formatter.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TChoiceFormatter::SetChoice

virtual void SetChoice (const TParameterFormatter & text, double startValue =TChoiceFormatter :: kDefaultChoiceValue, double endValue =TChoiceFormatter :: kDefaultChoiceValue)

Interface Category:

API.

Purpose:

Set a value to the specified text (which is a TParameterFormatter).

Calling Context:

Called when user wants to assign a value or a range of value for a specific choice.

Parameters:

const TParameterFormatter & text -The text for a specific range of value. The text is in the form of a TParameterFormatter so that user can have nested formatters within the text.
double startValue =TChoiceFormatter :: kDefaultChoiceValue -The start value for the range.
double endValue =TChoiceFormatter :: kDefaultChoiceValue -The end value for the range.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.