strfmon(3) Library Functions Manual strfmon(3)
NAME
strfmon - Formats monetary strings
LIBRARY
Standard C Library (libc.so, libc.a)
SYNOPSIS
#include <monetary.h>
ssize_t strfmon(
char *s,
size_t maxsize,
const char *format
[,double value]...);
STANDARDS
Interfaces documented on this reference page conform to industry stan-
dards as follows:
strfmon(): XPG4
Refer to the standards(5) reference page for more information about in-
dustry standards and associated tags.
PARAMETERS
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 specifi-
cations. Specifies the double data to be converted according to the
format parameter.
DESCRIPTION
The strfmon() function converts numeric values to monetary strings ac-
cording 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 re-
sults are undefined. If parameters remain after the format parameter is
exhausted, the excess parameters are ignored.
Conversion Specifications
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 speci-
fies 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 spec-
ified 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 dec-
imal 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 speci-
fies 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 for-
matted 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. There-
fore, 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 charac-
ter, and that the radix character is the period (.):
strcpy(format,"%=0#10i"); monetary_value = 1.23; retval = strf-
mon(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 parame-
ter is converted; the conversion specification %% (double per-
cent sign) produces a single % in the output string. The double
parameter is formatted according to the current locale's inter-
national 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 mem-
bers 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.
tab(@); lfHB lfHB lfHB l l l . _ lconv Structure@Explanation@Default
Value _ mon_decimal_point@Radix character@. (period) _ nega-
tive_sign@Character to indicate@- (hyphen) @negative values@ _
int_frac_digits@Default right@2 @precision for %i@ _ frac_digits@De-
fault right@2 @precision for %n@ _ left_parenthesis@Characters used@(
(left parenthesis) @for ( flag@ _ right_parenthesis@Characters used@)
(right parenthesis) @for ) flag@ _
EXAMPLES
The following table lists conversion specifications and the output.
tab(@); lfHB lfHB lfHB lfHB lfHB lfHB lfHB lfHB l n n l . _
Conv.@Output in@Output in Spec.@a US Locale@C Locale@Explanation _
%n@
[email protected]@Default @$1,
[email protected]@national format _ %i@USD
[email protected]@Default @USD 1,
[email protected]@international format _
%(#6.3n@$ 9,876.543@ 9876.543@Explicit @($ 25,832.000)@(
25832.000)@left and right @@@precision with @@@parentheses @@@for nega-
tive values _ %=*#7n@$****4,379.25@***4379.25@Fill
@-$****4,379.25@-***4379.25@character _
%=0#7n@$0004,
[email protected]@Zero fill @$0004,
[email protected] _
%!.0n@3,225@3225@Suppress @3,225-@-3225@currency symbol @@@and round to
@@@integer _
RETURN VALUES
If successful, and if the number of resulting bytes (including the ter-
minating 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 termi-
nating null byte is not included in the return count. Otherwise, the
function returns -1, and the contents of the s array are indeterminate.
ERRORS
If one of the following conditions occur, the strfmon() function sets
errno to the corresponding value: The function is not supported. (This
value may be returned on platforms, other than DIGITAL UNIX, that con-
form to XPG4 but do not support its worldwide portability interfaces.)
Conversion stopped due to lack of space in the buffer.
RELATED INFORMATION
Functions: localeconv(3), nl_langinfo(3), scanf(3), setlocale(3), strf-
time(3), wscanf(3)
Files: locale(4)
Others: i18n_intro(5), l10n_intro(5), standards(5)
Writing Software for the International Market delim off
strfmon(3)