math

The math module provides essential mathematical operations for precise numeric calculations, particularly focused on rounding operations with various rounding modes.

Functions

round()

The function rounds a numeric value to a specified number of decimal places using various rounding modes. This provides precise control over how numbers are rounded.

Input:

• value: Double ➡ The numeric value to be rounded.
• precision: Integer (default = 0) ➡ The number of decimal places to round to. Positive values round to decimal places, zero rounds to the nearest integer, and negative values round to tens, hundreds, etc.
• mode: String (default = "HALF_UP") ➡ The rounding mode to use. Available modes:
  • "CEILING" - Always round towards positive infinity
  • "FLOOR" - Always round towards negative infinity
  • "UP" - Always round away from zero
  • "DOWN" - Always round towards zero
  • "HALF_UP" - Round to nearest neighbor, ties round away from zero
  • "HALF_DOWN" - Round to nearest neighbor, ties round towards zero
  • "HALF_EVEN" - Round to nearest neighbor, ties round to even number (banker’s rounding)
  • "UNNECESSARY" - Assert that no rounding is necessary (throws error if rounding would occur)

Output:

• Double ➡ The rounded numeric value.

Usage:

// Basic rounding to nearest integer (default HALF_UP mode)
RETURN math.round(2.5) AS result;
// Returns: 3.0
 
// Round to 2 decimal places
RETURN math.round(3.14159, 2) AS result;
// Returns: 3.14
 
// Round using CEILING mode
RETURN math.round(1.234, 2, "CEILING") AS result;
// Returns: 1.24
 
// Round using FLOOR mode
RETURN math.round(1.234, 2, "FLOOR") AS result;
// Returns: 1.23
 
// Round to tens place (negative precision)
RETURN math.round(1234, -1) AS result;
// Returns: 1230.0
 
// Round using HALF_EVEN (banker's rounding)
RETURN math.round(2.5, 0, "HALF_EVEN") AS result;
// Returns: 2.0 (rounds to nearest even)
 
RETURN math.round(3.5, 0, "HALF_EVEN") AS result;
// Returns: 4.0 (rounds to nearest even)