$NORMALIZE

Validates and returns a numeric value; rounds to a specified precision.

Synopsis

$NORMALIZE(num,scale)

Parameters

num	The numeric value to be validated. It can be a numeric or string value, a variable name, or any valid Caché ObjectScript expression.
scale	The number of significant digits to round num to as the returned value. This number can be larger or smaller than the actual number of decimal digits in num.

Description

The $NORMALIZE function validates num and returns the normalized form of num. It performs rounding (or truncation) of decimal digits using the scale parameter. You can use the scale parameter to round a decimal number to a specified number of decimal digits, to round a decimal number to an integer, or to truncate a decimal number to an integer.

Parameters

num

The number to be validated may be an integer, a decimal number, an exponential 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. $NORMALIZE validates character-by-character. It stops validation and returns the validated portion of the string if:

num contains any characters other than the digits 0–9, + or – signs, a decimal point (.), and the letter “E” or “e” indicating an exponent.
num contains more than decimal point, or letter “E” or “e”.
If a + or – sign is found after a numeric in num it is considered a trailing sign, and no further numerics are parsed.
The letter “E” or “e” indicating an exponent is not followed by an integer.

The scale parameter value causes the returned value to be a rounded or truncated version of the num value. The actual value of the num variable is not changed by $NORMALIZE processing.

scale

The mandatory scale parameter is used to specify how many decimal digits to round to. Depending on the value specified, scale can have no effect on decimal digits, round to a specified number of decimal digits, round to an integer, or truncate to an integer.

A non-negative scale value causes num to be rounded to that number of decimal digits. When rounding, a value of 5 or greater is always rounded up. To avoid rounding of a decimal number, make scale larger than the number of possible decimal digits in num. A scale value of 0 causes num to be rounded to an integer value (3.9 = 4). A scale value of –1 causes num to be truncated to an integer value (3.9 = 3). A scale value which is non-numeric or the null string is equivalent to a scale value of 0.

Specify an integer value for scale; decimal digits in the scale value are ignored. You can specify a scale value larger than the number of decimal digits specified in num. You can specify a scale value of –1; all other negative scale values result in a <FUNCTION> error.

Examples

In the following example, all of the $NORMALIZE calls return the normalized version of num with the specified rounding (or integer truncate):

   WRITE !,$NORMALIZE(0,0)       ; All integers OK
   WRITE !,$NORMALIZE("",0)      ; Null string is parsed as 0
   WRITE !,$NORMALIZE(4.567,2)   ; Decimal numbers OK
   WRITE !,$NORMALIZE("4.567",2) ; Numeric strings OK
   WRITE !,$NORMALIZE(-+.0,99)   ; Leading/trailing signs OK
   WRITE !,$NORMALIZE(+004.500,1) ; Leading/trailing 0's OK
   WRITE !,$NORMALIZE(4E2,-1)     ; Exponents OK

In the following example, all of the $NORMALIZE calls return a numeric subset of num:

   WRITE !,$NORMALIZE("4,567",0)
     ; NumericGroupSeparators (commas) are not recognized
     ; here validation halts at the comma, and 4 is returned.
   WRITE !,$NORMALIZE("4A",0)
     ; Invalid (non-numeric) character halts validation
     ; here 4 is returned.

The following example shows the use of the scale parameter to round (or truncate) the return value:

   WRITE !,$NORMALIZE(4.55,2)
     ; When scale is equal to the decimal digits of num,
     ; all digits of num are returned without rounding.
   WRITE !,$NORMALIZE(3.85,1)
     ; num is rounded to 1 decimal digit, 
     ; (with values of 5 or greater rounded up) 
     ; here 3.9 is returned.
   WRITE !,$NORMALIZE(4.01,17) 
     ; scale can be larger than number of decimal digits,
     ; and no rounding is peformed; here 4.01 is returned.
   WRITE !,$NORMALIZE(3.85,0)
     ; When scale=0, num is rounded to an integer value.
     ; here 4 is returned.
   WRITE !,$NORMALIZE(3.85,-1)
     ; When scale=-1, num is truncated to an integer value.
     ; here 3 is returned.

Notes

$NORMALIZE, and $NUMBER Compared

The $NORMALIZE, and $NUMBER functions both validate numbers and return a validated version of the specified number.

These two functions offer different validation criteria. Select the one that best meets your needs.

Both functions parse signed and unsigned integers (including –0), exponential numbers (with “E” or “e”), and decimal numbers. However, $NUMBER can be set (using the “I” format) to reject decimal numbers (including negative exponents that result in decimal numbers). Both functions parse both numbers (123.45) and numeric strings (“123.45”).
Both functions strip out leading and trailing zeroes. The decimal character is stripped out unless followed by a non-zero value.
Numeric strings containing a NumericGroupSeparator: $NUMBER parses NumericGroupSeparator characters (American format: comma (,); European format: period (.) or apostrophe (')) and the decimal character (American format: period (.) or European format: comma (,)) based on its format parameter (or the default for the current locale). It accepts and strips out any number of NumericGroupSeparator characters. For example, in American format it validate “123,,4,56.99” as the number 123456.99. $NORMALIZE does not recognize NumericGroupSeparator characters. It validates character-by-character until it encounters a non-numeric character; for example, it validates “123,456.99” as the number 123.
Multiple leading signs (+ and –) are interpreted by both functions for numbers. Only $NORMALIZE accepts multiple leading signs in a quoted numeric string.
Trailing + and – signs: Both functions reject trailing signs in numbers. In a quoted numeric string $NUMBER parses one (and only one) trailing sign. $NORMALIZE parses multiple trailing signs.
Parentheses: $NUMBER parses parentheses surrounding an unsigned number in a quoted string as indicating a negative number. $NORMALIZE treats parentheses as non-numeric characters.
Numeric strings containing multiple decimal characters: $NORMALIZE validates character-by-character until it encounters the second decimal character. For example, in American format it validates “123.4.56” as the number 123.4. $NUMBER rejects any string containing more than one decimal character as an invalid number.

Numeric strings containing other non-numeric characters: $NORMALIZE validates character-by-character until it encounters an alphabetic character. It validates “123A456” as the number 123. $NUMBER validates or rejects the entire string; it reject “123A456” as an invalid number.
The null string: $NORMALIZE parses the null string as zero (0). $NUMBER rejects the null string.

The $NUMBER function provide optional min/max range checking. This is also available using the $ISVALIDNUM function.

$NORMALIZE, $NUMBER, and $ISVALIDNUM all provide rounding of decimal numbers to a specified number of decimal digits. $NORMALIZE can round decimal digits, and round or truncate a decimal number to return an integer. For example, $NORMALIZE can round 488.65 to 488.7 or 489, or truncate it to 488. $NUMBER can round decimal numbers or integers. For example, $NUMBER can round 488.65 to 488.7, 489, 490 or 500.