ifx_gl_format_number - Format a number value.

SYNOPSIS

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

DESCRIPTION

This function creates a string from the the value represented by the mi_number structure pointed to by number using the format specified by format. The resulting string is stored in the buffer pointed to by numstr and numstrbytes is the size of the output buffer.

If format is NULL, then the format is determined from the current GLS locale.

If format is not NULL, then it must point to a string which follows the rules described in the FORMAT section below.

FORMAT

The format string consists of one conversion specification and ordinary characters. The conversion specification consists of a % character and a terminating conversion character that determines the conversion specification's behavior, with optional modifiers in between. All ordinary characters (including the terminating null character) are copied unchanged into the array. The conversion specification is replaced with a string that represents the value in the number argument.

Only one conversion specification is allowed in the format string.

%b
is replaced by the binary representation of number.
%d, %i
is replaced by the decimal representation of number.
%e
is replaced by the style [-]d.ddde[+|-]dd of number.
%E
is replaced by the style [-]d.dddE[+|-]dd of number.
%f
is replaced by the style [-]ddd.ddd of number. The default precision is 6.
%g
is replaced by the style of %f or %e. %e will be 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 in %g except the replacement of %E for %e.
%o
is replaced by the octal representation of number.
%q
is replaced by the base-4 representation of number.
%u
is replaced by the unsigned decimal representation of number.
%x
is replaced by the hexadecimal representation of number, using the letters abcdef.
%X
same as in %x, but use ABCDEF instead of abcdef.

If a conversion specification does not correspond to any of the above, the behavior is undefined.

Modified Conversion Specifiers

Some conversion specifiers can be modified by putting modifier characters between the % and the type specifier to indicate that an alternative format or specification should be used. If the alternative format or specification does not exist for the current locale, the behavior will be as if unmodified conversion specifications were used.
'
Separate 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.
+
The result of a signed conversion will always begin with a positive or negative sign defined in the locale.
-
The result of the conversion will be left-justified within the field.
space
If the beginning of a signed conversion is not a sign, space will be prefixed. Ignore if the + modifier exists.
#
Convert the value to an alternate form. For o conversion, the first digit of the result is forced to be zero. For x (or X) conversion, a non-zero result will have a leading "0x" (or "0X"). For e,E,f,g,G conversions, the result will always have a radix character.
0
Leading zeros are used to pad to the field width. Ignore if - modifier exists.

Field Width and Precision

An optional field width and precision specification can follow the initial % of the conversion specification according to the following.
[-|0][w[.p]]

If the value begins with a minus (-) then the field will be left justified and padded with spaces on the right. If the value begins with a zero (0) then the field will be right justified and padded with zeros on the left. Otherwise, the value will be right justified and padded with spaces on the left.

w is a decimal value which specifies a minimum field width for the conversion.

The field width specifier w may be followed by a precision directive defined to be a period followed by a decimal value. For d,o,u,x and X conversions, p gives the minimum number of digits to appear. For e,E and f conversions, p gives the number of digits to appear after the radix character. For g and G conversions, p specifies the maximum number of significant digits. For s and ls conversions, p specifies the maximum number of characters to be printed.

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_INVALIDFMT]
The format control string 'format' is invalid.
[IFX_GL_PARAMERR]
The type specifier is invalid.
[IFX_GL_E2BIG]
Operation would overflow buffer.

SEE ALSO

ifx_gl_convert_number(),

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.