CNumberFormatter

All Packages | Methods

CNumberFormatter provides number localization functionalities.

CNumberFormatter formats a number (integer or float) and outputs a string based on the specified format. A CNumberFormatter instance is associated with a locale, and thus generates the string representation of the number in a locale-dependent fashion.

CNumberFormatter currently supports currency format, percentage format, decimal format, and custom format. The first three formats are specified in the locale data, while the custom format allows you to enter an arbitrary format string.

A format string may consist of the following special characters:

• dot (.): the decimal point. It will be replaced with the localized decimal point.
• comma (,): the grouping separator. It will be replaced with the localized grouping separator.
• zero (0): required digit. This specifies the places where a digit must appear (will pad 0 if not).
• hash (#): optional digit. This is mainly used to specify the location of decimal point and grouping separators.
• currency (¤): the currency placeholder. It will be replaced with the localized currency symbol.
• percentage (%): the percentage mark. If appearing, the number will be multiplied by 100 before being formatted.
• permillage (‰): the permillage mark. If appearing, the number will be multiplied by 1000 before being formatted.
• semicolon (;): the character separating positive and negative number sub-patterns.

Anything surrounding the pattern (or sub-patterns) will be kept.

The followings are some examples:

Pattern "#,##0.00" will format 12345.678 as "12,345.68".
Pattern "#,#,#0.00" will format 12345.6 as "1,2,3,45.60".

Note, in the first example, the number is rounded first before applying the formatting. And in the second example, the pattern specifies two grouping sizes.

CNumberFormatter attempts to implement number formatting according to the Unicode Technical Standard #35. The following features are NOT implemented:

• significant digit
• scientific format
• arbitrary literal characters
• arbitrary padding

array(
	// number of required digits after the decimal point,
	// will be padded with 0 if not enough digits,
	// -1 means we should drop the decimal point
	'decimalDigits'=>2,
	// maximum number of digits after the decimal point,
	// additional digits will be truncated.
	'maxDecimalDigits'=>3,
	// number of required digits before the decimal point,
	// will be padded with 0 if not enough digits
	'integerDigits'=>1,
	// the primary grouping size, 0 means no grouping
	'groupSize1'=>3,
	// the secondary grouping size, 0 means no secondary grouping
	'groupSize2'=>0,
	'positivePrefix'=>'+',  // prefix to positive number
	'positiveSuffix'=>'',   // suffix to positive number
	'negativePrefix'=>'(',  // prefix to negative number
	'negativeSuffix'=>')',  // suffix to negative number
	'multiplier'=>1,        // 100 for percent, 1000 for per mille
);