Format numeric strings

The Informix® 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-aligned the number, enclose a negative number in parentheses, and so on. The Informix® ESQL/C library includes the following functions that support numeric-formatting masks for numeric values.

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
Both the Informix® ESQL/C library and the DataBlade® API library provide functions to convert between mi_decimal values and other C-language data types.

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:


Formatting character	Description
*	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.

When you use rfmtdec(), rfmtdouble(), or rfmtlong() to format MONEY values, the function uses the currency symbols that the DBMONEY environment variable specifies. If you do not set this environment variable, the numeric-formatting functions use the currency symbols that the client locale defines. The default locale, US English, defines currency symbols as if you set DBMONEY to $,.. For more information about locales, see the Informix® GLS User's Guide.

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

Table 1. Sample format patterns and their results
Formatting mask	Numeric value	Formatted result
"#####" "&&&&&" "$$$$$" "*****" "<<<<<"	0 0 0 0 0	bbbbb 00000 bbbb$ ***** (null string)
"##,###" "##,###" "##,###" "##,###" "##,###" "##,###" "##,###"	12345 1234 123 12 1 -1 0	12,345 b1,234 bbb123 bbbb12 bbbbb1 bbbbb1 bbbbbb
"&&,&&&" "&&,&&&" "&&,&&&" "&&,&&&" "&&,&&&" "&&,&&&" "&&,&&&"	12345 1234 123 12 1 -1 0	12,345 01,234 000123 000012 000001 000001 000000
"$$,$$$" "$$,$$$" "$$,$$$" "$$,$$$" "$$,$$$" "$$,$$$" "$$,$$$" "$$,$$$" (DBMONEY set to `DM`)	12345 1234 123 12 1 -1 0 1234	***** (overflow) $1,234 bb$123 bbb$12 bbbb$1 bbbb$1 bbbbb$ DM1,234
"," "," ",*" ",*" ",*" ",***"	12345 1234 123 12 1 0	12,345 1,234 123 12 *1 ****
"##,###.##" "##,###.##" "##,###.##" "##,###.##" "##,###.##" "##,###.##" "##,###.##" "##,###.##" "##,###.##"	12345.67 1234.56 123.45 12.34 1.23 0.12 0.01 -0.01 -1	12,345.67 b1,234.56 bbb123.45 bbbb12.34 bbbbb1.23 bbbbbb.12 bbbbbb.01 bbbbbb.01 bbbbb1.00
"&&,&&&.&&" "&&,&&&.&&" "&&,&&&.&&" "&&,&&&.&&"	.67 1234.56 123.45 0.01	000000.67 01,234.56 000123.45 000000.01
"$$,$$$.$$" "$$,$$$.$$" "$$,$$$.##" "$$,$$$.##" "$$,$$$.&&" "$$,$$$.&&"	12345.67 1234.56 0.00 1234.00 0.00 1234.00	********* (overflow) $1,234.56 bbbbb$.00 $1,234.00 bbbbb$.00 $1,234.00
"-##,###.##" "-##,###.##" "-##,###.##" "--#,###.##" "---,###.##" "---,-##.##" "---,--#.##" "--#,###.##" "---,--#.##"	-12345.67 -123.45 -12.34 -12.34 -12.34 -12.34 -12.34 -1.00 -1.00	-12,345.67 -bbb123.45 -bbbb12.34 b-bbb12.34 bb-bb12.34 bbbb-12.34 bbbb-12.34 b-bbbb1.00 bbbbb-1.00
"-##,###.##" "-##,###.##" "-##,###.##" "-##,###.##" "--#,###.##" "---,###.##" "---,-##.##" "---,---.##" "---,---.--" "---,---.&&"	12345.67 1234.56 123.45 12.34 12.34 12.34 12.34 1.00 -.01 -.01	b12,345.67 bb1,234.56 bbbb123.45 bbbbb12.34 bbbbb12.34 bbbbb12.34 bbbbb12.34 bbbbbb1.00 bbbbbb-.01 bbbbbb-.01
"-$$$,$$$.&&" "-$$$,$$$.&&" "-$$$,$$$.&&" "--$$,$$$.&&" "--$$,$$$.&&" "--$$,$$$.&&" "--$$,$$$.&&" "--$$,$$$.&&"	-12345.67 -1234.56 -123.45 -12345.67 -1234.56 -123.45 -12.34 -1.23	-$12,345.67 -b$1,234.56 -bbb$123.45 -$12,345.67 b-$1,234.56 b-bb$123.45 b-bbb$12.34 b-bbbb$1.23
"----,--$.&&" "----,--$.&&" "----,--$.&&" "----,--$.&&" "----,--$.&&" "----,--$.&&"	-12345.67 -1234.56 -123.45 -12.34 -1.23 -.12	-$12,345.67 b-$1,234.56 bbb-$123.45 bbbb-$12.34 bbbbb-$1.23 bbbbbb-$.12
"$*,.&&" "$,.&&" "$,.&&" "$,.&&" "$,.&&" "$,*.&&"	12345.67 1234.56 123.45 12.34 1.23 .12	$12,345.67 $1,234.56 $*123.45 $*12.34 $**1.23 $*****.12
"($$$,$$$.&&)" "($$$,$$$.&&)" "($$$,$$$.&&)"	-12345.67 -1234.56 -123.45	($12,345.67) (b$1,234.56) (bbb$123.45)
"(($$,$$$.&&)" "(($$,$$$.&&)" "(($$,$$$.&&)" "(($$,$$$.&&)" "(($$,$$$.&&)" "((((,(($.&&)" "((((,(($.&&)" "((((,(($.&&)" "((((,(($.&&)" "((((,(($.&&)" "((((,(($.&&)"	-12345.67 -1234.56 -123.45 -12.34 -1.23 -12345.67 -1234.56 -123.45 -12.34 -1.23 -.12	($12,345.67) b($1,234.56) b(bb$123.45) b(bbb$12.34) b(bbbb$1.23) ($12,345.67) b($1,234.56) bbb($123.45) bbbb($12.34) bbbbb($1.23) bbbbbb($.12)
"($$$,$$$.&&)" "($$$,$$$.&&)" "($$$,$$$.&&)"	12345.67 1234.56 123.45	b$12,345.67 bb$1,234.56 bbbb$123.45
"(($$,$$$.&&)" "(($$,$$$.&&)" "(($$,$$$.&&)" "(($$,$$$.&&)" "(($$,$$$.&&)"	12345.67 1234.56 123.45 12.34 1.23	b$12,345.67 bb$1,234.56 bbbb$123.45 bbbbb$12.34 bbbbbb$1.23
"((((,(($.&&)" "((((,(($.&&)" "((((,(($.&&)" "((((,(($.&&)" "((((,(($.&&)" "((((,(($.&&)"	12345.67 1234.56 123.45 12.34 1.23 .12	b$12,345.67 bb$1,234.56 bbbb$123.45 bbbbb$12.34 bbbbbb$1.23 bbbbbbb$.12
"<<<,<<<" "<<<,<<<" "<<<,<<<" "<<<,<<<"	12345 1234 123 12	12,345 1,234 123 12