Caché ObjectScript Reference
$ISVALIDNUM
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Validates a numeric value and returns a boolean; optionally provides range checking.
Synopsis
$ISVALIDNUM(num,scale,min,max)
Parameters
num The numeric value to be validated. It can be a numeric or string value, a variable name, or any valid ObjectScript expression.
scale Optional — The number of significant fractional digits for min and max range comparisons.
min Optional — The minimum permitted numeric value.
max Optional — The maximum permitted numeric value.
Description
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.
Parameters
num
The number to be validated may be an integer, a real number, or a scientific notation number (with the letter “E” or “e”). It may be a string, expression, or variable that resolves to a number. It may be signed or unsigned, and may contain leading or trailing zeros. Validation fails ($ISVALIDNUM returns 0) if:
With the exception of $ISVALIDNUM, specifying a base-10 number with a non-integer 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.
If num is the INF, –INF, or NAN value returned by $DOUBLE, $ISVALIDNUM returns 1.
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.
Examples
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) ; base-10 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
 
Notes
$ISVALIDNUM and $ISVALIDDOUBLE Compared
The $ISVALIDNUM and $ISVALIDDOUBLE functions both validate numbers and return a boolean value (0 or 1).
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 double-precision 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
The $ISVALIDNUM, $NORMALIZE, and $NUMBER functions all validate numbers. $ISVALIDNUM returns a boolean value (0 or 1). $NORMALIZE and $NUMBER return a validated version of the specified number.
These three functions offer different validation criteria. Select the one that best meets your needs.
The $ISVALIDNUM and $NUMBER functions provide optional min/max range checking.
$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.
See Also