Converts a number of monetary values into a string. The
conversion is controlled by a format string.
Format
#include <monetary.h>
ssize_t strfmon (char *s, size_t maxsize, const char
*format, . . . );
1 – Arguments
s
A pointer to the resultant string.
maxsize
The maximum number of bytes to be stored in the resultant string.
format
A pointer to a string that controls the format of the output
string.
. . .
The monetary values of type double that are to be formatted for
the output string. There should be as many values as there are
conversion specifications in the format string pointed to by
format. The function fails if there are insufficient values.
Excess arguments are ignored.
2 – Description
The strfmon function creates a string pointed to by s, using the
monetary values supplied. A maximum of maxsize bytes is copied to
s.
The format string pointed to by format consists of ordinary
characters and conversion specifications. All ordinary characters
are copied unchanged to the output string. A conversion
specification defines how one of the monetary values supplied
is formatted in the output string.
A conversion specification consists of a percent character
(%), followed by a number of optional characters (see Optional
Characters in strfmon Conversion Specifications), and concluding
with a conversion specifier (see strfmon Conversion Specifiers).
If any of the optional characters listed in Optional Characters
in strfmon Conversion Specifications is included in a conversion
specification, they must appear in the order shown.
Table REF-5 Optional Characters in strfmon Conversion
Specifications
Character Meaning
left precision is specified. The default numeric
fill character is the space character. The fill
character must be representable as a single byte
in order to work with precision and width count.
This conversion specifier is ignored unless a
left precision is specified, and it does not
affect width filling, which always uses the space
character.
^ Do not use separator characters to format the
number. By default, the digits are grouped
according to the mon_grouping field in the LC_
MONETARY category of the current locale.
+ Add the string specified by the positive_sign
or negative_sign fields in the current locale.
If p_sign_posn or n_sign_posn is set to 0, then
parentheses are used by default to indicate
negative values. Otherwise, sign strings are used
to indicate the sign of the value. You cannot use a
+ and a ( in the same conversion specification.
( Enclose negative values within parentheses. The
default is taken from the p_sign_posn and n_sign_
posn fields in the current locale. If p_sign_
posn or n_sign_posn is set to 0, then parentheses
are used by default to indicate negative values.
Otherwise, sign strings are used to indicate the
sign of the value. You cannot use a + and ( in the
same conversion specification.
! Suppress the currency symbol. By default, the
currency symbol is included.
- Left-justify the value within the field. By
default, values are right-justified.
field width A decimal integer that specifies the minimum
field width in which to align the result of the
conversion. The default field width is the smallest
field that can contain the result.
#left_ A # followed by a decimal integer specifies
precision the number of digits to the left of the radix
character. Extra positions are filled by the
fill character. By default the precision is the
smallest required for the argument. If grouping
is not suppressed with the ^ conversion specifier,
and if grouping is defined for the current locale,
grouping separators are inserted before any fill
characters are added. Grouping separators are
not applied to fill characters even if the fill
character is defined as a digit.
.right_ A period (.) followed by a decimal integer
precision specifies the number of digits to the right of
the radix character. Extra positions are filled
with zeros. The amount is rounded to this number
of decimal places. If the right precision is zero,
the radix character is not included in the output.
By default the right precision is defined by the
frac_digits or int_frac_digits field of the current
locale.
Table REF-6 strfmon Conversion Specifiers
SpecifierMeaning
i Use the international currency symbol defined by the
int_currency_symbol field in the current locale, unless
the currency symbol has been suppressed.
n Use the local currency symbol defined by the currency_
symbol field in the current locale, unless the currency
symbol has been suppressed.
% Output a % character. The conversion specification must
be %%; none of the optional characters is valid with
this specifier.
3 – Return Values
x The number of bytes written to the string
pointed to by s, not including the null-
terminating character.
-1 Indicates an error. The function sets errno to
one of the following values:
o EINVAL - A conversion specification is
syntactically incorrect.
o E2BIG - Processing the complete format
string would produce more than maxsize
bytes.
4 – Example
#include <stdlib.h>
#include <stdio.h>
#include <locale.h>
#include <monetary.h>
#include <errno.h>
#define MAX_BUF_SIZE 124
main()
{
size_t ret;
char buffer[MAX_BUF_SIZE];
double amount = 102593421;
/* Display a monetary amount using the en_US.ISO8859-1 */
/* locale and a range of different display formats. */
if (setlocale(LC_ALL, "en_US.ISO8859-1") == (char *) NULL) {
perror("setlocale");
exit(EXIT_FAILURE);
}
ret = strfmon(buffer, MAX_BUF_
SIZE, "International: %i\n", amount);
printf(buffer);
ret = strfmon(buffer, MAX_BUF_
SIZE, "National: %n\n", amount);
printf(buffer);
ret = strfmon(buffer, MAX_BUF_
SIZE, "National: %=*#10n\n", amount);
printf(buffer);
ret = strfmon(buffer, MAX_BUF_
SIZE, "National: %(n\n", -1 * amount);
printf(buffer);
ret = strfmon(buffer, MAX_BUF_
SIZE, "National: %^!n\n", amount);
printf(buffer);
}
Running the example program produces the following result:
International: USD 102,593,421.00
National: $102,593,421.00
National: $**102,593,421.00
National: ($102,593,421.00)
National: 102593421.00