strfmon(3C)
strfmon --
convert monetary value to string
Synopsis
#include <monetary.h>
ssize_t strfmon(char s, size_t max, const char format, . . .);
Description
strfmon is part of the X/Open Portability Guide Issue 4 optional
Enhanced Internationalization feature group.
strfmon places characters into the array pointed to by s
as controlled by the string pointed to by format.
No more than max bytes
are placed into the array.
format contains
plain characters that are copied to the output stream,
and conversion specifications, that result in the
fetching of zero or more arguments
which are converted and formatted.
The results are undefined if there are insufficient arguments
for the format.
If the format is exhausted while arguments remain, the excess arguments are ignored.
A conversion specification consists of the following:
-
% character
-
optional flags
-
optional field width
-
optional precision
-
optional left precision
-
a conversion character that determines the conversion to be performed.
Options
The following flags can be specified to control the conversion:
=f-
An = followed by a single byte character f which is used as the
numeric fill character.
You must represent the fill character in a single
byte to work with precision and width counts.
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.
^-
Do not format the currency amount with grouping characters.
The default is
to insert the grouping characters if defined for the current locale.
+-
Specify the style of representing positive and negative amounts. You
can only specify one of these.
If + is specified, the locale's equivalent of
+ and - are used. If ( is specified, negative
amounts are enclosed within parentheses. + is the default.
!-
Suppress the currency symbol from the output conversion.
--
Specify the alignment. If this flag is present all fields are left-justified
rather than right-justified.
w-
A decimal digit string w specifying a minimum field width in bytes
in which the result of the conversion is right-justified, or left-justified
if the - flag is specified. The default is zero.
#n-
a # followed by a decimal digit string n specifying the maximum number
of digits expect to be formatted to the left of the radix character.
Use this option to keep the formatted output from multiple
calls to the strfmon aligned
in the same column.
You can also use it to fill unused positions with a special character
as in $***123.45. This option causes an amount to be formatted as if it
has the number of digits specified by n. If more than n
digit positions
are required, this conversion specification is ignored. Digit positions in excess of those
actually required are filled with the numeric fill character.
If grouping has not been suppressed with the ^ flag,
and it is defined for the
current locale, grouping separators are inserted before the fill characters (if any)
are added. Grouping separators are not applied to fill characters even if the fill character
is a digit.
To ensure alignment,
any characters appearing before or after the number in the formatted
output such as currency or sign symbols are padded as necessary
with space characters to make
their positive and negative formats an equal length.
.p-
A period followed by a decimal digit string p specifying the number of digits
after the radix character.
If the value of the right precision p is zero,
no radix character appears.
If the right precision is not included, a default
specified by the current locale is used.
The amount being formatted is rounded
to the specified number of digits before formatting.
The conversion characters and their meanings are:
i-
The double argument is formatted according to the
locale's international currency format, for example, USD 1,234.56
for the USA.
n-
The double argument is formatted according to the
locale's national currency format, for example, USD $1,234.56
for the USA.
%-
Convert to a %. No argument is converted. The entire conversion
specification must be %%.
Usage
The LC_MONETARY category of the program's locale affects the behavior
of this function including the monetary radix character which may be
different from the numeric radix character affected by this category.
It also affects the grouping separator, the currency symbols, and formats.
The international currency symbols used conform to
ISO 4217:1987 standard.
Return values
strfmon returns the number of bytes placed in s (not
including the terminating null byte), providing the total number of
resulting bytes (including the terminating null byte) is not more than
max.
Otherwise, -1 is returned, errno is set to indicate the error,
and the contents of the array are indeterminate.
Errors
In the following conditions,
strfmon fails and sets errno to:
ENOSYS-
The function is not supported
E2BIG-
Conversion stopped because of lack of space in the buffer.
References
monetary(5)
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004