strfmon - Formats monetary strings
#include <monetary.h>
ssize_t strfmon(
char *s,
size_t maxsize,
const char *format,
[,double value]... );
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards as follows:
strfmon(): XSH5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
Contains the output of the strfmon() function. Specifies
the maximum number of bytes (including the null terminating
byte) that may be placed in the s parameter. Contains
characters and conversion specifications. Specifies the
double data to be converted according to the format parameter.
The strfmon() function converts numeric values to monetary
strings according to the specifications in the format
parameter. The function converts the double-precision
floating-point value parameters under the control of the
format parameter and stores the result in the array specified
by the s parameter.
The format parameter is a character string that contains
two types of objects: Literal characters, which are copied
to the output stream. Conversion specifications, each of
which causes zero or more items to be fetched from the
value parameter list.
If there are insufficient parameters for the format parameter,
the results are undefined. If parameters remain
after the format parameter is exhausted, the excess parameters
are ignored.
Conversion Specifications [Toc] [Back]
A conversion specification consists of a % (percent sign)
character, optional flags, optional field width, optional
left precision, optional right precision, and a required
conversion character that determines the conversion to be
performed.
Each conversion specification in the format parameter has
the following syntax: A % (percent sign). Zero or more
optional flags can be specified to control the conversion.
The flag characters and their meanings are as follows: An
= (equal sign) followed by a single character that specifies
the numeric fill character. 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. The ^ (circumflex) flag suppresses the grouping
character when formatting the currency amount. The
default is to group the digits and separate them with the
grouping character if defined for the current locale. The
+ (plus) character specifies that the locale's equivalent
of + and - are used to indicate positive and negative values.
You cannot specify both the + (plus) character and
the ( (left-parenthesis) character. If you specify neither,
the style specified in the locale for + is used.
The ( (left-parenthesis) character specifies that the
locale's equivalent of enclosing negative amounts within
parentheses is used to indicate positive and negative values.
See also the description of the + character. The !
(exclamation mark) character suppresses the currency symbol
from the output conversion. The - (hyphen) character
specifies that the field is left justified within the minimum
field width rather than right justified. This flag is
ignored unless a minimum field width is specified. An
optional decimal digit string w that specifies a minimum
field width in which the result of the conversion is right
justified. If the - (hyphen) flag is specified, the result
is left justified. The default value for w is 0 (zero).
An optional left precision consisting of a # (number
sign), followed by a decimal digit string n. The decimal
digit string specifies the maximum number of digits to be
formatted to the left of the radix character. This option
causes an amount to be formatted as if it has the number
of digits specified by the n digit string. If more than n
digit positions are required, this option is ignored.
Digit positions in excess of those required are filled
with the numeric fill character set with the =f flag. The
#n option can be specified to keep the formatted output
from multiple calls to the strfmon() function aligned in
the same columns. The option can also be used in conjunction
with the =f flag to fill unused positions with a special
character (for example, $***123.45).
If grouping is defined for the current locale and
has not been suppressed with the ^ (circumflex)
flag, grouping separators are inserted before the
fill characters (if any) are added. Therefore,
grouping characters are not applied to instances of
the fill character, even when the fill character is
a digit. For the following example in which the
fill character is zero, assume that the locale
specifies that the thousands grouping character is
a comma (,), that the grouping character should be
delimit each group of three characters to the left
of the radix character, and that the radix character
is the period (.):
strcpy(format,"%=0#10i"); monetary_value = 1.23;
retval = strfmon(str,STR_SIZE,format, monetary_value);
printf("(%s,%f) => %s\en",format,monetary_value,
str);
This example prints 0000000000001.23 rather than
0,000,000,001.23. An optional right precision consisting
of a (period) followed by a decimal digit
string p that specifies the number of digits after
the radix character. If the value of the p digit
string is 0 (zero), no radix character is used. If
a right precision is not specified, a default specified
by the current locale is used. The amount
being formatted is rounded to the specified number
of digits prior to formatting. A character that
indicates the type of conversion to be applied: No
parameter is converted; the conversion specification
%% (double percent sign) produces a single %
in the output string. The double parameter is formatted
according to the current locale's international
currency format; for example, in a U.S.
locale: USD 1,234.56. The double parameter is formatted
according to the current locale's national
currency format; for example, in a U.S. locale:
$1,234.56.
The following table lists the default values used by the
strfmon() function when there are no values defined in the
locale for these members of the lconv structure. These are
the defaults for the POSIX (C) locale. For all other lconv
members, such as mon_thousands_sep, there are no defaults.
-----------------------------------------------------------------------
lconv Structure Explanation Default Value
-----------------------------------------------------------------------
mon_decimal_point Radix character . (period)
negative_sign Character to indicate neg- - (hyphen)
ative values
int_frac_digits Default right precision 2
for %i
frac_digits Default right precision 2
for %n
left_parenthesis Characters used for ( flag ( (left parenthesis)
right_parenthesis Characters used for ) flag ) (right parenthesis)
-----------------------------------------------------------------------
The following table lists conversion specifications and
the output.
-------------------------------------------------------------------------
Conv. Spec. Output in a US Output in C Explanation
Locale Locale
-------------------------------------------------------------------------
%n $100.35 100.35 Default national
format
$1,225.15- -1225.15
%i USD 100.35 100.35 Default international
format
USD 1,225.15- -1225.15
%(#6.3n $ 9,876.543 9876.543 Explicit left and
right precision
($ 25,832.000) ( 25832.000) with parentheses
for negative values
%=*#7n $****4,379.25 ***4379.25 Fill character
-$****4,379.25 -***4379.25
%=0#7n $0004,379.25 0004379.25 Zero fill
$0004,379.25- -0004379.25
%!.0n 3,225 3225 Suppress currency
symbol and round
3,225- -3225 to integer
-------------------------------------------------------------------------
If successful, and if the number of resulting bytes
(including the terminating null byte) is not more than the
number of bytes specified by the maxsize parameter, the
strfmon() function returns the number of bytes placed into
the array pointed to by the s parameter. The terminating
null byte is not included in the return count. Otherwise,
the function returns -1, and the contents of the s array
are indeterminate.
If one of the following conditions occur, the strfmon()
function sets errno to the corresponding value: Conversion
stopped due to lack of space in the buffer.
Functions: localeconv(3), nl_langinfo(3), scanf(3), setlocale(3), strftime(3), wscanf(3)
Files: locale(4)
Others: i18n_intro(5), l10n_intro(5), standards(5)
Writing Software for the International Market
strfmon(3)
[ Back ] |
