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:
- If the DBMONEY environment variable is set, the function formats monstr according to DBMONEY.
- 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| Argument | See |
|---|---|
| modifiers | Modified formatting directives |
| flag | Field width and precision |
| width | Field width and precision |
| left_precision | Field width and precision |
| right_precision | Field width and precision |
| type_specifier | Valid type specifiers |
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.