Formats monetary strings.
Standard C Library (libc. a)
The strfmon subroutine converts numeric values to monetary strings according to the specifications in the Format parameter. This parameter also contains numeric values to be converted. Characters are placed into the S array, as controlled by the Format parameter. The LC_MONETARY category governs the format of the conversion.
The strfmon subroutine can be called multiple times by including additional format structures, as specified by the Format parameter.
The Format parameter specifies a character string that can contain plain characters and conversion specifications. Plain characters are copied to the output stream. Conversion specifications result in the fetching of zero or more arguments, which are converted and formatted.
If there are insufficient arguments for the Format parameter, the results are undefined. If arguments remain after the Format parameter is exhausted, the excess arguments are ignored.
A conversion specification consists of the following items in the following order: a % (percent sign), optional flags, optional field width, optional left precision, optional right precision, and a required conversion character that determines the conversion to be performed.
The strfmon_l() function is equivalent to the strfmon() function, except that the locale data used is from the locale represented by Locale.
| Item | Description |
|---|---|
| S | Contains the output of the strfmon subroutine. |
| MaxSize | Specifies the maximum number of bytes (including the null terminating byte) that may be placed in the S parameter. |
| Format | Contains characters and conversion specifications. |
One or more of the following flags can be specified to control the conversion:
| Item | Description |
|---|---|
| =f | An = (equal sign) followed by a single character that specifies the numeric fill character. The default numeric fill character is the space character. This flag does not affect field-width filling, which always uses the space character. This flag is ignored unless a left precision is specified. |
| ^ | Does not use grouping characters when formatting the currency amount. The default is to insert grouping characters if defined for the current locale. |
| + or ( | Determines the representation of positive and negative currency amounts. Only one of these flags may be specified. The locale's equivalent of + (plus sign) and - (negative sign) are used if + is specified. The locale's equivalent of enclosing negative amounts within parentheses is used if ( (left parenthesis) is specified. If neither flag is included, a default specified by the current locale is used. |
| - | Left-justifies all fields (pads to the right). The default is right-justification. |
| ! | Suppresses the currency symbol from the output conversion. |
Field Width
| Item | Description |
|---|---|
| w | The decimal-digit string w specifies the minimum field width in which the result of the conversion is right-justified. If -w is specified, the result is left-justified. The default is a value of 0. |
Left Precision
| Item | Description |
|---|---|
| #n | A # (pound sign) followed by a decimal-digit string, n,
specifies the maximum number of digits to be formatted to the left
of the radix character. This option can be specified to keep formatted
output from multiple calls to the strfmon subroutine aligned
in the same columns. It can also be used to fill unused positions
with a special character (for example, $***123.45). This
option causes an amount to be formatted as if it has the number of
digits specified by the n variable. If more than n digit
positions are required, this option is ignored. Digit positions in
excess of those required are filled with the numeric fill character
set with the =f flag. If defined for the current locale and not suppressed with the ^ flag, the subroutine inserts grouping characters before fill characters (if any). Grouping characters are not applied to fill characters, even if the fill character is a digit. In the example: grouping characters do not appear after the first or fourth 0 from the left. To ensure alignment, any characters appearing before or after the number in the formatted output, such as currency or sign symbols, are padded as necessary with space characters to make their positive and negative formats equal in length. |
Right Precision
| Item | Description |
|---|---|
| .p | A . (period) followed by a decimal digit string, p, specifies the number of digits after the radix character. If the value of the p variable is 0, no radix character is used. If a right precision is not specified, a default specified by the current locale is use. The amount being formatted is rounded to the specified number of digits prior to formatting. |
Conversion Characters
| Item | Description |
|---|---|
| i | The double argument is formatted according to the current locale's international currency format; for example, in the U.S.: 1,234.56. |
| n | The double argument is formatted according to the current locale's national currency format; for example, in the U.S.: $1,234.56. |
| % | No argument is converted; the conversion specification %% is replaced by a single %. |
If successful, and if the number of resulting bytes (including the terminating null character) is not more than the number of bytes specified by the MaxSize parameter, the strfmon, and strfmon_l subroutines return the number of bytes placed into the array pointed to by the S parameter (not including the terminating null byte). Otherwise, a value of -1 is returned and the contents of the S array are indeterminate.
The strfmon, and strfmon_l subroutines may fail if the following is true:
| Item | Description |
|---|---|
| E2BIG | Conversion stopped due to lack of space in the buffer. |