Formatting Numeric Strings

The ESQL/C library provides special functions that enable you to format numeric expressions as strings. These numeric-formatting functions apply a given formatting mask to a numeric value to allow you to line up decimal points, right- or left-justify the number, enclose a negative number in parentheses, and so on. The ESQL/C library includes the following functions that support numeric-formatting masks for numeric values.

Function Name

Description

rfmtdec( )

Converts an mi_decimal value to a string

rfmtdouble( )

Converts a C-language double value to a string

rfmtlong( )

Converts a C-language long integer value to a string

Tip:

Both the ESQL/C library and the DataBlade API library provide functions to convert between mi_decimal values and other C-language data types. For more information, see Converting Decimal Data.

This section describes the characters that you can use to create a numeric- formatting mask. It also provides extensive examples that show the results of applying these masks to numeric values. A numeric-formatting mask specifies a format to apply to some numeric value. This mask is a combination of the following formatting characters:

*

This character fills with asterisks any positions in the display field that would otherwise be blank.

&

This character fills with zeros any positions in the display field that would otherwise be blank.

#

This character changes leading zeros to blanks. Use this character to specify the maximum leftward extent of a field.

<

This character left-justifies the numbers in the display field. It changes leading zeros to a null string.

,

This character indicates the symbol that separates groups of three digits (counting leftward from the units position) in the whole-number part of the value. By default, this symbol is a comma. You can set the symbol with the DBMONEY environment variable. In a formatted number, this symbol appears only if the whole-number part of the value has four or more digits.

.

This character indicates the symbol that separates the whole-number part of a money value from the fractional part. By default, this symbol is a period. You can set the symbol with the DBMONEY environment variable. You can have only one period in a format string.

-

This character is a literal. It appears as a minus sign when expr1 is less than zero. When you group several minus signs in a row, a single minus sign floats to the rightmost position that it can occupy; it does not interfere with the number and its currency symbol.

+

This character is a literal. It appears as a plus sign when expr1 is greater than or equal to zero and as a minus sign when expr1 is less than zero. When you group several plus signs in a row, a single plus or minus sign floats to the rightmost position that it can occupy; it does not interfere with the number and its currency symbol.

(

This character is a literal. It appears as a left parenthesis to the left of a negative number. It is one of the pair of accounting parentheses that replace a minus sign for a negative number. When you group several in a row, a single left parenthesis floats to the rightmost position that it can occupy; it does not interfere with the number and its currency symbol.

)

This is one of the pair of accounting parentheses that replace a minus sign for a negative value.

$

This character displays the currency symbol that appears at the front of the numeric value. By default, the currency symbol is the dollar ($) sign. You can set the currency symbol with the DBMONEY environment variable. When you group several dollar signs in a row, a single currency symbol floats to the rightmost position that it can occupy; it does not interfere with the number.

Any other characters in the formatting mask are reproduced literally in the result.

When you use the following characters within a formatting mask, the characters float; that is, multiple occurrences of the character at the left of the pattern in the mask appear as a single character as far to the right as possible in the formatted number (without removing significant digits):

-
+

(

)

$

For example, if you apply the mask $$$,$$$.## to the number 1234.56, the result is $1,234.56.

Table 16 shows sample format strings for numeric expressions. The character b represents a blank or space.