embedded-vector 0.2.1

2D, 3D, and 4D f32 vectors for no_std embedded systems
Documentation
  • Coverage
  • 100%
    105 out of 105 items documented1 out of 78 items with examples
  • Size
  • Source code size: 54.2 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 394.2 kB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 1s Average build duration of successful builds.
  • all releases: 4s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • jorgeandrecastro/embedded-vector
    0 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • jorgeandrecastro

embedded-vector

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

Crates.io License: GPL-2.0-or-later no_std


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 (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

[dependencies]
embedded-vector = "0.2.1"

Quick start

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

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

cargo test

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

License

GPL-2.0-or-later — see LICENSE.

Copyright © 2026 Jorge Andre Castro.