embedded-vector 0.2.1

2D, 3D, and 4D f32 vectors for no_std embedded systems
Documentation
# embedded-vector

`f32` 2D, 3D, and 4D vectors for `no_std` embedded systems.

[![Crates.io](https://img.shields.io/crates/v/embedded-vector)](https://crates.io/crates/embedded-vector)
[![License: GPL-2.0-or-later](https://img.shields.io/badge/license-GPL--2.0--or--later-blue)](LICENSE)
[![no_std](https://img.shields.io/badge/no__std-✓-green)]()

---

## Features

- **`no_std`** — no dependency on the standard library; suitable for bare-metal targets
- **No `unsafe`** — `#![forbid(unsafe_code)]`
- **No allocation** — no heap or `alloc` required
- **Embedded square root** — provided by [`embedded-f32-sqrt`]https://crates.io/crates/embedded-f32-sqrt (Newton–Raphson)
- **Explicit errors** — fallible operations return `Result` instead of panicking
- **Numerical robustness** — `norm`, `normalize`, `distance`, and `project_onto` handle very large (`1e30`) and very small (`1e-30`) components without intermediate overflow or underflow

## Installation

```toml
[dependencies]
embedded-vector = "0.2.1"
```

## Quick start

```rust
use embedded_vector::{Vec2, Vec3, Vec4};

let a = Vec3::new(1.0, 2.0, 3.0);
let b = Vec3::new(4.0, 5.0, 6.0);

let c = a + b;                          // Vec3 { x: 5, y: 7, z: 9 }
let d = a.dot(&b);                      // 32.0
let e = a.cross(&b);                    // Vec3 { x: -3, y: 6, z: -3 }
let f = 2.0 * a;                        // Scalar multiplication works on either side

let n = a.norm().unwrap();              // sqrt(14) ≈ 3.742
let u = a.normalize().unwrap();         // Unit vector
let z = Vec3::ZERO.normalize_or_zero(); // No error handling required

let m = a.lerp(&b, 0.5);

// Projection, rejection, and reflection (Vec2, Vec3, and Vec4)
let p = a.project_onto(&Vec3::X).unwrap();
let r = a.reject_from(&Vec3::X).unwrap();
let v = Vec2::new(1.0, -1.0).reflect(&Vec2::Y).unwrap(); // [1, 1]

// Homogeneous coordinates
let point = Vec4::from_vec3(a, 1.0);    // Point
let direction = a.extend(0.0);          // Direction
let xyz = point.perspective_divide().unwrap(); // (x/w, y/w, z/w)
```

## API

### Shared by `Vec2`, `Vec3`, and `Vec4`

| Method / constant | Description |
|---|---|
| `new(..)`, `ZERO`, `ONE`, `Default` | Construction |
| `as_array()`, `from_array(..)`, `From<[f32; N]>` | Array conversion |
| `dot(&rhs)` | Dot product |
| `norm_sq()` | Squared norm (infallible; may overflow or underflow) |
| `norm()` | Euclidean norm → `Result<f32, VecError>` (robust) |
| `normalize()` | Unit vector → `Result<Self, VecError>` |
| `normalize_or_zero()` | Unit vector, or `ZERO` if normalization fails |
| `distance(&rhs)` / `distance_sq(&rhs)` | Euclidean distance / squared distance |
| `lerp(&rhs, t)` | Linear interpolation |
| `hadamard(&rhs)` | Component-wise product |
| `min`, `max`, `abs` | Component-wise operations |
| `project_onto`, `reject_from`, `reflect` | Projection, perpendicular component, reflection |
| `checked_div(s)` | Scalar division without silently producing `inf` or `NaN` |
| `is_finite()`, `is_approx_eq(&rhs, eps)` | Validation / approximate comparison |

### Type-specific API

| Type | Method / constant | Description |
|---|---|---|
| `Vec2` | `X`, `Y` | Unit axes |
| `Vec2` | `cross(&rhs) -> f32` | 2D cross product (Z component) |
| `Vec2` | `perp()` | 90° counterclockwise rotation: `[-y, x]` |
| `Vec2` | `extend(z)` | Convert to `Vec3` |
| `Vec3` | `X`, `Y`, `Z` | Unit axes |
| `Vec3` | `cross(&rhs)` | Cross product (right-hand rule) |
| `Vec3` | `triple(&b, &c)` | Scalar triple product `self · (b × c)` |
| `Vec3` | `truncate()`, `extend(w)` | Convert to `Vec2` / `Vec4` |
| `Vec4` | `X`, `Y`, `Z`, `W` | Unit axes |
| `Vec4` | `from_vec3(v, w)`, `xyz()` | Convert from / to `Vec3` |
| `Vec4` | `perspective_divide()` | `(x/w, y/w, z/w)` → `Result<Vec3, VecError>` |

## Errors

```rust
#[non_exhaustive]
pub enum VecError {
    ZeroNorm,        // Zero vector: normalization / projection is undefined
    NonFiniteValue,  // NaN, infinity, or a result outside the f32 range
    DivisionByZero,  // Zero scalar divisor or zero homogeneous coordinate w
}
```

No operation panics. The zero vector has a norm of `Ok(0.0)`; only `normalize`
returns `ZeroNorm` for it.

## Operators and traits

All vector types implement `Add`, `Sub`, `Mul<f32>`, `Div<f32>`, `Neg`,
`AddAssign`, `SubAssign`, `MulAssign<f32>`, `DivAssign<f32>`, `f32 * Vec`,
`iter::Sum`, `Default`, and `From<[f32; N]>` / `Into<[f32; N]>`.

> `Div<f32>` follows IEEE 754 semantics (division by `0.0` produces `inf` or
> `NaN`). Use `checked_div` when the divisor is not guaranteed to be nonzero.

## Why `Vec4` for embedded systems?

`Vec4` is useful for:

- **Homogeneous coordinates** — multiplication by a 4×4 matrix (affine transforms and perspective projection), where points (`w = 1`) must be distinguished from directions (`w = 0`). `perspective_divide` converts back to 3D.
- **RGBA colors** — compact representation of four `f32` channels.
- **Quaternions** — storing a rotation as `(x, y, z, w)` without a dedicated quaternion type.

If your project does not use any of these, `Vec4` adds no overhead to the final
binary (Rust only compiles the code that is used).

## Tests

```sh
cargo test
```

Integration tests are in `tests/`: `common_api`, `operators`, `projection`,
`robustness`, `vec2`, `vec3`, and `vec4`.

## License

GPL-2.0-or-later — see [LICENSE](LICENSE).

Copyright © 2026 Jorge Andre Castro.