safe_negate
Use the safe_negate() function to negate a numeric value with overflow protection. Unlike standard negation, safe_negate() returns null instead of raising an error when the result overflows.
Syntax
safe_negate(<number>)Parameters
number
integer, float
Yes
The numeric value to negate.
Returns
Type: integer or float (matches input type)
Description: The safe_negate() function returns the negated value of the input (i.e., -number). If the result would overflow the numeric type, the function returns null instead of raising an error. If the input is null, the function returns null.
Usage notes
Input type: XQL doesn't support NaN or infinite values as input and these value types also can not be returned.
Overflow Protection: The primary advantage of
safe_negate()is that it returnsnullinstead of raising an error when negating the minimum integer value (for example, negating-9223372036854775808would overflow since the maximum positive 64-bit integer is9223372036854775807).Null Handling: If the input expression is
null, the function returnsnull.Double Negation:
safe_negate(safe_negate(x))returnsxfor all non-overflow cases.Common Use Cases: This function is used when working with values that might be at the boundary of the integer range, such as system-generated counters or imported data with extreme values.
Examples
Example 1: Negate literal values safely
Goal: Negate specific numeric literals, including edge cases.
XQL code:
Explanation: safe_negate(42) returns -42, safe_negate(-100) returns 100, and safe_negate(0) returns 0. These are straightforward negations with no overflow risk.
Output:
-42
100
0
Example 2: Safely negate field values
Goal: Negate values stored in a dataset field with overflow protection.
XQL code:
Explanation: This query negates each value in the numeric_value field. If any value is at the minimum integer boundary, the result is null rather than an error.
Output:
101
5.0
-5.0
102
-200.0
200.0
103
50.0
-50.0
Example 3: Use safe_negate to compute absolute difference
Goal: Calculate the absolute difference between two fields using safe negation.
XQL code:
Explanation: This query calculates the difference between two fields, then uses safe_negate() to compute the absolute value when the difference is negative. This approach safely handles potential overflow at integer boundaries.
Output:
101
5.0
1.5
3.5
3.5
102
0.8
200.0
-199.2
199.2
103
50.0
10.2
39.8
39.8
Related articles
Functions:
safe_subtract(),safe_add(),subtract(),if()Datasets:
xdr_data
Last updated
Was this helpful?
