 |
Index for
Section 3 |
|
 |
Alphabetical
listing for S |
|
 |
Bottom of
page |
|
strfmon(3)
NAME
strfmon - Formats monetary strings
SYNOPSIS
#include <monetary.h>
ssize_t strfmon(
char *s,
size_t maxsize,
const char *format,
[,double value]... );
LIBRARY
Standard C Library (libc)
STANDARDS
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.
PARAMETERS
s Contains the output of the strfmon() function.
maxsize
Specifies the maximum number of bytes (including the null terminating
byte) that may be placed in the s parameter.
format
Contains characters and conversion specifications.
value
Specifies the double data to be converted according to the format
parameter.
DESCRIPTION
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
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:
=f 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.
i 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.
n 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
negative values
- (hyphen)
int_frac_digits 2
Default right precision
for %i
frac_digits 2
Default right precision
for %n
left_parenthesis
Characters used for ( flag
( (left parenthesis)
right_parenthesis
Characters used for ) flag
) (right parenthesis)
______________________________________________________________________
EXAMPLES
The following table lists conversion specifications and the output.
________________________________________________________________________
Conv. Spec. Explanation
Output in a US
Locale
Output in C
Locale
________________________________________________________________________
%n
$100.35
$1,225.15-
100.35
-1225.15
Default national
format
%i
USD 100.35
USD 1,225.15-
100.35
-1225.15
Default
international
format
%(#6.3n
$ 9,876.543
($ 25,832.000)
9876.543
( 25832.000)
Explicit left and
right precision
with parentheses
for negative
values
%=*#7n Fill character
$****4,379.25
-$****4,379.25
***4379.25
-***4379.25
%=0#7n Zero fill
$0004,379.25
$0004,379.25-
0004379.25
-0004379.25
%!.0n
3,225
3,225-
3225
-3225
Suppress currency
symbol and round
to integer
________________________________________________________________________
RETURN VALUES
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.
ERRORS
If one of the following conditions occur, the strfmon() function sets errno
to the corresponding value:
[E2BIG]
Conversion stopped due to lack of space in the buffer.
SEE ALSO
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
|
Index for
Section 3 |
|
|
Alphabetical
listing for S |
|
 |
Top of
page |
|