strfmon(3C) SDK R4.11 strfmon(3C)
NAME
strfmon - convert monetary value to string
SYNOPSIS
#include <monetary.h>
ssizet *strfmon(char *s, sizet 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.
+ or ( 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 LCMONETARY 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 -1 and sets errno to ENOSYS.
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.
Licensed material--property of copyright holder(s)