
Caché ObjectScript Reference
$FNUMBER



Server:docs1 
Instance:LATEST 
User:UnknownUser 


Formats a numeric value with a specified format; optionally rounds to a specified precision.
Synopsis
$FNUMBER(inumber,format,decimal)
$FN(inumber,format,decimal)
An expression that resolves to a number. If
inumber is a string, Caché first converts it to a number, truncating at the first nonnumeric character. (Caché converts a nonnumeric string to 0.) Before
$FNUMBER formats this number, Caché converts it to
canonical form.
The possible format codes are as follows. You can specify them singly or in combination.
In Caché, fractional numbers less than 1 are represented in canonical form without a zero integer: 0.66 becomes .66. In most cases,
$FNUMBER returns fractional numbers less than 1 with a leading zero integer: .66 becomes 0.66. However, 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 leading zero integer: .66 becomes 0.66.
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.
Rounding is performed before the number is truncated or zero filled. It can be specified as a positive integer value, the name of an integer variable, or any valid Caché ObjectScript expression that evaluates to a positive integer. If the
decimal value is 0, the number is returned as an integer, with no decimal point. If the
decimal value is greater than the number of decimal digits in the number, the remaining positions are zero filled. If
inumber itself is less than 1,
$FNUMBER inserts a leading zero before the decimal point.
You can specify the
decimal parameter to control the number of fractional digits returned, after rounding is performed. The
decimal parameter must evaluate to an integer. 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. Zero fill is performed if the
decimal parameter exceeds the number of fractional digits in the number.
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,"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;
$FNUMBER inserts a comma every 3 numerals to the left of the decimal point of
x.
SET x=1234567.81
WRITE $FNUMBER(x,",")
The following example returns 1.234.567,81;
$FNUMBER inserts European formatting to
x.
SET x=1234567.81
WRITE $FNUMBER(x,".")
The following example returns 124,329.00;
$FNUMBER inserts a comma and adds a decimal point and two zeros to the value of
x.
SET x=124329
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.