Class: TParameterFormatter

Declaration: Formatter.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TFormatter

Inherited By:

TDateTimePattern

Purpose:

Takes a list of parameters, each one wrapped by a TFormattable object, and formats them into text. The formatted parameters are inserted into a text template that you specify. TParameterFormatter also performs the reverse action, scanning a text string into a set of TFormattable objects.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Clients that want to do more sophisticated parameter-based scanning and formatting can derive from this class.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TParameterFormatter::~TParameterFormatter

~ TParameterFormatter ()

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

TParameterFormatter & operator =(const TParameterFormatter & toCopy)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

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

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

Interface Category:

API.

Purpose:

Formats a list of TFormattable parameters. This function first verifies that the formattable, formatter, and format result for each parameter are compatible, and then calls each formatter. The output strings are then inserted into the appropriate ranges of the text template for this parameter formatter.

Calling Context:

Call this function directly.

Parameters:

const TFormattable & valueList -The list of TFormattable parameters.
TText & text -Receives the output text.
TFormatResult & conversionResult -Receives the format results for the operation. Returns a TFormatResult object for each parameter.

Return Value:

None.

Exceptions:

Throws an exception if the TFormattable argument for any parameter is not compatible with the attached formatter.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TParameterFormatter::Scan

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

Interface Category:

API.

Purpose:

Scans a text string, parsing it into a list of TFormattable objects based on this formatter's text template.

Calling Context:

Call this function directly.

Parameters:

const TText & text -The text string to scan.
const TTextRange & inputRange -The range of the text string to scan.
TFormattable & valueList -Receives the scanned in values.
TScanResult & conversionResult -Receives the scan results for the operation. Returns a TScanResult object for each parameter.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TParameterFormatter::SetTemplate

virtual void SetTemplate (const TText & textTemplate)

Interface Category:

API.

Purpose:

Attaches a text template to this formatter.

Calling Context:

Call this function directly.

Parameters:

const TText & textTemplate -The text template.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TParameterFormatter::GetTemplate

virtual void GetTemplate (TText & textTemplate) const

Interface Category:

API.

Purpose:

Returns a copy of the text template attached to this formatter.

Calling Context:

Called to get a copy of the text template attached to this formatter.

Parameters:

TText & textTemplate -The text template.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TParameterFormatter::SetTextMatch

virtual void SetTextMatch (const TTextRange & range, const TTextMatch & aTextMatch)

Interface Category:

API.

Purpose:

Attaches an alternate text match to a particular range of the text template. This is used during scanning, allowing this formatter to accurately parse a wider range of input strings.

Calling Context:

Called to attach an alternate text match to a range of the template. Call this function directly.

Parameters:

const TTextRange & range -The range to attach the alternate match to.
const TTextMatch & aTextMatch -The alternate text match.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TParameterFormatter::ClearAllTextMatch

virtual void ClearAllTextMatch ()

Interface Category:

API.

Purpose:

Deletes all the alternate text matches attached to this formatter.

Calling Context:

Called to clear the formatter of any alternate text matches. For example, call this function if you attach a different template to the 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: TParameterFormatter::CreateFormattable

virtual TFormattable * CreateFormattable () const

Interface Category:

API.

Purpose:

Creates an object of the formattable class, TFormattableParameterList, used by this formatter.

Calling Context:

Called during the scanning operation.

Parameters:

Takes no parameters.

Return Value:

An empty TFormattableParameterList object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TParameterFormatter::CreateScanResult

virtual TScanResult * CreateScanResult () const

Interface Category:

API.

Purpose:

Creates an object of the scan result class, TParameterScanResult, used by this formatter.

Calling Context:

Called during the scanning operation.

Parameters:

Takes no parameters.

Return Value:

An empty TParameterScanResult object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TParameterFormatter::CreateFormatResult

virtual TFormatResult * CreateFormatResult () const

Interface Category:

API.

Purpose:

Creates an object of the format result class, TParameterFormatResult, used by this formatter.

Calling Context:

Called during the formatting operation.

Parameters:

Takes no parameters.

Return Value:

An empty TParameterFormatResult object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TParameterFormatter::SetParameterType

virtual void SetParameterType (ParameterIndex aParameterNumber, const ClassName & aClassName)

Interface Category:

API.

Purpose:

Sets the parameter type for a parameter within this parameter formatter.

Calling Context:

Called when creating the parameter formatter to set the type for each parameter. Call this function directly.

Parameters:

ParameterIndex aParameterNumber -The parameter to set the type for.
const ClassName & aClassName -The class name identifying the type of this parameter.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TParameterFormatter::GetParameterType

virtual bool GetParameterType (ParameterIndex aParameterNumber, ClassName & aClassName)

Interface Category:

API.

Purpose:

Queries whether a particular parameter is of the specified type.

Calling Context:

Called to get the type of a particular parameter. Called during type checking when a formatter is attached to a parameter with SetParameterFormat.

Parameters:

ParameterIndex aParameterNumber -The parameter to check the type for.
ClassName & aClassName -The class name.

Return Value:

Returns true if this parameter is of the type identified by the class name argument.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TParameterFormatter::SetParameterFormat

virtual void SetParameterFormat (const TTextRange & range, ParameterIndex aParameterNumber, const TFormatter & formatter)

Interface Category:

API.

Purpose:

Attaches a formatter to the parameter at the specified index. The parameter formatter clones the formatter.

Calling Context:

Called when creating the parameter formatter to attach a formatter to each parameter. Called during localization to attached a localized formatter to each parameter. Call this function directly.

Parameters:

const TTextRange & range -The range of this parameter within the text template.
ParameterIndex aParameterNumber -The index of the parameter.
const TFormatter & formatter -The formatter to attach.

Return Value:

None.

Exceptions:

Throws an exception if the formatter being attached does not match the parameter type as set by the SetParameterType function.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TParameterFormatter::ClearParameterFormat

virtual void ClearParameterFormat (const TTextRange & range)

Interface Category:

API.

Purpose:

Deletes the formatter attached to the specified range. The text template is not modified at all.

Calling Context:

Called when replacing a formatter or the text template.

Parameters:

const TTextRange & range -The text range to delete the formatter from.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TParameterFormatter::OverlappedRange

bool OverlappedRange (const TTextRange & range) const

Interface Category:

API.

Purpose:

Determines whether a particular range in the text template already has a formatter or an alternate text match attached to it.

Calling Context:

Called by SetParameterFormat and SetTextMatch to verify that formatters and alternate text matches are not attached to overlapping ranges.

Parameters:

const TTextRange & range -The range to check for a formatter or an alternate text match.

Return Value:

Returns true if the range has an associated formatter or alternate text match.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TParameterFormatter::GetMaxParameterCount

virtual ParameterCount GetMaxParameterCount () const

Interface Category:

API.

Purpose:

Returns the maximum number of defined parameters. This might not equal the actual number of attached formatters, if some parameter indexes are empty.

Calling Context:

Called to get the maximum number of defined parameters for this formatter.

Parameters:

Takes no parameters.

Return Value:

The maximum number of defined parameters for this formatter.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TParameterFormatter::TParameterFormatter

TParameterFormatter ()
TParameterFormatter (const TParameterFormatter & toCopy)
TParameterFormatter (TTextOrder * textOrderToAdopt)
TParameterFormatter (const TText & textTemplate, TTextOrder * textOrderToAdopt =NIL)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.
Construct a TParameterFormatter using a specific TTextOrder.
Construct a TParameterFormatter using a specific text template and text order.

Calling Context:

Called by the stream-in operators and as a default constructor.
Called to copy an object.
Called when user wants to specify a specific text order for this formatter.
Called when user wants to specify a specific text order and a specific text template for this formatter.

Parameters:

Takes no parameters.
const TParameterFormatter & toCopy -The object to be copied.
TTextOrder * textOrderToAdopt -The pointer of the text order to be adopted.
const TText & textTemplate -The specific text template to be used.
TTextOrder * textOrderToAdopt =NIL -The pointer of the text order to be adopted.

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.