# math

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

| Trait               | Value      |
| ------------------- | ---------- |
| **Module type**     | util       |
| **Implementation**  | C++        |
| **Parallelism**     | sequential |

## 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:

```cypher
// 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)
```

> **Warning**
>
> The `UNNECESSARY` rounding mode will throw an error if the input value requires rounding. Use this mode when you want to assert that a value should already be at the desired precision.