Caché ObjectScript Reference
$ISVALIDNUM


Validates a numeric value and returns a boolean; optionally provides range checking.
Synopsis
$ISVALIDNUM(num,scale,min,max)
The
$ISVALIDNUM function validates
num and returns a boolean value. It optionally performs a range check using
min and
max values. The
scale parameter is used during range checking to specify how many fractional digits to compare. A boolean value of 1 means that
num is a properly formed number and passes the range check, if one is specified.
$ISVALIDNUM validates American format numbers, which use a period (.) as the decimal separator. It does not validate European format numbers, which use a comma (,) as the decimal separator.
$ISVALIDNUM does not consider valid a number that contains numeric group separators; it returns 0 (invalid) for any number containing a comma or a blank space, regardless of the current locale.
With the exception of
$ISVALIDNUM, specifying a base10 number with a noninteger exponent in any expression results in a <SYNTAX> error. For example,
WRITE 7E3.5.
The
scale parameter value causes evaluation using rounded or truncated versions of the
num value. The actual value of the
num variable is not changed by
$ISVALIDNUM processing.
The largest floating point number that Caché supports is 1.7976931348623157081E308. Specifying a larger number in any Caché numeric operation generates a <MAXNUMBER> error. The largest Caché decimal floating point number specified as a string that
$ISVALIDNUM supports is 9.223372036854775807E145. For floating point number strings larger than this, use
$ISVALIDDOUBLE. For further details, refer to
“Extremely Large Numbers” in the
“Data Types and Values” chapter of
Using Caché ObjectScript.
scale
The
scale parameter is used during range checking to specify how many fractional digits to compare. Specify an integer value for
scale; fractional digits in the
scale value are ignored. You can specify a
scale value larger than the number of fractional digits specified in the other parameters. You can specify a
scale value of –1; all other negative
scale values result in a <FUNCTION> error.
A nonnegative
scale value causes
num to be rounded to that number of fractional digits before performing
min and
max range checking. A
scale value of 0 causes
num to be rounded to an integer value (3.9 = 4) before performing range checking. A
scale value of –1 causes
num to be truncated to an integer value (3.9 = 3) before performing range checking. To compare all specified digits without rounding or truncating, omit the
scale parameter. A
scale value that is nonnumeric or the null string is equivalent to a
scale value of 0.
Rounding is performed for all
scale values except –1. A value of 5 or greater is always rounded up.
If you omit the
scale parameter, retain the comma as a place holder.
When rounding numbers, be aware that IEEE floating point numbers and standard Caché fractional numbers differ in precision.
$DOUBLE IEEE floating point numbers are encoded using binary notation. They have a precision of 53 binary bits, which corresponds to 15.95 decimal digits of precision. (Note that the binary representation does not correspond exactly to a decimal fraction.) Because most decimal fractions cannot be exactly represented in this binary notation, an IEEE floating point number may differ slightly from the corresponding standard Caché floating point number. Standard Caché fractional numbers have a precision of 18 decimal digits on all supported Caché system platforms. When an IEEE floating point number is displayed as a fractional number, the binary bits are often converted to a fractional number with far more than 18 decimal digits. This
does not mean that IEEE floating point numbers are more precise than standard Caché fractional numbers.
min and max
You can specify a minimum allowed value, a maximum allowed value, neither, or both. If specified, the
num value (after the
scale operation) must be greater than or equal to the
min value, and less than or equal to the
max value. A null string as a
min or
max value is equal to zero. If a value does not meet these criteria,
$ISVALIDNUM returns 0.
If you omit a parameter, retain the comma as a place holder. For example, when omitting
scale and specifying
min or
max, or when omitting
min and specifying
max. Trailing commas are ignored.
If the
num,
min, or
max value is a
$DOUBLE number, then all three of these numbers are treated as a
$DOUBLE number for this range check. This prevents unexpected range errors caused by the small generated fractional part of a
$DOUBLE number.
In the following example, each invocation of
$ISVALIDNUM returns 1 (valid number):
WRITE !,$ISVALIDNUM(0) ; All integers OK
WRITE !,$ISVALIDNUM(4.567) ; Real numbers OK
WRITE !,$ISVALIDNUM("4.567") ; Numeric strings OK
WRITE !,$ISVALIDNUM(.0) ; Signed numbers OK
WRITE !,$ISVALIDNUM(+004.500) ; Leading/trailing zeroes OK
WRITE !,$ISVALIDNUM(4E2) ; Scientific notation OK
In the following example, each invocation of
$ISVALIDNUM returns 0 (invalid number):
WRITE !,$ISVALIDNUM("") ; Null string is invalid
WRITE !,$ISVALIDNUM("4,567") ; Commas are not permitted
WRITE !,$ISVALIDNUM("4A") ; Invalid character
In the following example, each invocation of
$ISVALIDNUM returns 1 (valid number), even though INF (infinity) and NAN (Not A Number) are, strictly speaking, not numbers:
DO ##class(%SYSTEM.Process).IEEEError(0)
WRITE !,$ISVALIDNUM($DOUBLE($ZPI)) ; DOUBLE numbers OK
WRITE !,$ISVALIDNUM($DOUBLE("INF")) ; DOUBLE INF OK
WRITE !,$ISVALIDNUM($DOUBLE("NAN")) ; DOUBLE NAN OK
WRITE !,$ISVALIDNUM($DOUBLE(1)/0) ; generated INF OK
The following example shows the use of the
min and
max parameters. All of the following return 1 (number is valid and also passes the range check):
WRITE !,$ISVALIDNUM(4,,3,5) ; scale can be omitted
WRITE !,$ISVALIDNUM(4,2,3,5) ; scale can be larger than
; number of fractional digits
WRITE !,$ISVALIDNUM(4,0,,5) ; min or max can be omitted
WRITE !,$ISVALIDNUM(4,0,4,4) ; min and max are inclusive
WRITE !,$ISVALIDNUM(4,0,5,5) ; negative numbers
WRITE !,$ISVALIDNUM(4.00,2,04,05) ; leading/trailing zeros
WRITE !,$ISVALIDNUM(.4E3,0,3E2,400) ; base10 exponents expanded
The following example shows the use of the
scale parameter with
min and
max. All of the following return 1 (number is valid and also passes the range check):
WRITE !,$ISVALIDNUM(4.55,,4.54,4.551)
; When scale is omitted, all digits of num are checked.
WRITE !,$ISVALIDNUM(4.1,0,4,4.01)
; When scale=0, num is rounded to an integer value
; (0 fractional digits) before min & max check.
WRITE !,$ISVALIDNUM(3.85,1,3.9,5)
; num is rounded to 1 fractional digit,
; (with values of 5 or greater rounded up)
; before min check.
WRITE !,$ISVALIDNUM(4.01,17,3,5)
; scale can be larger than number of fractional digits.
WRITE !,$ISVALIDNUM(3.9,1,2,3)
; When scale=1, num is truncated to an integer value
$ISVALIDNUM and $ISVALIDDOUBLE Compared

Both functions accept as valid numbers the INF, –INF, and NAN values returned by
$DOUBLE.
$ISVALIDDOUBLE also accepts as valid numbers the not casesensitive strings “NAN” and “INF”, as well as the variants “Infinity” and “sNAN”, and any of these strings beginning with a single plus or minus sign.
$ISVALIDNUM rejects all of these strings as invalid, and returns 0.
WRITE !,$ISVALIDNUM($DOUBLE("NAN")) ; returns 1
WRITE !,$ISVALIDDOUBLE($DOUBLE("NAN")) ; returns 1
WRITE !,$ISVALIDNUM("NAN") ; returns 0
WRITE !,$ISVALIDDOUBLE("NAN") ; returns 1

Both functions parse signed and unsigned integers (including –0), scientific notation numbers (with “E” or “e”), real numbers (123.45) and numeric strings (“123.45”).

Neither function recognizes the European DecimalSeparator character (comma (,)) or the NumericGroupSeparator character (American format: comma (,); European format: period (.)). For example, both reject the string “123,456” as an invalid number, regardless of the current locale setting.

Both functions parse multiple leading signs (+ and –) for numbers. Neither accepts multiple leading signs in a quoted numeric string.
If a numeric string is too big to be represented by a Caché floating point number, the default is to automatically convert it to an IEEE doubleprecision number. However, such large numbers fail the
$ISVALIDNUM test, as shown in the following example:
WRITE !,"E127 no IEEE conversion required"
WRITE !,$ISVALIDNUM("9223372036854775807E127")
WRITE !,$ISVALIDDOUBLE("9223372036854775807E127")
WRITE !,"E128 automatic IEEE conversion"
WRITE !,$ISVALIDNUM("9223372036854775807E128")
WRITE !,$ISVALIDDOUBLE("9223372036854775807E128")
$ISVALIDNUM, $NORMALIZE, and $NUMBER Compared
These three functions offer different validation criteria. Select the one that best meets your needs.
$ISVALIDNUM,
$NORMALIZE, and
$NUMBER all provide rounding of numbers to a specified number of fractional digits.
$ISVALIDNUM and
$NORMALIZE can round fractional digits, and round or truncate a number with a fractional part to return an integer. For example,
$NORMALIZE can round 488.65 to 488.7 or 489, or truncate it to 488.
$NUMBER can round both fractional digits and integer digits. For example,
$NUMBER can round 488.65 to 488.7, 489, 490 or 500.