IntlFormatNumber

Synopsis

Description

You can create your own NumericSpec structure which lets you use intlFormatNumber() to handle custom formatting needs. The fields in the structure have the following meaning:

• ns_PosGroups =A GroupingDesc value defining how digits are grouped to the left of the decimal character. A GroupingDesc is simply a 32-bit bitfield. Every ON bit in the bitfield indicates that the separator sequence should be inserted after the associated digit. So if the third bit (bit #2) is ON, it means that the grouping separator should be inserted after the third digit of the formatted number.

• ns_PosGroupSep =A string used to separate groups of digits to the left of the decimal character.

• ns_PosRadix =A string used as a decimal character.

• ns_PosFractionalGroups A GroupingDesc value defining how digits are grouped to the right of the decimal character.
• ns_PosFractionalGroupSep = A string used to separate groups of digits to the right of the decimal character.

• ns_PosFormat =This field is used to do post-processing on a formatted number. This is typically used to add currency notation around a numeric value. The string in this field is used as a format string in a sprintf() function call, and the formatted numeric value is supplied as a parameter to the same sprintf() call. For example, if the ns_PosFormat field is defined as "$%s", and the formatted numeric value is "0.02", then the result of the post-processing will be "$0.02". When this field is NULL, no post-processing occurs.

• ns_PosMinFractionalDigits =Specifies the minimum number of digits to display to the right of the decimal character. If there are not enough digits, then the string will be padded on the right with 0s.

• ns_PosMaxFractionalDigits= Specifies the maximum number of digits to display to the right of the decimal character. Any excess digits are just removed.

• ns_NegGroups, ns_NegGroupSep, ns_NegRadix, ns_NegFractionalGroups, ns_NegFractionalGroupSep, ns_NegFormat, ns_NegMinFractionalDigits, ns_NegMaxFractionalDigits = These fields have the same function as the eight fields described above, except that they are used to process negative amounts, while the previous fields are used for positive amounts.

• ns_Zero =If the number being processed is 0, then this string pointer us used as-is'andiscopieddirectlyintotheresultbuffer.'If this field is NULL, the number is formatted as if it were a positive number.

• ns_Flags =This is reserved for future use and must always be 0.

Arguments

locItem

A Locale Item, as obtained from intlOpenLocale().

spec

The formatting template describing the number layout. This structure is typically taken from a Locale structure (loc_Numbers, loc_Currency, loc_SmallCurrency), but it can also be built up by the title for custom formatting.

whole

The whole component of the number to format. (The part of the number to the left of the radix character.)

frac

The decimal component of the number to format. (The part of the number to the right of the radix character.). This is specified in number of billionth. For example, to represent .5, you would use 500000000. To represent .0004, you would use 400000.

negative

TRUE if the number is negative, and FALSE

if the number is positive.

doFrac

TRUE if a complete number with a decimal mark and decimal digits is desired. FALSE if only the whole part of the number should be output.

result

Where the result of the formatting is put.

resultSize

The number of bytes available in the result buffer. This limits the number of bytes which are put into the buffer.

Return Value

greater than or equal to 0 Number of characters copied.

INTL_ERR_BADNUMERICSPEC - The pointer to the NumericSpec structure was bad.

INTL_ERR_NORESULTBUFFER- "result" was NULL.

INTL_ERR_BUFFERTOOSMALL - There was not enough room in the result buffer.

INTL_ERR_BADITEM loc- Item was not an existing Locale Item.

Implementation

Associated Files

See Also