strfmon - convert monetary value to a string
SYNOPSIS
#include <monetary.h>
ssize_t strfmon(char *s, size_t max, const char *format,
...);
DESCRIPTION
The strfmon() function formats the specified amounts
according to the format specification format and places
the result in the character array s of size max.
Ordinary characters in format are copied to s without con
version. Conversion specifiers are introduced by a `%'
character. Immediately following it there can be zero or
more of the following flags:
=f The single-byte character f is used as the numeric
fill character (to be used with a left precision,
see below). When not specified, the space charac
ter is used.
^ Do not use any grouping characters that might be
defined for the current locale. By default, group
ing is enabled.
( or + The ( flag indicates that negative amounts should
be enclosed between parentheses. The + flag indi
cates that signs should be handled in the default
way, that is, amounts are preceded by the locale's
sign indication, e.g., nothing for positive, "-"
for negative.
! Omit the currency symbol.
- Left justify all fields. The default is right jus
tification.
Next, there may be a field width: a decimal digit string
specifying a minimum field width in bytes. The default is
0. A result smaller than this width is padded with spaces
(on the left, unless the left-justify flag was given).
Next, there may be a left precision of the form "#" fol
lowed by a decimal digit string. If the number of digits
left of the radix character is smaller than this, the rep
resentation is padded on the left with the numeric fill
character. Grouping characters are not counted in this
field width.
Next, there may be a right precision of the form "." fol
lowed by a decimal digit string. The amount being
prior to formatting. The default is specified in the
frac_digits and int_frac_digits items of the current
locale. If the right precision is 0, no radix character
is printed. (The radix character here is determined by
LC_MONETARY, and may differ from that specified by
LC_NUMERIC.)
Finally, the conversion specification must be ended with a
conversion character. The three conversion characters are
% (In this case the entire specification must be
exactly "%%".) Put a `%' character in the result
string.
i One argument of type double is converted using the
locale's international currency format.
n One argument of type double is converted using the
locale's national currency format.
RETURN VALUE
The strfmon() function returns the number of characters
placed in the array s, not including the terminating NUL
character, provided the string, including the terminating
NUL, fits. Otherwise, it sets errno to E2BIG, returns -1,
and the contents of the array is undefined.
EXAMPLE
The call
strfmon(buf, sizeof(buf), "[%^=*#6n] [%=*#6i]",
1234.567, 1234.567);
outputs
[ fl **1234,57] [ NLG **1 234,57]
in the Dutch locale (with fl for "florijnen" and NLG for
Netherlands Guilders). The grouping character is very
ugly because it takes as much space as a digit, while it
should not take more than half that, and will no doubt
cause confusion. Surprisingly, the "fl" is preceded and
followed by a space, and "NLG" is preceded by one and fol
lowed by two spaces. This may be a bug in the locale
files. The Italian, Australian, Swiss and Portuguese
locales yield
[ L. **1235] [ ITL **1.235]
[ $**1234.57] [ AUD **1,234.57]
[Fr. **1234,57] [CHF **1.234,57]
[ **1234$57Esc] [ **1.234$57PTE ]
SEE ALSO
setlocale(3), sprintf(3), locale(7)
Man(1) output converted with
man2html