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:

  1. a % character
  2. optional flags
  3. optional field width
  4. optional left precision
  5. optional right precision
  6. 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.