Description | strfmon() writes characters of type ’character’ to the field pointed to by s in accordance
with the format specification. No more than maxsize bytes are written to the field. format is a string containing two types of object: simple characters that are copied into the output stream, and conversion specifications. Conversion specifications cause arguments (none, one or more) to be converted and formatted. If there are not enough arguments for the specified format, the result is undefined. If there are more arguments than allowed for by the format, the excess arguments are ignored. A conversion specification consists of the following elements: a % character optional flags an optional field size an optional left-adjusted precision an optional right-adjusted precision a conversion character that determines how the arguments are converted (mandatory)
FlagsTo control the conversion, you can specify one or more of the flags listed below: =f | An equals sign followed by a single f. This character is used as a filler for numeric values. The fill character must be representable in a single byte so that it does not clash with specifications on the field size and the alignment. The default fill character is the blank.
This flag does not affect filling due to a field-size specification: the blank is always used as a filler in this case.
The flag is ignored if no left-adjusted precision is specified. | ^ | Monetary values are formatted without grouping characters. By default, monetary values are formatted with the grouping characters that apply for the current locale. | + or ( | Controls how positive and negative monetary values are displayed. Only one of the two characters + and ( can be specified. If + is specified, the values defined in the current locale for + and - are used (in the USA, for example, the empty string for positive values and the - sign for negative values). If ( is specified, negative values are enclosed in brackets. The default value is +. | ! | Suppresses the currency symbol in the output. | - | Controls the alignment. If this flag is set, values in the fields are left-aligned instead of right-aligned (i.e. padded to the right). |
Field size w | A sequence of decimal digits defining the minimum field size in bytes. The result of the conversion is right-aligned in the field and, if necessary, padded (the result is left-aligned if the - flag is set).
The default field size is 0. | Left-adjusted precision #n | A sequence of decimal digits prefixed by the # character. This value specifies the maximum number of digits expected to the left of the radix character (e.g. the period in $ **15.20).
This option can be used to align the results of several strfmon calls in columns. It can also be used to fill up free positions with a special character, e.g. $ ***123.45.
This option causes a monetary value to be formatted as if it had n digits. If more than n digit positions are required, this conversion specification is ignored. Free digit positions are filled with the numeric filler character (see flag =f). If a grouping is defined in the current locale and is not suppressed (flag ^), the grouping characters are inserted before free positions are padded with filler characters. Filler characters are not grouped, even if they are numeric. To guarantee the alignment, all characters like currency symbols or minus signs before or after the number are positioned before or after the number in the formatted output using blanks so that their positive and negative formats have the same lengths. | Right-adjusted precision .p | A sequence of decimal digits prefixed by the . character. This word specifies how many digits are to appear to the right of the radix character (e.g. the period in $ **15.20). If p is 0, the radix character is also omitted. If right-adjusted precision is not specified, the right-adjusted precision defined in the current locale is used. The sum to be formatted is rounded to the specified number of digits before the formatting. |
Conversion characters i | The argument of type double is formatted according to the international currency format defined in the locale (e.g. in the USA: USD 1,234.56). | n | The argument of type double is formatted according to the national currency format defined in the locale (e.g. in the USA: $1,234.56). | % | Converted to a %., no argument is converted. The complete conversion specification must be %%. |
Locale information The behavior of the function is influenced by the LC_MONETARY category of the locale of the program. This applies particularly to the monetary radix character (which can be different from the numeric radix character which applies for the LC_NUMERIC category), the grouping character, the currency symbols and the currency formats. The international currency symbol should comply with the ISO 4217:1987 standard. |
Example | The following examples refer to a locale in the USA and the values 123.45, -123.45 and 3456.781: Conversion specification | Result | Comment | %n | $123.45
-$123.45
$3,456.78
| Default formatting | %11n | $123.45
-$123.45
$3,456.78
| Right alignment within an 11-character field | %#5n | $ 123.45
-$ 123.45 $
3,456.78
| Values through 99.999 are aligned in a column | %=*#5n | $***123.45
-$***123.45
$*3,456.78
| Specification of a filler character for free positions | %=0#5n | $000123.45
-$000123.45 $03,456.78
| Filler characters are not grouped, even if the filler character is a digit | %^#5n | $ 123.45
-$ 123.45
$ 3456.78
| Suppress grouping character | %^#5.0n | $ 123
-$ 123
$ 3456
| Round to integer | %^#5.4n | $ 123.4500
-$ 123.4500 $ 3456.7800
| Increase right-adjusted precision | %(#5n | $ 123.45
($ 123.45)
$ 3456.78
| Alternative representation for positive/negative values | %!(#5n | 123.45
( 123.45)
3456.78
| Suppress currency symbol |
|
