Class: TPositionalNumberFormatter

Declaration: NumberFormat.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TNumberFormatter

Inherited By:

TFloatingPointNumberFormatter

Purpose:

This class, derived from TNumberFormatter, handles numbers expressed in a positionally based numbering system like that commonly used in the United States and Europe. This class handles integer values; derived classes add the ability to handle non-integer values.

Instantiation:

Always allocate on the heap.

Deriving Classes:

Derived classes must override TextToCanonicalNumber and CanonicalNumberToText. The system provides the derived classes TFloatingPointNumberFormatter and TRationalNumberFormatter.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TPositionalNumberFormatter::TPositionalNumberFormatter

TPositionalNumberFormatter ()
TPositionalNumberFormatter (const TNumerals &)
TPositionalNumberFormatter (const TPositionalNumberFormatter & format)

Interface Category:

API.

Purpose:

Default constructor. Creates a number formatter that uses a TUnicodeDecimalNumerals object.
Creates a number formatter that uses the specified TNumerals object for mapping characters to values.
Copy constructor.

Calling Context:

Called by the stream-in operators and directly to instantiate this class.
Called directly to create a number formatter that uses a TNumerals object other than TUnicodeDecimalNumerals.
Called to copy an object.

Parameters:

Takes no parameters.
const TNumerals & -The TNumerals object to be used by this formatter.
const TPositionalNumberFormatter & 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: TPositionalNumberFormatter::~TPositionalNumberFormatter

virtual ~ TPositionalNumberFormatter ()

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: TPositionalNumberFormatter::SetUpCanonicalNumberConverter

virtual void SetUpCanonicalNumberConverter ()

Interface Category:

API.

Purpose:

Sets up the canonical number converter for use in converting between binary numbers and text. It also calls the inherited function.

Calling Context:

Called during conversion operations.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPositionalNumberFormatter::TextToCanonicalNumber

virtual void TextToCanonicalNumber (const TText &, TCanonicalNumber &, TNumberScanResult &, const TTextRange &)

Interface Category:

API.

Purpose:

During a scanning operation, converts a text string into a TCanonicalNumber object. The scanning function then uses a TCanonicalNumberConverter to convert the canonical number to a binary number.

Calling Context:

Called by the Scan member function when converting a text string into a numeral.

Parameters:

const TText & -Contains the text string to scan.
TCanonicalNumber & -Receives the canonical number produced by the conversion.
TNumberScanResult & -Receives information about the result of the scanning operation.
const TTextRange & -Specifies the range of the text string to scan.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPositionalNumberFormatter::CanonicalNumberToText

virtual void CanonicalNumberToText (const TCanonicalNumber &, TText &, TNumberFormatResult &)

Interface Category:

API.

Purpose:

During a formatting operation, converts a TCanonicalNumber object into a text string. The formatting function first uses a TCanonicalNumberConverter to convert the binary number into the canonical number.

Calling Context:

Called by the Format function when converting a numeral into a text string.

Parameters:

const TCanonicalNumber & -Specifies the canonical number to convert.
TText & -Receives the text string produced by the conversion.
TNumberFormatResult & -Receives information about the result of the formatting operation.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPositionalNumberFormatter::GetDigitGroupSeparator

virtual void GetDigitGroupSeparator (TText &) const

Interface Category:

API.

Purpose:

Gets the text string used to separate groups of digits.

Calling Context:

Calling during the formatting operation.

Parameters:

TText & -Contains the text string used to separate groups of digits.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPositionalNumberFormatter::SetDigitGroupSeparator

virtual void SetDigitGroupSeparator (const TText &)

Interface Category:

API.

Purpose:

Sets the text string used to separate groups of digits.

Calling Context:

Call this function directly.

Parameters:

const TText & -Contains the text string used to separate groups of digits.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPositionalNumberFormatter::GetSeparatorSpacing

virtual TDigitCount GetSeparatorSpacing () const

Interface Category:

API.

Purpose:

Gets the number of digits displayed between digit group separators.

Calling Context:

Called during the formatting operation.

Parameters:

Takes no parameters.

Return Value:

Returns TDigitCount (unsigned short), which specifies the number of digits displayed between digit group separators.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPositionalNumberFormatter::SetSeparatorSpacing

virtual void SetSeparatorSpacing (TDigitCount)

Interface Category:

API.

Purpose:

Sets the number of digits displayed between digit group separators.

Calling Context:

Call this function directly.

Parameters:

TDigitCount -The number of digits to display between digit group separators.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPositionalNumberFormatter::GetIntegerSeparator

virtual bool GetIntegerSeparator () const

Interface Category:

API.

Purpose:

Queries whether this number formatter is set to display the digit group separator in the integer part of the number.

Calling Context:

Called during the formatting operation.

Parameters:

Takes no parameters.

Return Value:

Returns true if this number formatter is set to display the digit group separator in the integer part of the number.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPositionalNumberFormatter::SetIntegerSeparator

virtual void SetIntegerSeparator (bool)

Interface Category:

API.

Purpose:

Specifies whether this number formatter should display the digit group separator in the integer part of the number.

Calling Context:

Call this function directly.

Parameters:

bool -Set to true if this number formatter should display the digit group separator in the integer part of the number.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPositionalNumberFormatter::GetPrecision

virtual void GetPrecision (double & multiple, ERoundingType & rounding) const

Interface Category:

API.

Purpose:

Gets the precision of the number formatter, consisting of a multiple, which controls the interval for rounding, and the rounding type, which controls whether the rounding occurs up, down, or evenly.

Calling Context:

Called during the formatting operation.

Parameters:

double & multiple -Receives the multiple that defines the interval for rounding.
ERoundingType & rounding -Receives the rounding type.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPositionalNumberFormatter::SetPrecision

virtual void SetPrecision (double multiple, ERoundingType rounding)

Interface Category:

API.

Purpose:

Sets the precision of the number formatter, consisting of a multiple, which controls the interval for rounding, and the rounding type, which controls whether the rounding occurs up, down, or evenly.

Calling Context:

Call this function directly.

Parameters:

double & multiple -Receives the multiple that defines the interval for rounding.
ERoundingType & rounding -Receives the rounding type.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPositionalNumberFormatter::GetMinIntegerDigits

virtual TDigitCount GetMinIntegerDigits () const

Interface Category:

API.

Purpose:

Gets the minimum number of integer digits to display.

Calling Context:

Called during the formatting operation.

Parameters:

Takes no parameters.

Return Value:

Returns TDigitCount (unsigned short), which indicates the minimum number of integer digits to display.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPositionalNumberFormatter::SetMinIntegerDigits

virtual void SetMinIntegerDigits (TDigitCount)

Interface Category:

API.

Purpose:

Sets the minimum number of integer digits to display.

Calling Context:

Call this function directly.

Parameters:

TDigitCount -The minimum number of integer digits to display.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPositionalNumberFormatter::operator=

TPositionalNumberFormatter & operator =(const TPositionalNumberFormatter &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TPositionalNumberFormatter & -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: TPositionalNumberFormatter::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: TPositionalNumberFormatter::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 a TStandardException if the version of the formatter cannot be used on the current system.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPositionalNumberFormatter::IsEqual

virtual bool IsEqual (const MCollectible * obj) const

Interface Category:

API.

Purpose:

Compares two objects for equality.

Calling Context:

Called to compare compatible objects.

Parameters:

const MCollectible * obj -The MCollectible to be compared.

Return Value:

Returns true if the objects match.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPositionalNumberFormatter::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: TPositionalNumberFormatter::ScanDigits

virtual void ScanDigits (const TText &, TTextRange &, bool hasSeparator, double & scale, TCanonicalNumber & num, TNumberScanResult &)

Interface Category:

API.

Purpose:

Scans text and converts it into a number.

Calling Context:

Called during the scanning operation.

Parameters:

const TText & -The text string to scan.
TTextRange & -The range within the text string to scan.
bool hasSeparator -Flags whether the text contains digit group separators.
double & scale -Receives the converted number.
TCanonicalNumber & num -The canonical number produced during conversion.
TNumberScanResult & -Receives the results of the scanning operation.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPositionalNumberFormatter::GetDigitGroupSeparatorIterator

TTextIterator * GetDigitGroupSeparatorIterator () const

Interface Category:

API.

Purpose:

Gets the text iterator of the text string used to separate groups of digits.

Calling Context:

Called during the scanning operation.

Parameters:

None.

Return Value:

The pointer to the TTextIterator of the digit group separator string.

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.