strfmon(S)

strfmon -- convert monetary value to string

Synopsis

   #include <monetary.h>
   
   ssize_t strfmon(char s, size_t max, const char format, . . .);

Description

strfmon is part of the X/Open Portability Guide Issue 4 optional Enhanced Internationalization feature group.

strfmon places characters into the array pointed to by s as controlled by the string pointed to by format. No more than max bytes are placed into the array.

format contains plain characters that are copied to the output stream, and conversion specifications, that result in the fetching of zero or more arguments which are converted and formatted. The results are undefined if there are insufficient arguments for the format. If the format is exhausted while arguments remain, the excess arguments are ignored.

A conversion specification consists of the following:

% character
optional flags
optional field width
optional precision
optional left precision
a conversion character that determines the conversion to be performed.

Options

The following flags can be specified to control the conversion:

=f

An = followed by a single byte character f which is used as the numeric fill character. You must represent the fill character in a single byte to work with precision and width counts. 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.

^

Do not format the currency amount with grouping characters. The default is to insert the grouping characters if defined for the current locale.

+

Specify the style of representing positive and negative amounts. You can only specify one of these. If + is specified, the locale's equivalent of + and - are used. If ( is specified, negative amounts are enclosed within parentheses. + is the default.

!

Suppress the currency symbol from the output conversion.

-

Specify the alignment. If this flag is present all fields are left-justified rather than right-justified.

w

A decimal digit string w specifying a minimum field width in bytes in which the result of the conversion is right-justified, or left-justified if the - flag is specified. The default is zero.

#n

a # followed by a decimal digit string n specifying the maximum number of digits expect to be formatted to the left of the radix character. Use this option to keep the formatted output from multiple calls to the strfmon aligned in the same column. You can also use it to fill unused positions with a special character as in $***123.45. This option causes an amount to be formatted as if it has the number of digits specified by n. If more than n digit positions are required, this conversion specification is ignored. Digit positions in excess of those actually required are filled with the numeric fill character.

If grouping has not been suppressed with the ^ flag, and it is defined for the current locale, grouping separators are inserted before the fill characters (if any) are added. Grouping separators are not applied to fill characters even if the fill character is a digit.

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 an equal length.

.p

A period followed by a decimal digit string p specifying the number of digits after the radix character. If the value of the right precision p is zero, no radix character appears. If the right precision is not included, a default specified by the current locale is used. The amount being formatted is rounded to the specified number of digits before formatting.

The conversion characters and their meanings are:

i: The double argument is formatted according to the locale's international currency format, for example, USD 1,234.56 for the USA.
n: The double argument is formatted according to the locale's national currency format, for example, USD $1,234.56 for the USA.
%: Convert to a %. No argument is converted. The entire conversion specification must be %%.

Usage

The LC_MONETARY category of the program's locale affects the behavior of this function including the monetary radix character which may be different from the numeric radix character affected by this category. It also affects the grouping separator, the currency symbols, and formats. The international currency symbols used conform to ISO 4217:1987 standard.

Return values

strfmon returns the number of bytes placed in s (not including the terminating null byte), providing the total number of resulting bytes (including the terminating null byte) is not more than max. Otherwise, -1 is returned, errno is set to indicate the error, and the contents of the array are indeterminate.

Errors

In the following conditions, strfmon fails and sets errno to:

ENOSYS: The function is not supported
E2BIG: Conversion stopped because of lack of space in the buffer.

References

monetary(M)