ObjectScript Reference
$FNUMBER


Formats a numeric value with a specified format; optionally rounds or zero fills to a specified precision.
Synopsis
$FNUMBER(inumber,format,decimal)
$FN(inumber,format,decimal)
An expression that resolves to a number. Before
$FNUMBER performs any operation, InterSystems IRIS performs its standard numeric resolution on
inumber as follows: it resolves variables, performs string operations such as concatenation, converts strings to numerics, performs numeric expression operations, then converts the resulting numeric to
canonical form. This is the number that
$FNUMBER formats.
If
inumber is a string, InterSystems IRIS first converts it to a number, truncating at the first nonnumeric character. If the first character of the string is a nonnumeric character, InterSystems IRIS converts the string to 0.
The possible format codes are as follows. You can specify them singly or in combination. Alphabetic codes are not casesensitive.
In InterSystems IRIS, fractional numbers less than 1 are represented in InterSystems IRIS canonical form without a zero integer: 0.66 becomes .66. This is the
$FNUMBER default. However, most
$FNUMBER format options return fractional numbers less than 1 with a leading zero integer: .66 becomes 0.66. Twoparameter
$FNUMBER with a
format of "" (empty string), "L" (which is functionally identical to empty string), and "D" return fractional numbers less than 1 in canonical form: .66. All other twoparameter
$FNUMBER format options, and all threeparameter
$FNUMBER format options, return fractional numbers less than 1 with a single leading zero integer: 000.66 or .66 both becomes 0.66. This is the fractional number format for JSON numbers.
The
$DOUBLE function can return the values INF (infinite) and NAN (not a number). INF can take a negative sign; format codes represent INF as if it were a number. For example:
+INF,
INF,
(INF). NAN does not take a sign; the only format code that affects NAN is “d”, which returns it in lowercase letters. The “E” and “G” codes have no effect on INF and NAN values.
The
decimal parameter specifies the number of fractional digits to include in the returned value. Specify
decimal as a positive integer, or any valid ObjectScript variable or expression that evaluates to a positive integer. If
decimal is a negative number, InterSystems IRIS treats it as a 0 value. If
decimal is a fractional number, InterSystems IRIS truncates to its integer component.

If
decimal is greater than the number of fractional digits in
inumber, the remaining positions are zero filled.

If
decimal is less than the number of fractional digits in
inumber, InterSystems IRIS rounds
inumber to the appropriate number of fractional digits.

If
decimal is 0,
inumber is returned as an integer with no decimal separator character. InterSystems IRIS rounds
inumber to the appropriate integer.
If
inumber is less than 1 and
decimal greater than 0,
$FNUMBER always returns a single zero in the integer position before the decimal separator character, regardless of the
format value. This representation of fractional numbers differs from InterSystems IRIS canonical form.
You can specify the
decimal parameter to control the number of fractional digits returned, after rounding is performed. For example, assume that variable
c contains the number 6.25198.
SET c="6.25198"
SET x=$FNUMBER(c,"+",3)
SET y=$FNUMBER(c,"+",8)
WRITE !,x,!,y
The first
$FNUMBER returns +6.252 and the second returns +6.25198000.
The following examples show how the different formatting designations can affect the behavior of
$FNUMBER. These examples assume that the current locale is the default locale.
The following example shows the effects of sign codes on a positive number:
SET a=1234
WRITE $FNUMBER(a),! ; returns 1234
WRITE $FNUMBER(a,""),! ; returns 1234
WRITE $FNUMBER(a,"+"),! ; returns +1234
WRITE $FNUMBER(a,""),! ; returns 1234
WRITE $FNUMBER(a,"L"),! ; returns 1234
WRITE $FNUMBER(a,"T"),! ; returns 1234 (with a trailing space)
WRITE $FNUMBER(a,"T+"),! ; returns 1234+
The following example shows the effects of sign codes on a negative number:
SET b=1234
WRITE $FNUMBER(b,""),! ; returns 1234
WRITE $FNUMBER(b,"+"),! ; returns 1234
WRITE $FNUMBER(b,""),! ; returns 1234
WRITE $FNUMBER(b,"L"),! ; returns 1234
WRITE $FNUMBER(b,"T"),! ; returns 1234
The following example shows the effects of the “P” format code on positive and negative numbers. This example writes asterisks before and after the number to show that a positive number is returned with a leading and a trailing blank:
WRITE "*",$FNUMBER(123,"P"),"*",! ; returns *(123)*
WRITE "*",$FNUMBER(123,"P"),"*",! ; returns * 123 *
The following example returns 1,234,567.81. The
"," format returns
x in American format, inserting commas as numeric group separators and a period as the decimal separator:
SET x=1234567.81
WRITE $FNUMBER(x,",")
The following example returns 1.234.567,81. The
"." format returns
x in European format, inserting periods as numeric group separators and a comma as the decimal separator:
SET x=1234567.81
WRITE $FNUMBER(x,".")
The following 3parameter example returns 124,329.00.
$FNUMBER inserts a comma as numeric group separator, adds a period as the decimal separator, and appends two zeros as fractional digits to the value of
x.
SET x=124329
WRITE $FNUMBER(x,",",2)
The following 3parameter example returns 124329.00. The omitted
format is represented by a placeholder comma;
decimal appends two zeros as fractional digits to the value of
x.
SET x=124329
WRITE $FNUMBER(x,,2)
The following 3parameter example returns 0.78. The omitted
format is represented by a placeholder comma;
decimal rounds to 2 fractional digits;
decimal also appends the integer 0, overriding the
format default:
SET x=.7799
WRITE $FNUMBER(x,,2)
$FNUMBER uses the DecimalSeparator property value for the current locale (“.” by default) as the delimiter character between the integer part and the fractional part of the returned number. When the “.” format code is specified, this delimiter is a “,” regardless of the current locale setting.
To determine the DecimalSeparator character for your locale, invoke the
GetFormatItem() method:
WRITE ##class(%SYS.NLS.Format).GetFormatItem("DecimalSeparator")
Numeric Group Separator and Size
When the
format string includes “,”
$FNUMBER uses the NumericGroupSeparator property value from the current locale as the delimiter between groups of digits in the integer part of the returned number. The size of these groups is determined by the NumericGroupSize property of the current locale.
The English language locale defaults to a comma (“,”) as the NumericGroupSeparator and 3 as the NumericGroupSize. Many European locales use a period (“.”) as the NumericGroupSeparator. The Russian (rusw), Ukrainian (ukrw), and Czech (csyw) locales use a blank space as the NumericGroupSeparator. The NumericGroupSize defaults to 3 for all locales, including Japanese. (Users of Japanese may wish to group integer digits in units of either 3 or 4, depending upon context.)
When the
format string includes “.” (and does not include “N”)
$FNUMBER uses NumericGroupSeparator=”.” and NumericGroupSize=3 to format the return value, regardless of your current locale settings.
To determine the NumericGroupSeparator character and NumericGroupSize number for your locale, invoke the
GetFormatItem() method:
WRITE ##class(%SYS.NLS.Format).GetFormatItem("NumericGroupSeparator"),!
WRITE ##class(%SYS.NLS.Format).GetFormatItem("NumericGroupSize")
$FNUMBER uses the PlusSign and MinusSign property values for the current locale (“+” and “” by default). When the “.” format code is specified, these signs are set to “+” and “”, regardless of the current locale.
To determine the PlusSign and MinusSign characters for your locale, invoke the
GetFormatItem() method:
WRITE ##class(%SYS.NLS.Format).GetFormatItem("PlusSign"),!
WRITE ##class(%SYS.NLS.Format).GetFormatItem("MinusSign")
Differences between $FNUMBER and $INUMBER
Most format codes have similar meanings in the
$FNUMBER and
$INUMBER functions, but the exact behavior triggered by each code differs by function because of the nature of the validations and conversions being performed.
In particular, the “” and “+” format codes do not have quite the same meaning for
$FNUMBER as they do for
$INUMBER. With
$FNUMBER, “” and “+” are not mutually exclusive, and “” only affects the MinusSign (by suppressing it), and “+” only affects the PlusSign (by inserting it). With
$INUMBER, “” and “+” are mutually exclusive. “” means no sign is permitted, and “+” means there must be a sign.