math/roundeven
===============================================================================
%% Round to nearest integer (ties to even)
1. Usage
-------------------------------------------------------------------------------
```mech:disabled
Y := math/roundeven(X)
```
2. Description
-------------------------------------------------------------------------------
Rounds each element of the input to the nearest integer, with halfway cases
rounded to the **nearest even integer**. This rule is also known as
"banker's rounding" or **round half to even**.
$$ y = \mathrm{roundeven}(x)
3. Input
-------------------------------------------------------------------------------
| Argument | Kind | Description |
|----------|------------------------------|-------------|
| `X` | `float`, `[float]`, `matrix` | Real-valued input(s). Supported scalar types are `f64` and `f32`, and their vector/matrix forms. |
4. Output
-------------------------------------------------------------------------------
| Argument | Kind | Description |
|----------|------------------|-------------|
| `Y` | matches input | `X` rounded to the nearest integer (as a float), with ties going to even. Shape and precision match the input. |
5. Examples
-------------------------------------------------------------------------------
(a) Scalar value
```mech:ex1
y := math/roundeven(3.7)
```
(b) Negative input
```mech:ex2
y := math/roundeven(-2.3)
```
(c) Halfway cases (tie to even)
```mech:ex3
y := math/roundeven(2.5)
y := math/roundeven(3.5)
y := math/roundeven(-2.5)
y := math/roundeven(-3.5)
```
(d) Vector input
```mech:ex4
x := [1.2, 2.5, -3.7, -4.5]
y := math/roundeven(x)
```
6. Details
-------------------------------------------------------------------------------
- **Definition:** `roundeven(x)` returns the nearest integer to `x`. For halfway
cases (`n + 0.5`), the result is the nearest **even** integer.
- **Domain:** All real values are valid inputs.
- **Special cases:**
- `roundeven(±∞) = ±∞`
- `roundeven(NaN) = NaN`
- **Shapes & types:** Scalars map to scalars; vectors/matrices are computed
elementwise with the same shape.
7. Notes for Implementers
-------------------------------------------------------------------------------
Backed by Rust/libm `roundeven` (f64) and `roundevenf` (f32). Implementations
dispatch across scalar, vector, and matrix variants. Ensures IEEE-754 compliance
for "round half to even".
8. See also
-------------------------------------------------------------------------------
`math/round`, `math/rint`, `math/floor`, `math/ceil`, `math/trunc`