strfmon.3c (2010 09)

s
strfmon(3C) strfmon(3C)
NAME
strfmon - convert monetary value to string
SYNOPSIS
#include <monetary.h>
ssize_t strfmon(char *__restrict s, size_t maxsize,
const char *__restrict format, ...);
Remarks
The ANSI C ", ..." construct denotes a variable length argument list whose optional [or required]
members are given in the associated comment (
/* */).
DESCRIPTION
The
strfmon() function places characters into the array pointed to by s as controlled by the string
pointed to by format . No more than maxsize bytes are placed into the array.
The format is a character string that contains two types of objects: plain characters, which are simply
copied to the output, and conversion specifications, each of which results in the fetching of zero or more
arguments that are converted and formatted. The arguments are of type
double, see the Conversion
Characters section for details. The results are undefined if there are insufficient arguments for the for-
mat. If the format is exhausted while arguments remain, the excess arguments are ignored.
A conversion specification is the string
%[flag]...[field_width ][#left_precision][
.right_precision] conversion_character
Each element of the sequence is specified as follows:
Flags
One or more of the following optional flags can be specified to control the conversion:
=f An = (equal sign) followed by a single character f which is used as the numeric fill character.
The fill character must be representable in a single byte in order 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 (see below) 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.
+ or ( Specify the style for representing positive and negative currency amounts. Only one of
+ or (
(plus sign or left parenthesis) may be specified. If + is specified, the locale’s equivalent of +
and − are used (for example, in the en_US.roman8 locale: an empty string if positive and − if
negative). If
( is specified, negative amounts are enclosed within parentheses. If neither flag
is specified, the + style is used.
! Suppress the currency symbol from the output conversion.
- A minus sign specifying the alignment. If this flag is present all fields are left-justified (pad-
ded to the right) rather than right-justified.
Field Width
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.
Left Precision
#n A # followed by a decimal digit string n specifying a maximum number of digits expected to be
formatted to the left of the radix character. This option can be used to keep the formatted out-
put from multiple calls to the strfmon() aligned in the same columns. It can also be used
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 numeric fill character (see the =f flag above).
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.
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1