TRUNCATE (SQL)
Synopsis
{fn TRUNCATE(numeric-expr,scale)}
Description
TRUNCATE truncates numeric-expr by truncating at the scale number of digits from the decimal point. It does not round numbers or add padding zeroes. Leading and trailing zeroes are removed before the TRUNCATE operation.
-
If scale is a positive number, truncation is performed at that number of digits to the right of the decimal point. If scale is equal to or larger than the number of decimal digits, no truncation or zero filling occurs.
-
If scale is zero, the number is truncated to a whole integer. In other words, truncation is performed at zero digits to the right of the decimal point; all decimal digits and the decimal point itself are truncated.
-
If scale is a negative number, truncation is performed at that number of digits to the left of the decimal point. If scale is equal to or larger than the number of integer digits in the number, zero is returned.
-
If numeric-expr is zero (however expressed: 00.00, -0, etc.) TRUNCATE returns 0 (zero) with no decimal digits, regardless of the scale value.
-
If numeric-expr or scale is NULL, TRUNCATE returns NULL.
TRUNCATE can only be used as an ODBC scalar function (with the curly brace syntax).
ROUND can be used to perform a similar truncation operation on numbers. TRIM can be used to perform a similar truncation operation on strings.
TRUNCATE, ROUND, and $JUSTIFY
TRUNCATE and ROUND are numeric functions that perform similar operations; they both can be used to decrease the number of significant decimal or integer digits of a number. ROUND allows you to specify either rounding (the default), or truncation; TRUNCATE does not perform rounding. ROUND returns the same data type as numeric-expr; TRUNCATE returns numeric-expr as data type NUMERIC, unless numeric-expr is data type DOUBLE, in which case it returns data type DOUBLE.
TRUNCATE truncates to a specified number of fractional digits. If the truncation results in trailing zeros, these trailing zeros are preserved. However, if scale is larger than the number of fractional decimal digits in the canonical form of numeric-expr, TRUNCATE does not zero-pad.
ROUND rounds (or truncates) to a specified number of fractional digits, but its return value is always normalized, removing trailing zeros. For example, ROUND(10.004,2) returns 10, not 10.00.
Use $JUSTIFY if rounding to a fixed number of fractional digits is important — for example, when representing monetary amounts. $JUSTIFY returns the specified number of trailing zeros following the rounding operation. When the number of digits to round is larger than the number of fractional digits, $JUSTIFY zero-pads. $JUSTIFY also right-aligns the numbers, so that the DecimalSeparator characters align in a column of numbers. $JUSTIFY does not truncate.
Arguments
numeric-expr
The number to be truncated. A number or numeric expression.
scale
An expression that evaluates to an integer that specifies the number of places to truncate, counting from the decimal point. Can be zero, a positive integer, or a negative integer. If scale is a fractional number, InterSystems IRIS rounds it to the nearest integer.
TRUNCATE returns the DOUBLE, INTEGER, or NUMERIC data type.
-
If numeric-expr is of type DOUBLE, TRUNCATE returns DOUBLE.
-
If numeric-expr is of type INTEGER and scale is less than or equal to 0, TRUNCATE returns INTEGER.
-
If numeric-expr is of type NUMERIC, or of type INTEGER and scale is greater than 0, TRUNCATE returns NUMERIC.
Examples
The following two examples both truncate a number to two decimal digits, where scale is specified as an integer:
SELECT {fn TRUNCATE(654.321888,2)}
SELECT {fn TRUNCATE(654.321888,2)}
Both examples return 654.32 (truncation to two decimal places).
The following example specifies a scale larger than the number of decimal digits:
SELECT {fn TRUNCATE(654.321000,9)}
It returns 654.321 (InterSystems IRIS removed the trailing zeroes before the truncation operation; no truncation or zero padding occurred).
The following example specifies a scale of zero:
SELECT {fn TRUNCATE(654.321888,0)}
It returns 654 (all decimal digits and the decimal point are truncated).
The following example specifies a negative scale:
SELECT {fn TRUNCATE(654.321888,-2)}
It returns 600 (two integer digits have been truncated and replaced by zeroes; note that no rounding has been done).
The following example specifies a negative scale as large as the integer portion of the number:
SELECT {fn TRUNCATE(654.321888,-3)}
It returns 0.
See Also
-
ObjectScript function: $NORMALIZE