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.