# IntlFormatNumber

Format a number in a localized manner.

### Synopsis

`int32 intlFormatNumber(Item locItem,const NumericSpec *spec,uint32 whole, uint32 frac,bool negative, bool doFrac,unichar *result, uint32 resultSize);`

### Description

This function formats a number according to the rules contained in the NumericSpec structure. The NumericSpec structure is normally taken from a Locale structure. The Locale structure contains three initialized NumericSpec structures (loc_Numbers, loc_Currency, and loc_SmallCurrency) which let you format numbers in an appropriate manner for the current system.

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

If positive, then the number of characters in the result buffer. If negative, then an error code. The string copied into the result buffer is guaranteed to be NULL-terminated.

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

Folio call implemented in international folio V24.

### Associated Files

intl.h

### See Also

``intlOpenLocale`(), intlFormatDate()`