Controlling basic TNumberFormatter behavior

• How positive and negative numbers are formatted
• The text to use to indicate infinity or NaNs
• The valid numeric range of each formatter and how out-of-bounds numbers are handled
• What character-value mapping is used

Classes derived from TNumberFormatter provide default functionality for all aspects of number formatting. You can use default number formatters in many situations simply by instantiating and calling the formatter. You can also use the number formatter specified by the current locale, using the identifier TLocale::kNumberFormatID. For example:

  TLocale currentLocale = TLocale::GetCurrentLocale();
  
  TLocaleItem<TNumberFormatter> item;
  TDeleterFor<TNumberFormatter> numberFormatter = 
          item.CopyItem( TLocale::kNumberFormatID, currentLocale );
  
  TStandardText numText;
  TNumberFormatResult result;
  
  numberFormatter->Format( TFormattableNumber(9999), numText, result );
  // numText now contains a formatted string representing the number 9999 in the
  // format specified by the current locale.

Formatting positive and negative numbers

• + 9,999
• - 9,999
• (9,999)

To set the affixes used to indicate the positive or negative signs, use the SetPlus or SetMinus member functions. These functions take text instances containing the affix strings. For example, to make the number formatter myNumberFormatter produce negative numbers formatted like (9,999), you might use the following code:

  UniChar px = TGeneralPunctuation::kLeftParenthesis;
  TStandardText prefix(&px, 1);
  UniChar sx = TGeneralPunctuation::kRightParenthesis;
  TStandardText suffix(&sx, 1);
  
  myNumberFormatter->SetMinus( prefix, suffix );

TNumberFormatter provides the following default behavior for sign indication:

	Sign	Prefix	Suffix	Example
	Positive	Empty string	Empty string	9,999
	Negative	TMathematicalOperators::kMinusSign	Empty string	-9,999

Setting text identifiers

To set a string to indicate infinity, use the TNumberFormatter::SetInfinitySign function. By default, number formatters use the Unicode character TMathematicalOperators::kInfinity ().

To set a string to indicate a NaN, use the TNumberFormatter::SetNanSign function. By default, number formatters use the Unicode character TGeneralPunctuation::kQuestionMark.

Setting the formatting range

To change the valid range for a number formatter, use the SetMinNumber and SetMaxNumber member functions. These functions take a double as the argument.

Each TNumberFormatter instance also has an associated number formatter that it uses whenever you ask it to handle any number out of its range. The TNumberFormatter default for this formatter is a TUniversalNumberFormatter that uses the digits in the Roman script. This number formatter has a universal range; it can handle any number, including NaNs. This mechanism guarantees that you get a result whenever you format a number, although it does not guarantee the level of accuracy.

Use the TNumberFormatter::AdoptOutOfBoundsNumberFormatter member function to change the default out-of-bounds number formatter--for example, to use a formatter other than TUniversalNumberFormatter or to create a localized instance of TUniversalNumberFormatter that uses digits other than those in the Roman script. This function checks the range of the formatter before adopting it to ensure that it has a larger range than the original formatter.

Mapping characters to numeric values

The system currently provides two concrete subclasses of TNumerals--TUnicodeDecimalNumerals and THybridNumerals. Use TUnicodeDecimalNumerals for a mapping of the characters and associated digit values defined by Unicode, and use THybridNumerals for arbitrary character-value mappings.

Using TUnicodeDecimalNumerals

During text scanning, the TUnicodeDecimalNumerals::NumeralToValue function accepts any character defined by Unicode as a digit and converts it to the corresponding value. Character-value mappings can be many-to-one. For example, the TUnicodeDigit characters kArabicIndicOne, kMalayalamOne, and kDevanagariOne all map to the value 1.

During formatting, the TUnicodeDecimalNumerals::ValueToNumeral function formats a numeric value into a character based on the mappings for a particular script. For example, when the function receives the value 1, it needs to know what script to use so that it knows whether kArabicIndicOne, kDevanagariOne, or some other character is appropriate.

You can specify a script when you instantiate TUnicodeDecimalNumerals, or later with the TUnicodeDecimalNumerals::SetScript member function. Specify the script with a TUnicode::EUnicodeScript value. The default value is EUnicodeScript::kRoman.

TPositionalNumberFormatter, TFloatingPointNumberFormatter, and TRationalNumberFormatter use this type of TNumerals by default.

Using THybridNumerals

The set of scanning pairs can represent many-to-one relationships; multiple scanning pairs can map different Unicode characters to the same value. For example, in the Roman numeral system, the characters i and I can both map to the value 1. You add a pair to the set of scanning pairs with the THybridNumerals::AddScanningPair member function.

The set of formatting pairs defines one-to-one relationships, and each numerical value can be mapped to only one Unicode character. For example, in the Roman numeral system, you have to choose whether to convert the value 1 into the character i or I. You add a pair to the set of formatting pairs with the THybridNumerals::AddFormattingPair member function.

NOTE When you add a formatting pair, the AddFormattingPair function also adds the pair to the set of scanning pairs.

A THybridNumerals object owns the scanning and formatting pairs, as shown in this figure:

You can also retrieve formatting and scanning pairs with the THybridNumerals functions GetFormattingPair and GetScanningPair:

  void GetFormattingPair ( unsigned short index, UniChar& numeral, long& value ) const;
  void GetScanningPair( unsigned short index, UniChar& numeral, long& value ) const;