ifx_gl_format_money - Format a money value.
SYNOPSIS
#include <ifxgls.h>
int ifx_gl_format_money(char *monstr,
int monstrbytes,
mi_money *money,
char *format)
DESCRIPTION
This function creates a string from the the mi_money structure
pointed to by money using the format specified by
format. The resulting string is stored in the buffer pointed
to by monstr and monstrbytes is the size of the output
buffer.
If format is NULL, then the format is
determined from the DBMONEY environment variable
and the LC_MONEY settings in the current GLS locale.
If format is not NULL, then it must point to a character
string which adheres to the description in the FORMAT section below.
FORMAT
The format is a character string that contains two types of
objects: plain characters, which are simplly copied to the output
stream, and one conversion specification which gets expanded to
a string which represents the value in money.
The conversion specification consists of the following sequence:
- a % character
- optional flags
- optional field width
- optional left precision
- optional right precision
- a required conversion character that determines the
conversion to be performed.
Flags
One or more of the following flags can be specified to control the
conversion:
- =f
-
An = 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 of representing positive and
negative currency amounts. Only one of + or ( may be specified.
If + is specified, the locale's equivalent of + and - are used
(for example, in the U.S.A.: the empty string if positive and -
if negative). If neither flag is specified, the locale's equivalent
of - is used for negative values, but no sign is printed if the
value is positive.
- !
-
Suppress the currency symbol from the output conversion.
- -
-
Specify the alignment. If this flag is present all
fields are left-justified (padded to the right) rather than
right-justified.
Field Width
A decimal digit character string w specifying
a minimum field width in characters in which the result of the
conversion is right-justified (or left-justified if the flag
- is specified). The default is zero.
Left Precision
A # followed by a decimal digit character string n
specifying a maximum number of digits expected to be formated
to the left of the radix character. This option can be used to
keep the formatted output from multiple calls to this
function 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 the 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.
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 charaacters to make their
positive and negative formats and equal length.
Right Precision
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 a right precision is not
included, a defalt specified by the current locale is used. The
amount being formatted is rounded to the specified number of
digits prior to formatting.
Conversion Characters
The conversion characters and their meanings are:
- i
-
The money argument is formated according to the locale's
international currency format. For example, in the U.S.A.:
USD 1,234.56
- n
-
The moneyargument is formated according to the locale's
national currency format. For example, in the U.S.A.:
$1,234.56
- %
-
Convert to a %; no argument is converted. The entire
conversion specification must be %%.
Locale Information
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 the LC_NUMERIC category), the grouping
separator, the currency symbols and formats. The international
currency symbol should be conformant with the ISO 4217:1987
standard.
RETURN VALUES
On success, this function returns 0.
On failure, this function returns -1.
ERRORS
If an error has occurred, this function returns -1 and
ifx_gl_lc_errno() returns,
- [IFX_GL_ENOSYS]
- Format specification is not supported.
- [IFX_GL_E2BIG]
- Operation would overflow buffer.
SEE ALSO
ifx_gl_convert_money(),
ACKNOWLEDGEMENT
Portions of this description were derived from the X/Open CAE
Specification: "System Interfaces and Headers, Issue 4"; X/Open
Document Number: C202; ISBN: 1-872630-47-2; Published by X/Open Company
Ltd., U.K.