The ifx_gl_format_number() function

The ifx_gl_format_number() function formats an internal decimal value to a number string.

Syntax

#include <ifxgls.h>
...
int ifx_gl_format_number(numstr, numstrbytes, number, format)
       char *numstr;
       int numstrbytes;
       mi_decimal *number;
       char *format;

numstr: A pointer to the first character in the number string that the function formats from its internal number representation.
numstrbytes: The size of the numstr buffer for the number string. This size is the maximum size that the formatted string can reach.
number: A pointer to the variable that holds the internal representation that ifx_gl_format_number() formats to create the numstr number string.
format: A pointer to the format string that determines how to format the numstr number string. For more information, see Format string


Valid in client application	Valid in DataBlade® UDR
Yes	Yes

Usage

The ifx_gl_format_number() function uses the format that the format string specifies to format the internal decimal representation in number as a number string. It stores the resulting number string in a buffer that numstr references.

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

The number argument is a pointer to an mi_decimal value.

Format string

If format is NULL, the function uses the numeric formats in the LC_NUMERIC category of the current GLS locale file to format the numstr number string that it creates.

If format is not NULL, it must point to a string that follows the rules that this section describes. To format the numstr number string, ifx_gl_format_number() 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 `number` argument. It replaces the formatting directive with a string representation of a numeric element for the `numstr` number string. Only one formatting directive is allowed in the `format` string.
Ordinary characters	The function copies the ordinary character unchanged to the `numstr` number string. Ordinary characters include the null terminator and white space characters.

The formatting directive consists of the following sequence:

%[modifiers][flags][width[.precision]]type_specifier


Argument	See
`modifiers`	Modified formatting directives
`flags`	Field width and precision
`width`	Field width and precision
`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_number() function to use when it creates a numeric element of a numstr string. These numeric formats are formats that the LC_NUMERIC locale-file category of the current locale might define. The ifx_gl_format_number() function supports the following formatting directives.

%b: Replaced by the binary representation of number.
%d: Replaced by the decimal representation of number.
%e: Replaced by the style [-]d.ddde[+|-]dd of number (where d is a digit).
%E: Replaced by the style [-]d.dddE[+|-]dd of number (where d is a digit).
%f: Replaced by the style [-]ddd.ddd of number (where d is a digit). The default precision is 6.
%g: Replaced by the style of %f or %e. The %e directive is used only if the converted exponent is less than -4 or greater than or equal to the precision. The precision specifies the number of significant digits. Trailing zeros are removed from the fractional portion of the result.
%G: Same as %g , except for the replacement of %E for %e.
%i: Same as %d.
%o: Replaced by the octal representation of number.
%q: Replaced by the base-4 representation of number.
%u: Replaced by the unsigned decimal representation of number.
%x: Replaced by the hexadecimal representation of number, using the hexadecimal characters a through f.
%X: Same as %x, but use uppercase hexadecimal characters (A through F) instead of lowercase letters (a through f).

If a formatting directive does not correspond to any of the preceding directives, the behavior of the formatting 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_number() function supports the following format modifiers.

': Separates the significant digits of the converted number with the grouping character defined in the locale, according to the grouping format also defined in the locale.
+: Begins the result of a signed conversion with a positive or negative sign, which the locale defines.
-: Left-justifies the result of the conversion within the field. space Prefixes the result with a space character (unless the + modifier exists) if the beginning of a signed conversion is not a sign.
#: Converts the value to an alternate form. For a %o directive, the first digit of the result is forced to be 0. For a %x (or %X) directive, a nonzero result will have a leading 0x (or 0X). For a %e, %E, %f, %g, or %G directive, the result always has a decimal-separator character.
0: Pads the field width with leading zeros (unless the - modifier exists).

If the alternative format does not exist for the current locale, the function uses the unmodified formatting directive.

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:

[- | 0][width[.precision]]

[- | 0]

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. If the value begins with 0, the function right-aligns the field and pads it with zeros on the left. 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 for the formatted string.

precision

The format has the format of a period (.) followed by a decimal value. The field width specifier can optionally be followed by a precision directive.

For the %d, %o, %u, %x, and %X directives, the value of precision specifies the minimum number of digits to appear. If a directive supplies fewer digits than specified by the precision, it is padded with leading zeros.

For the %e, %E, and %f directives, the value of precision specifies the number of digits to appear after the decimal separator.

For the %g, and %G directives, the value of precision specifies the maximum number of significant digits.

Locale information

The LC_NUMERIC category of the current locale affects the behavior of this function because it provides the locale-specific information for the formatting of the number value.

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 values.

IFX_GL_INVALIDFMT: The format string is invalid.
IFX_GL_PARAMERR: The type specifier in the formatting directive is invalid.
IFX_GL_E2BIG: Formatting stopped due to lack of space in the buffer.