Caché ObjectScript Reference
$NORMALIZE
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

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 fractional digits in num. Permitted values are 0 (round to integer), –1 (truncate to integer), and positive integers (round to specified number of fractional digits). There is no maximum scale value. However, the functional maximum cannot exceed the numeric precision. For standard Caché fractional numbers the functional scale maximum is 18 (minus the number of integer digits – 1).
Description
The $NORMALIZE function validates num and returns the normalized form of num. It performs rounding (or truncation) of fractional digits using the scale parameter. You can use the scale parameter to round a real number to a specified number of fractional digits, to round a real number to an integer, or to truncate a real number to an integer.
After rounding, $NORMALIZE removes trailing zeros from the return value. For this reason, the number of fractional digits returned may be less than the number specified in scale, as shown in the following example:
  WRITE $NORMALIZE($ZPI,11),!
  WRITE $NORMALIZE($ZPI,12),!   /* trailing zero removed */
  WRITE $NORMALIZE($ZPI,13),!
  WRITE $NORMALIZE($ZPI,14)
 
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. $NORMALIZE validates character-by-character. It stops validation and returns the validated portion of the string if:
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 fractional digits to round to. Depending on the value specified, scale can have no effect on fractional digits, round to a specified number of fractional digits, round to an integer, or truncate to an integer.
A nonnegative scale value causes num to be rounded to that number of fractional digits. When rounding, a value of 5 or greater is always rounded up. To avoid rounding a number, make scale larger than the number of possible fractional 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 nonnumeric 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, each invocation of $NORMALIZE returns the normalized version of num with the specified rounding (or integer truncation):
   WRITE !,$NORMALIZE(0,0)        ; All integers OK
   WRITE !,$NORMALIZE("",0)       ; Null string is parsed as 0
   WRITE !,$NORMALIZE(4.567,2)    ; Real 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)     ; Scientific notation OK   
 
In the following example, each invocation of $NORMALIZE returns 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 (nonnumeric) 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 fractional digits of num,
     ; all digits of num are returned without rounding.
   WRITE !,$NORMALIZE(3.85,1)
     ; num is rounded to 1 fractional 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 fractional 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
$DOUBLE Numbers
$DOUBLE IEEE floating point numbers are encoded using binary notation. Most decimal fractions cannot be exactly represented in this binary notation. When a $DOUBLE value is input to $NORMALIZE with a scale value, the return value frequently contains more fractional digits than specified in scale because the fractional decimal result is not representable in binary, so the return value must be rounded to the nearest representable $DOUBLE value, as shown in the following example:
  SET x=1234.1234
  SET y=$DOUBLE(1234.1234)
  WRITE "Decimal: ",$NORMALIZE(x,2),!
  WRITE "Double: ",$NORMALIZE(y,2),!
  WRITE "Dec/Dub: ",$NORMALIZE($DECIMAL(y),2)
 
If you are normalizing a $DOUBLE value for decimal formatting, you should convert the $DOUBLE value to decimal representation before normalizing the result, as shown in the above example.
$NORMALIZE handles $DOUBLE("INF") and $DOUBLE("NAN") values, and returns INF and NAN.
DecimalSeparator Value Ignored
$NORMALIZE is intended to operate on numbers, not strings. It converts num to a Caché canonical number prior to performing normalization. This is the same as appending a + sign to a string to force its interpretation as a number. This conversion to a canonical number does not use the DecimalSeparator property value for the current locale.
For example, of you specify for num the string "00123.4500", $NORMALIZE treats this as the canonical number 123.45, regardless of the current DecimalSeparator value. If you specify the string "00123,4500", $NORMALIZE treats this as the canonical number 123 (truncating at the first non-numeric character), regardless of the current DecimalSeparator value.
If you want a function that takes a string as input, use $INUMBER. If you want a function that produces a string result use $FNUMBER.
$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.
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 numbers to a specified number of fractional digits. $NORMALIZE can round fractional digits, and round or truncate a real 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 real numbers or integers. For example, $NUMBER can round 488.65 to 488.7, 489, 490 or 500.
See Also