Article Directory

Chapter 23 Caché Function Collection $ISVALIDNUM Function
Outline
- parameter
description
- on one
- scale
- min and max
Example
note
- `$ISVALIDDOUBLE` and `$ISVALIDNUM` comparison
- `$ISVALIDNUM`, `$NORMALIZE` and `$NUMBER` comparison

Chapter 23 Caché Function Collection $ISVALIDNUM Function

Validate the value and return a boolean; optionally provide range checking.

Outline

$ISVALIDNUM(num,scale,min,max)

parameter

num The value to be verified. It can be a numeric or string value, a variable name, or any valid ObjectScript expression.
scale Optional-the number of valid decimal places to compare the minimum and maximum ranges.
min Optional-the smallest value allowed.
max optional-the maximum value allowed.

description

on one

The number to be verified can be an integer, real number, or scientific notation number (with letters “E”or “e”). It can be a string, an expression, or a variable parsed as a number. It can be signed or unsigned, and can contain leading or trailing zeros. In the following cases, verification fails ( $ISVALIDNUMreturns 0):

num is an empty string ( “”).
num contains any characters other than numbers 0–9, leading +OR –, decimal point ( 。) and letters “E”or “e”.
num contains multiple +or –symbols, decimal points or letters “E”or “e”.
The optional +or –symbol is not the first character of num.
A letter representing the base 10 exponent “E”or “e”an integer in a string followed by a number.

In addition $ISVALIDNUM, specifying a decimal number with a non-integer exponent in any expression will cause an error. For example, write 7E3.5.

The Scale parameter value is evaluated using the rounded or truncated version of the value. $ISVALIDNUMProcessing does not change the actual value of the num variable.

If num is $DOUBLEreturned INF, -INFor NANvalue, then $ISVALIDNUM1 is returned.

The largest floating point number supported by Caché is 1.7976931348623157081E308. Specifying a larger number in any Caché numerical operation will cause an error. $ISVALIDNUMThe maximum Caché decimal floating point number specified as a supported string is 9.223372036854775807E145. For floating-point number strings greater than this length, please use $ISVALIDDOUBLE.

scale

The Scale parameter is used to specify the number of decimal places to compare during range checking. Specify an integer value for the scale bar; decimal places in the scale bar value will be ignored. You can specify a scale value greater than the number of decimal places specified in other parameters. You can specify the scale value as -1; all other negative scale values will cause <function>an error.

Non-negative range values will cause num to be rounded to that number of decimal places before performing minimum and maximum range checks. A scale value of 0 will cause num to be rounded to an integer value ( 3.9=4) before performing the range check . A scale value of -1 will cause num to be truncated to an integer value ( 3.9=3) before performing the range check . To compare all specified numbers without rounding or truncation, omit the Scale parameter. A scale value that is not a number or an empty string is equivalent to a scale value of 0.

Perform rounding on all scale values except -1. Values of 5 or greater are always rounded up.

If you omit the Scale parameter, keep the comma as a placeholder.

When rounding numbers, please note that the precision of IEEE floating-point numbers and Caché decimals are different. $DOUBLEIEEE floating point numbers are encoded using binary notation. Their precision is 53 binary digits, which is equivalent to the precision of 15.95 decimal digits. (Please note that binary notation does not exactly correspond to decimal fractions.). Since most decimals cannot be accurately represented by this binary notation, IEEE floating-point numbers may be slightly different from the corresponding Caché floating-point numbers. On all supported Caché system platforms, the accuracy of Caché decimals is 18 decimal places. When IEEE floating-point numbers are displayed as decimals, the binary digits are usually converted to decimals with far more than 18 decimal digits. This does not mean that IEEE floating point numbers are more accurate than Caché decimals.

min and max

You can specify the minimum allowable value, the maximum allowable value, neither or both. If specified, the Num value (after the scaling operation) must be greater than or equal to the minimum and less than or equal to the maximum. The empty string as the minimum or maximum value is equal to zero. If the value does not meet these conditions, $ISVALIDNUM0 will be returned.

If you omit the parameter, keep the comma as a placeholder. For example, when SCALE is omitted and MIN or MAX is specified, or MIN is omitted and MAX is specified. Trailing commas will be ignored.

If the NUM, MIN, or MAX value is a $DOUBLEnumber, then for this range check, all three numbers are treated as $DOUBLEnumbers. This prevents $DOUBLEthe small generated fractional part of the number from causing unexpected range errors.

Example

In the following example, each call $ISVALIDNUMreturns 1 (a significant number):

/// d ##class(PHA.TEST.Function).ISVALIDNUM()
ClassMethod ISVALIDNUM()
{
    
    
	WRITE !,$ISVALIDNUM(0)        ; 所有整数 OK
	WRITE !,$ISVALIDNUM(4.567)    ; 小数 OK
	WRITE !,$ISVALIDNUM("4.567")  ; 数字字符 OK
	WRITE !,$ISVALIDNUM(-.0)      ; 符号数字 OK
	WRITE !,$ISVALIDNUM(+004.500) ; 前导或尾随0 OK
	WRITE !,$ISVALIDNUM(4E2)      ; 科学计数 OK
}

DHC-APP>d ##class(PHA.TEST.Function).ISVALIDNUM()
 
1
1
1
1
1
1

In the following example, each call $ISVALIDNUMreturns 0 (invalid number):

/// d ##class(PHA.TEST.Function).ISVALIDNUM1()
ClassMethod ISVALIDNUM1()
{
    
    
	WRITE !,$ISVALIDNUM("")      ; 空字符串无效
	WRITE !,$ISVALIDNUM("4,567") ; 逗号不允许
	WRITE !,$ISVALIDNUM("4A")    ; 无效字符
}

DHC-APP>d ##class(PHA.TEST.Function).ISVALIDNUM1()
 
0
0
0

In the following example, each call $ISVALIDNUMreturns 1 (a significant number), even if INF(infinity) and NaN(not an A number) are strictly not numbers:

/// d ##class(PHA.TEST.Function).ISVALIDNUM2()
ClassMethod ISVALIDNUM2()
{
    
    
	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
}

DHC-APP> d ##class(PHA.TEST.Function).ISVALIDNUM2()
 
1
1
1
1

The following example shows the use of min and max parameters. All of the following return 1 (the number is valid and the range check is also passed):

/// d ##class(PHA.TEST.Function).ISVALIDNUM3()
ClassMethod ISVALIDNUM3()
{
    
    
	WRITE !,$ISVALIDNUM(4,,3,5)    ; scale 可以忽略
	WRITE !,$ISVALIDNUM(4,2,3,5)   ; scale 可以大于整数位数
	WRITE !,$ISVALIDNUM(4,0,,5)    ; 最大最小值可以忽略
	WRITE !,$ISVALIDNUM(4,0,4,4)   ; 包含最大最小值
	WRITE !,$ISVALIDNUM(-4,0,-5,5) ; 负数
	WRITE !,$ISVALIDNUM(4.00,2,04,05) ; 前导或尾随0 
	WRITE !,$ISVALIDNUM(.4E3,0,3E2,400) ; 以10为底的指数扩展
}

DHC-APP>d ##class(PHA.TEST.Function).ISVALIDNUM3()
 
1
1
1
1
1
1
1

The following example shows the use of the Scale parameter with min and max. All of the following return 1 (the number is valid and also passes the range check):

/// d ##class(PHA.TEST.Function).ISVALIDNUM4()
ClassMethod ISVALIDNUM4()
{
    
    
   WRITE !,$ISVALIDNUM(4.55,,4.54,4.551)
     ; 省略小数位时，将检查num的所有数字。
   WRITE !,$ISVALIDNUM(4.1,0,4,4.01)
     ; 当scale = 0时，num在最小值和最大值检查之前四舍五入为整数值（0个小数位）。
   WRITE !,$ISVALIDNUM(3.85,1,3.9,5)
     ; Num四舍五入为1个小数位数(值向上舍入为5或更大)；在进行最小检查之前。
   WRITE !,$ISVALIDNUM(4.01,17,3,5) 
     ; 小数位数可以大于数字位数。
   WRITE !,$ISVALIDNUM(3.9,-1,2,3)
     ; 当scale = -1时，num被截断为整数值
}

DHC-APP>d ##class(PHA.TEST.Function).ISVALIDNUM4()
 
1
1
1
1
1

note

`$ISVALIDDOUBLE`And `$ISVALIDNUM`compare

$ISVALIDDOUBLE$ISVALIDNUMBoth the and functions validate the number in the US format and return a Boolean value (0 or 1).

Both functions accept $DOUBLEreturns INF, -INFand NaNvalue as a valid number. $ISVALIDDOUBLEAlso accepts strings are not case-sensitive “NaN”and “INF”, variants “Infinity”, and “snan”and any combination of single plus or minus sign at the beginning of the string as a valid number. $ISVALIDNUMReject all these strings on the grounds of invalidity and return 0.

/// d ##class(PHA.TEST.Function).ISVALIDDOUBLE6()
ClassMethod ISVALIDDOUBLE6()
{
    
    
	WRITE !,$ISVALIDNUM($DOUBLE("NAN"))    ; returns 1
	WRITE !,$ISVALIDDOUBLE($DOUBLE("NAN")) ; returns 1
	WRITE !,$ISVALIDNUM("NAN")             ; returns 0
	WRITE !,$ISVALIDDOUBLE("NAN")          ; returns 1
}

Both of these functions parse signed and unsigned integers (including -0), numbers in scientific notation (with an “E”OR “e”), real numbers ( 123.45), and numeric strings ( “123.45”). Treat all these strings as invalid and return 0.
Neither function recognizes the European decimal separator character (comma ( ，)) or NumericGroupSeparatorcharacter (American format: comma ( ，); European format: period ( .)). For example, regardless of the current locale settings, both will “123,456”reject character strings as invalid numbers.
Both of these functions parse multiple leading symbols ( +and -) of numbers . Neither accept multiple leading symbols in quoted numeric strings.

If the number string is too large to be represented by a Caché floating point number, it will be automatically converted to an IEEE double-precision number by default. However, such a large number fails the $ISVALIDNUMtest, as shown in the following example:

/// d ##class(PHA.TEST.Function).ISVALIDNUM5()
ClassMethod ISVALIDNUM5()
{
    
    
	WRITE !,"E127不需要IEEE转换"
	WRITE !,$ISVALIDNUM("9223372036854775807E127")
	WRITE !,$ISVALIDDOUBLE("9223372036854775807E127")
	WRITE !,"E128自动IEEE转换"
	WRITE !,$ISVALIDNUM("9223372036854775807E128")
	WRITE !,$ISVALIDDOUBLE("9223372036854775807E128")
}

`$ISVALIDNUM`, `$NORMALIZE`And `$NUMBER`compare

$ISVALIDNUM, $NORMALIZEAnd $NUMBERfunctions all verify numbers. $ISVALIDNUMReturns a boolean value (0 or 1). $NORMALIZEAnd $NUMBERreturn the verified version of the specified number.

DHC-APP>w $number("1.1",0)
1
DHC-APP>w $number("1.5",0)
2
DHC-APP>w $number("1.5",-1)
0

These three functions provide different verification standards. Choose the one that best meets your needs.

The US format number is verified by all three functions. Numbers in European format are only $NUMBERverified by functions.
These three functions all resolve signed and unsigned integers (including -0), numbers in scientific notation (with “E”or “e”), and numbers with fractional parts. However, you can (using the “i”format) $numberset to reject numbers with fractional parts (including scientific notation with negative base 10 exponents). These three functions parse numbers ( 123.45) and number strings ( “123.45”) at the same time .
All three functions will remove leading and trailing zeros. Unless it is followed by a non-zero value, the decimal character will be removed.
DecimalSeparator: $numberValidate decimal characters (US format: period ( .). Or European format: comma ( ，)) based on its format parameters (or the default value of the current locale). Other functions only validate decimal numbers in American format, regardless of the current locale.
NumericGroupSeparator: $NumberAccept NumericGroupSeparatorcharacters (American format: comma ( ，) or space; European format: period ( .). or space). It accepts and strips any number of NumericGroupSeparatorcharacters, regardless of position. For example, in the US format, it will be “12 3，，4，56.9，9”verified as a number 123456.99. Characters are $Normalizenot recognized NumericGroupSeparator. It verifies character by character until it encounters a non-numeric character; for example, it “123,456.99”verifies as a number 123. Reject $ISVALIDNUMthe character string “123,456”as an invalid number.
All three functions of numbers interpret multiple leading symbols ( +and -). However, only $Normalizemultiple leading symbols in quoted numeric strings are accepted.
Trailing +and -signs: All three functions reject trailing signs in numbers. However, in the quoted number string $NUMBER, $NORMALIZEone (and only one) trailing symbol is $NORMALIZEparsed, multiple trailing symbols are parsed, and $ISVALIDNUMany string containing trailing symbols is rejected as invalid numbers.
Brackets: $numberParse the brackets around unsigned numbers in quoted strings as negative numbers. $NormalizeAnd $ISVALIDNUMreject brackets.
Numeric string containing multiple decimal characters: $NORMALIZEverify character by character until the second decimal character is encountered. For example, in the US format, it will be “123.4.56”verified as a number 123.4. $NUMBERAnd $ISVALIDNUMreject any string containing more than one decimal character as an invalid number.

Numeric strings containing other non-numeric characters: $NormizeVerify character by character until an alphabetic character is encountered. It is confirmed “123A456”as a number 123. $NUMBERAnd $ISVALIDNUMverify the entire string, they will be “123A456”rejected as invalid numbers.

Empty string: $NormalizeParse an empty string into zero (0). $NUMBERAnd $ISVALIDNUMreject empty strings.

$ISVALIDNUMThe sum $NUMBERfunction provides optional minimum/maximum range checking.

$ISVALIDNUM, $NORMALIZEAnd $NUMBERboth provide rounding of numbers to the specified number of decimal places. $ISVALIDNUMAnd $NORMALIZEit may be rounded to the decimal places, and the number with a fractional part is rounded or truncated to the integer return. For example, it $NORMALIZEcan be 488.65rounded to 488.7or 489, or it can be truncated to 488. $numberEither decimal places or integer places can be rounded. For example, $NUMBERyou can round to 488.65to 488.7.

DHC-APP>w $number(488.65)
488.65
DHC-APP>w $number(488.65,1)
488.7
DHC-APP>w $number(488.65,0)
489
DHC-APP>w $NORMALIZE(488.65,0)
489
DHC-APP>w $NORMALIZE(488.65,1)
488.7
DHC-APP>w $NORMALIZE(488.65,3)
488.65
DHC-APP>w $NORMALIZE(488.65,-1)
488

$NORMALIZEIt can $numberbe rounded directly or rounded up, and both can return numbers.