The ifx_gl_convert_number() function

The ifx_gl_convert_number() function converts a number string to its internal decimal representation.

Syntax

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

number: A pointer to the variable that holds the internal decimal representation that ifx_gl_convert_number() creates from the numstr number string.
numstr: A pointer to the first character of the number string that the function converts to its internal decimal representation.
format: A pointer to the format string that determines how to interpret the numstr number string. For more information, see Format string


Valid in client application	Valid in DataBlade® UDR
Yes	Yes

Usage

The ifx_gl_convert_number() function converts the number string that numstr references to its internal decimal representation, which the function stores in the number argument. The function uses the format that the format string specifies to scan the numstr number string.

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 formats in the LC_NUMERIC category of the current GLS locale file to scan the numstr number string. If format is not NULL, it must point to a string that follows the rules that this section describes.

To convert the numstr number string, ifx_gl_convert_number() compares each character in numstr with the format string. It takes the following actions for each possible character that it finds in format.


Contents of format string	Conversion action taken
One or more white space characters	The function skips over the corresponding number of white space characters in the `numstr` number string (unless the formatting directive begins with the minus-sign modifier), up to the first character that is not white space or until no more characters can be scanned. White space characters are characters that the blank class of the LC_CTYPE category in the current locale defines.
A valid formatting directive	The function performs the specified conversion on the numeric element in the `numstr` number string. It replaces the formatting directive with an internal representation of the numeric element for conversion to the `number` value. Only one formatting directive is allowed in the `format` string.
Ordinary characters	The function must find the same ordinary character in the `numstr` number string. Any mismatch generates an error. The differing and subsequent characters in `numstr` remain unscanned.

The formatting directive consists of the following sequence:

%[flags][maximum_width[.minimum_width]]type_specifier


Argument	See
`flags`	Field width
`maximum_width`	Field width
`minimum_width`	Field width
`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_convert_number() function to expect when it scans 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_convert_number() function supports the following formatting directives to represent a numeric element.

%b: Matches a binary integer.
%d: Matches a decimal integer
%e: Matches a floating-point number
%E: Same as %e.
%f: Same as %e.
%g: Same as %e.
%G: Same as %e.
%i: Same as %d.
%o: Matches an octal integer.
%q: Matches a base-4 integer.
%u: Matches an unsigned decimal integer.
%x: Matches a hexadecimal integer.
%X: Same as %x.

Field width

You can specify an optional field width in a formatting directive. This information follows the initial percent symbol (%) of the formatting directive and has the following format:

[-][maximum_width][.minimum_width]

[-]

Indicates field justification.

If the specification begins with a minus sign (-), the function expects the first character of the numstr number string to be the first character of the value to be converted. The function does not skip white space characters in numstr but reports them as an error.

If you omit the minus sign (-), the function assumes that the numstr string is right-aligned, and it skips any initial white space characters.

maximum_width

A decimal value that specifies the maximum number of characters to read from the numstr money string.

minimum_width

Indicates an optional minimum field width. The minimum field width has the format of a period (.) followed by a decimal number. The minimum_width decimal number represents the minimum number of characters to read. If the function reads fewer than minimum_width characters, it generates an error (unless you specified left justification). When you specify left justification, the function skips any trailing white space to read the required number of characters.

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 scan of the numstr number string.

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.