The ifx_gl_format_money() function

The ifx_gl_format_money() function formats an internal money value to a money string.

Syntax

#include <ifxgls.h>
...
int ifx_gl_format_money(monstr, monstrbytes, money, format)
       char *monstr;
       int monstrbytes;
       mi_money *money;
       char *format;
monstr
A pointer to the first character of the money string that the function formats to its internal money representation.
monstrbytes
The size of the monstr buffer for the money string. This size is the maximum size that the formatted string can reach.
money
A pointer to the variable that holds the internal representation that ifx_gl_format_money() formats to create the monstr money string.
format
A pointer to the format string that determines how to format the monstr money string. For more information, see Format string
Valid in client application Valid in DataBlade® UDR
Yes Yes

Usage

The ifx_gl_format_money() function uses the format that the format string specifies to format the internal money representation in money as a money string. It stores the resulting money string in a buffer that monstr references.

The money argument is a pointer to a decimal (dec_t) value.

The money argument is a pointer to an mi_money value.

Format string

If format is NULL, the ifx_gl_format_money() function determines the format of the monstr money string that it creates from the environment, as follows:
  1. If the DBMONEY environment variable is set, the function formats monstr according to DBMONEY.
  2. Otherwise, the function uses the monetary formats in the LC_MONETARY category of the current GLS locale.
If format is not NULL, it must point to a string that follows the rules that this section describes. To format the monstr money string, the function ifx_gl_format_money() takes the following actions for each possible character that it finds in format.
Contents of format string Conversion action taken
A valid formatting directive The function performs the specified formatting of the data in the money argument. It replaces the formatting directive with a string representation of a money element for the monstr money string. Only one formatting directive is allowed in the format string.
Ordinary characters The function copies the ordinary character unchanged to the monstr money string. Ordinary characters include the null terminator and white space characters.
The formatting directive consists of the following sequence:
%[modifiers][flag][width[#left_precision][.right_precision]]type_specifier
Tip: In the preceding format sequence, the square brackets indicate that the enclosed portion of the format is optional.

Valid type specifiers

The type specifier is a letter or letters within a formatting directive that identify a format for the ifx_gl_format_money() function to use when it creates a monetary element of a monstr string. These monetary formats are formats that the LC_MONETARY locale-file category of the current locale might define. The ifx_gl_format_money() function supports the following formatting directives.
%i
Replaced by the international monetary format (which uses the int_curr_symbol subcategory of the LC_MONETARY category in the current locale) for the money argument. For example, in the default locale, the international monetary format for 1,234.56 is USD 1,234.56.
%n
Replaced by the national currency format (which uses the currency_symbol of the LC_MONETARY category in the current locale) for the money argument. For example, in the default locale, the national monetary format for 1,234.56 is $1,234.56.
%%
Replaced by the % symbol.

If a formatting directive does not correspond to any of the preceding directives, the behavior of the conversion is undefined.

Modified formatting directives

You can modify some formatting directives with format modifiers, which follow the percent symbol (%), to indicate use of an alternative format. The ifx_gl_format_money() function supports the following format modifiers.
=f
Use the single-byte character f as the numeric-fill character. The fill character must be representable in a single byte to work with precision and width counts. The default numeric-fill character is the blank (space) character. This flag does not affect field-width filling, which always uses the space character. Unless you specify left_precision, this flag is ignored.
^
Do not format the monetary amount with thousands separators. The default action is to insert the thousands separators if the LC_MONETARY category of the current locale defines them.
+ or (
Specify how to represent positive and negative monetary amounts. You can specify only + or (. If you specify the plus sign (+) , the function uses the equivalent of + and - that the LC_MONETARY category of the current locale defines. For example, in the default locale, a plus sign means an empty string for positive values and a minus sign (-) for negative values. If you do not specify either flag, the function uses the locale equivalent of the minus sign (-) for negative values and no sign for positive values.
!
Suppress the currency symbol from the formatted result.

Field width and precision

You can also specify an optional field width and precision in a formatting directive. This information precedes the type specifier in the formatting directive and has the following format:
[-][width[#left_precision][.right_precision]]
-
Indicates field justification. If the specification begins with a minus sign (-), the function left-aligns the field and pads it with spaces on the right. Otherwise, the function right-aligns the field and pads it with spaces on the left.
width
A decimal value that specifies a minimum field width, in characters, in which the resulting string is right-aligned. The default field width is 0.
left_precision
A string that specifies the maximum number of digits expected to the left of the decimal separator. This option causes an amount to be formatted as if it has the number of digits that n specifies. If more than n digit positions are required, the function ignores this precision specification.
right_precision
A decimal value that specifies the number of digits after the decimal separator. If the value of right_precision is 0, no decimal separator appears in the formatted string. If you do not include right_precision, the function uses a default, which the current locale specifies. The amount that is being formatted is rounded to the specified number of digits before formatting.
You can use this left_precision option to:
  • keep the formatted output from multiple calls to this function aligned in the same columns.
  • fill unused positions with a special character, such as the asterisk character in the $***123.45 string.

For left_precision, digit positions in excess of those positions required are filled with the numeric-fill character (see the description of the =f modifier in Modified formatting directives). If grouping has not been suppressed with the ^ modifier, and it is defined for the current locale, the function inserts thousands separators before the fill characters (if any) are added. Thousands separators are not applied to fill characters even if the fill character is a digit.

To ensure alignment, any characters that appear 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.

Locale information

The LC_MONETARY category of the current locale affects the behavior of this function because it provides the locale-specific information for the formatting of the money value. For more information, see The LC_MONETARY locale-file category.

Return values

0
The function was successful.
-1
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns -1 and sets the ifx_gl_lc_errno() error number to one of the following value.
IFX_GL_ENOSYS
The formatting directive is not supported.
IFX_GL_E2BIG
Formatting stopped due to insufficient space in the buffer.