Using TNumberFormatter subclasses

• TPositionalNumberFormatter (for integral and floating-point numbers)
• TRationalNumberFormatter
• TAdditiveNumberFormatter
• TOutlineNumberFormatter

Formatting integers

TPositionalNumberFormatter uses an instance of TUnicodeDecimalNumerals to determine character-value mappings (see "Using TUnicodeDecimalNumerals" on page 236).

Here are some examples of formatted numbers produced by a TPositionalNumberFormatter with default behavior:

• 1
• 9,999
• -9,999

	Member function	Description	Default
	SetDigitGroupSeparator	Sets the text used to separate groups of digits within an integer (for example, the comma in the number 1,000,000).	TGeneralPunctuation:: kComma
	SetIntegerSeparator	Indicates whether the digit group separator should be used.	True
	SetSeparatorSpacing	Sets the number of digits in each group separated by the digit group separator (for example, 3 in the number 1,000,000).	3
	SetPrecision	Controls how to round a number during conversion to text. Two parameters control rounding:
		Increment value, or number that rounded numbers should be a multiple of. For example, you might round currency amounts to multiples of 1,000.	0
		ERoundingType value, specifying whether numbers are rounded up, down, or to the closest increment value.	kRoundUp
	SetMinIntegerDigits	Sets the minimum number of digits to insert when converting a number to text (also known as zero-padding).	0

The system also provides TFloatingPointNumberFormatting, derived from TPositionalNumberFormatter, that handles non-integer values.

Formatting floating-point numbers

Here are some examples of formatted numbers produced by a TFloatingPointNumberFormatter with default behavior:

• 1
• 9,999.99999
• -9,999.99999
• 9.009E+9

	Member function	Description	Default
	SetDecimalSeparator	Sets the text used to separate the left (integer) value from the right (decimal) value.	TGeneralPunctuation:: kFullStop
	SetDecimalWithInteger	Indicates whether to include the decimal separator when the value is an integer (it has no value to the right of the decimal separator).	False
	SetUpperExponentThreshold	Sets the upper limit of the range within which numbers are formatted in decimal points; above this limit, numbers are formatted using exponential notation.	1,000,000 (1E+6)
	SetLowerExponentThreshold	Sets the lower limit of the range within which numbers are formatted in decimal points; below this limit, numbers are formatted using exponential notation.	0.0000001 (1E-6)
	SetExponentSeparatorText	Sets the text used to separate the decimal value from the exponential factor (for example, the E in 1.23E+4, or the x10 in 1.23x104).	TLatin::kCapitalLetterE
	SetFractionSeparator	Indicates whether to display the digit group separator set by the SetDigitGroupSeparator function in the right (decimal) part of the value (for example, the second comma in 1,234.567,89).	False
	SetMinFractionDigits	Sets the minimum number of digits displayed in the non-integer part of the value.	0
	SetMaxFractionDigits	Sets the maximum number of digits displayed in the non-integer part of the value.	6
	SetExponentPhase	Sets a number that the exponent must be a multiple of. For example, if the phase is 3, the behavior for formatting multiples of 10 from the number 1.23 is: 1.23E+0, 12.3E+0, 123.0E+0, 1.23E+3, 12.3E+3, and so on.	1
	SetShowBaseType	Indicates EShowBaseType value specifying whether to display the base number used for exponential notation. For example, the notation 1.23E+4 does not display the base, while the notation 1.23E10+4 does.	kDontShowBase
	SetExponentStyle	Sets a character style set for use when formatting the exponent into text (for example, superscripting the exponent results in the format 1.23x104).	Empty style set

Formatting rational numbers

NOTE In a future release, TRationalNumberFormatter will support scanning Unicode characters representing fractions (such as TLatin1::kVulgarFractionOneHalf) and converting them to values.

Here are some examples of formatted numbers produced by a default TRationalNumberFormatter object:

• 1
• 3 ¹/₇
• -9,999 ⁴/₉

TRationalNumberFormatter provides member functions allowing you to control the following aspects of formatting fractions:

	Member function	Description	Default
	SetVariance	Sets the precision requirement for how close the text representation must be to the actual value.	0.0000005
	SetFractionSpace	Sets the text used to separate the integer part of the value from the fraction.	TASCII::kSpace
	SetFractionSign	Sets the text used to separate the numerator from the denominator.	TGeneralPunctuation:: kFractionSlash
	SetFractionPropriety	Indicates EFractionPropriety value specifying whether formatted fractions are proper (the numerator is always less than the denominator and the integer value is expressed separately, as in 3 1/7) or improper (the numerator can be greater than the denominator, as in 22/7).	kProperFraction
	SetSuperscriptUse	Indicates whether the numerator should be superscripted and the denominator subscripted, as in 1/2, or not, as in 1/2. If the fraction direction is reset (see the description of SetFractionDirection), the denominator is superscripted and the numerator is subscripted.	True
	SetNumeratorStyle	Sets a character style set for use when formatting the numerator into text.	Empty style set
	SetDenominatorStyle	Sets a character style set for use when formatting the denominator into text.	Empty style set
	AdoptIntegerFormat	Sets a number formatter for use on each integer portion within the value (the integer, the numerator, and the denominator).	TPositionalNumberFormatter instance using TUnicodeDecimalNumerals
	SetFractionDirection	Indicates EFractionDirection value specifying whether the numerator or the denominator appears first.	kNumeratorFirst

Formatting in additive numbering systems

TAdditiveNumberFormatter uses an instance of THybridNumerals to determine character-value mappings (see "Using THybridNumerals" on page 237). Classes created to support a specific numbering system create, by default, an instance of THybridNumerals containing the appropriate data for the numbering system. Call the TNumberFormat::SetNumerals member function to use a different THybridNumerals instance.

THybridNumberFormatter, a special subclass, can handle any numbering system in which numbers above a certain threshold are expressed in a multiplicative way; you always create your own THybridNumerals instances for use by this class if you instantiate it directly.

The system provides the following classes for specific numbering systems:

• THanNumberFormatter, derived from THybridNumberFormatter, handles the Han numbering system used in parts of East Asia.
• THebrewNumberFormatter, derived from TAdditiveNumberFormatter, handles Hebrew numerals.
• TRomanNumberFormatter, derived from TAdditiveNumberFormatter, handles Roman numerals.

There are currently several variations of the Han numbering system in use. The standard system used most frequently provides a uniform approach for writing numbers up to the value 99,999. Larger numbers are written using one of three systems:

• The xiadeng (low-level) system
• The zhongdeng (mid-level) system
• The shangdeng (upper-level) system

Other Han numbering variations are based on Western numbers and are positional rather than hybrid. There is also a variation in which special shortened forms of the numbers 21 through 39 (called calendar numbers) are used.

THanNumberFormatter supports each of these variations. You can identify the numbering system with a THanNumberFormatter::EHanNumberType value, using the SetHanNumberType member function. The default behavior is to use the standard numbering system.

When formatting from numbers to text, THanNumberFormatter also lets you choose between traditional character forms and the simplified character forms commonly used in the People's Republic of China. THanNumberFormatter recognizes both set of characters when parsing text. Use the SetHanSimplification member function to set this field, which takes a THanNumberFormatter::EHanSimplification value. The default behavior is to format numbers using the traditional characters.

Formatting Hebrew numbers

THebrewNumberFormatter can also distinguish standard Hebrew numerals from the cabalistic numerals used in medieval Jewish documents. This distinction is specified by THebrewNumberFormatter::EHebrewNumeralType. The system does not, however, support formatting cabalistic numbers.

Formatting Roman numbers

TRomanNumberFormatter accurately parses either uppercase or lowercase characters. However, you control whether numbers are formatted into uppercase or lowercase during conversion to text. Use the SetRomanNumeralCase member function to control this feature. This function takes an ERomanNumeralCase value; the default value is kUpperCase.

TRomanNumberFormatter also supports several different variations of the Roman numbering system that use the subtractive principle (expressing 4 as IV rather than IIII) to different degrees. Each system is identified by an ERomanNumeralType value, as described in this table.

	ERomanNumeralType	4	8	9	1999
	kShort	IV	IIX	IX	IM
	kNormalLong4Long8	IIII	VIII	IX	MCMXCIX
	kNormalLong4Short8	IIII	IIX	IX	MCMXCIX
	kNormalShort4Long8	IV	VIII	IX	MCMXCIX
	kNormalShort4Short8	IV	IIX	IX	MCMXCIX
	kLong	IIII	VIII	VIIII	MDCCCCLXXXXVIIII

Use the SetRomanNumeralType member function to specify one of these types. The default type used is kNormalShort4Long8.

TRomanNumberFormatter lets you use one more variation of the Roman numbering system. In some contexts the letter J is used instead of I for the last character in a numeral--for example, VJ instead of VI. Use the SetTerminatesWithJ member function to implement this formatting variation. The default behavior is to terminate numerals with I.

Creating hybrid number formatters

To create a THybridNumberFormatter for this type of system:

1. Instantiate THybridNumerals with data that correctly maps characters to values (for example, maps the character THanNumeral::kOne to the values 1, 10, 100, and so on).
   
2. Instantiate THybridNumberFormatter, passing in your THybridNumerals instance and setting the multiplicative threshold as appropriate.
   

To implement a TOutlineNumberFormatter:

1. Create an instance of THybridNumerals containing the character-value mappings you want to use.
   
2. Instantiate TOutlineNumberFormatter, passing in your THybridNumerals instance.