Const Generics

19 min read

Const generics let a type or function be generic over a constant value — most commonly an array length — rather than only over a type. They are how [T; N] works, how a fixed-capacity buffer can be a distinct type from a different-capacity one, and how Rust can verify dimensions like “a 2x3 matrix times a 3x2 matrix” at compile time with zero runtime cost.

Quick Overview

A normal generic parameter stands in for a type (Vec<T>). A const generic parameter stands in for a value of some primitive type, written const N: usize. The classic case is the array type [T; N]: the length N is part of the type, so [u8; 4] and [u8; 8] are genuinely different types.

For a TypeScript/JavaScript developer the nearest analogy is a fixed-length tuple type such as readonly [number, number, number]. The crucial difference: TypeScript’s tuple length is a compile-time-only annotation that is fully erased — at runtime it is just a number[], and a length mismatch passes silently. Rust’s const generics are real, monomorphized types that the compiler turns into distinct, separately-optimized machine code, so the length is enforced and exploitable at runtime too.

TypeScript/JavaScript Example

TypeScript can describe a fixed-length vector with a tuple type and even catch a length mismatch during type-checking:

1
// A 3-element vector, described with a fixed-length tuple type.
2
type Vec3 = readonly [number, number, number];
3

4
function dot(a: Vec3, b: Vec3): number {
5
  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
6
}
7

8
const a: Vec3 = [1, 2, 3];
9
const b: Vec3 = [4, 5, 6];
10
console.log("dot =", dot(a, b)); // dot = 32
11

12
// Passing the wrong length is a *compile-time* type error:
13
dot(a, [4, 5]);
14
//     ~~~~~~ Argument of type '[number, number]' is not assignable
15
//            to parameter of type 'Vec3'. Source has 2 element(s)
16
//            but target requires 3.

That tsc --strict error is real. But the length lives only in the type system. There is no Vec3 value at runtime — it is an ordinary JavaScript array — and a generic helper that takes number[] will happily run on the wrong length:

1
// Plain JavaScript: the length annotation is gone. Nothing stops a mismatch.
2
function dot(a, b) {
3
  return a.reduce((sum, x, i) => sum + x * b[i], 0);
4
}
5

6
console.log(dot([1, 2, 3], [4, 5, 6])); // 32
7
console.log(dot([1, 2, 3], [4, 5]));     // NaN  — silently wrong

So in TypeScript the length is a hint to the checker, not a property of the runtime value. And tuple types do not let you write code that is generic over an arbitrary fixed length N while still tracking that length — you would end up with a separate Vec2, Vec3, Vec4, or fall back to number[] and lose the guarantee entirely.

Rust Equivalent

In Rust the length is a first-class generic parameter. One definition covers every length, and the length is part of the type at runtime:

1
use std::ops::{Add, Index, IndexMut};
2

3
// A fixed-size mathematical vector, generic over its length N.
4
#[derive(Debug, Clone, Copy, PartialEq)]
5
struct Vector<const N: usize> {
6
    data: [f64; N],
7
}
8

9
impl<const N: usize> Vector<N> {
10
    fn from_array(data: [f64; N]) -> Self {
11
        Vector { data }
12
    }
13

14
    fn zero() -> Self {
15
        Vector { data: [0.0; N] }
16
    }
17

18
    fn dot(&self, other: &Vector<N>) -> f64 {
19
        let mut sum = 0.0;
20
        for i in 0..N {
21
            sum += self.data[i] * other.data[i];
22
        }
23
        sum
24
    }
25

26
    fn len(&self) -> usize {
27
        N
28
    }
29
}
30

31
// Adding two vectors is legal only when their lengths match: the same N.
32
impl<const N: usize> Add for Vector<N> {
33
    type Output = Vector<N>;
34
    fn add(self, rhs: Vector<N>) -> Vector<N> {
35
        let mut out = [0.0; N];
36
        for i in 0..N {
37
            out[i] = self.data[i] + rhs.data[i];
38
        }
39
        Vector { data: out }
40
    }
41
}
42

43
impl<const N: usize> Index<usize> for Vector<N> {
44
    type Output = f64;
45
    fn index(&self, i: usize) -> &f64 {
46
        &self.data[i]
47
    }
48
}
49

50
impl<const N: usize> IndexMut<usize> for Vector<N> {
51
    fn index_mut(&mut self, i: usize) -> &mut f64 {
52
        &mut self.data[i]
53
    }
54
}
55

56
fn main() {
57
    let a = Vector::from_array([1.0, 2.0, 3.0]); // Vector<3>
58
    let b = Vector::from_array([4.0, 5.0, 6.0]); // Vector<3>
59

60
    let sum = a + b;
61
    println!("a + b   = {:?}", sum.data);
62
    println!("a . b   = {}", a.dot(&b));
63
    println!("len(a)  = {}", a.len());
64

65
    let z = Vector::<4>::zero(); // explicitly Vector<4>
66
    println!("zero(4) = {:?}", z.data);
67

68
    let c = Vector::from_array([7.0, 8.0]); // Vector<2>
69
    println!("c[1]    = {}", c[1]);
70
}

Real output:

1
a + b   = [5.0, 7.0, 9.0]
2
a . b   = 32
3
len(a)  = 3
4
zero(4) = [0.0, 0.0, 0.0, 0.0]
5
c[1]    = 8

One Vector<const N: usize> definition serves every length, the length is recoverable at runtime (a.len() returns 3), and — as the next sections show — a length mismatch is a compile error, not a silent NaN.

Detailed Explanation

Declaring a const generic parameter

1
struct Vector<const N: usize> {
2
    data: [f64; N],
3
}

The syntax const N: usize declares a generic parameter whose value is a usize constant. It sits in the same <...> angle-bracket list as type parameters and lifetimes. The ordering rule is: lifetimes first, then type and const parameters (which may be interleaved). Inside the body, N is usable anywhere a constant of that type is needed — most importantly as an array length [f64; N], but also in expressions like 0..N.

Note: The type after const (here usize) is the type of the constant value, not a type parameter. The only types currently allowed for a const generic parameter are the integer types, bool, and char — confirmed by the compiler error in the next section.

Supplying the value

There are three ways N gets a concrete value:

Inference from an argument. Vector::from_array([1.0, 2.0, 3.0]) passes a [f64; 3], so the compiler infers N = 3.
Explicit turbofish. Vector::<4>::zero() names the value directly, just like Vec::<i32>::new() names a type. Const generic arguments go in the same ::<...> list.
From a type annotation. let z: Vector<4> = Vector::zero(); lets the binding’s declared type drive N.

Const generic arguments are written as a value (4, true, '.') or a standalone const parameter (N). A more complex expression like N + 1 is not allowed in argument position on stable — see Key Differences.

Monomorphization makes each length a real type

Rust monomorphizes generics: the compiler stamps out a separate, fully-specialized copy of the code for each concrete set of generic arguments actually used. Vector<3> and Vector<2> compile to two distinct types with two distinct add functions, each with N substituted as a literal. This is the same machinery described in Generic Functions, extended from types to values — and it is the opposite of TypeScript’s type erasure, where Vec3 vanishes before the code runs.

Because N is a compile-time literal inside each monomorphized copy, loops like for i in 0..N have a known trip count, arrays are sized exactly, and the optimizer can unroll or vectorize freely. There is no length field stored at runtime and no heap allocation — Vector<3> is exactly three f64s, 24 bytes, on the stack.

`impl<const N: usize>` blocks

1
impl<const N: usize> Vector<N> { /* ... */ }

To write methods that work for every N, the impl block itself must introduce the const parameter, exactly as it would introduce a type parameter impl<T> Wrapper<T>. You can also write an impl for one specific length — impl Vector<3> { ... } — to add methods that only make sense at that size (for example, a cross product that exists only for 3-vectors).

The standard library is built on this

The array type [T; N] is the most pervasive const-generic type in Rust, and the standard library exposes const-generic combinators over it:

1
fn main() {
2
    // `<[T; N]>::map` keeps the length in the type: [i32; 4] -> [i32; 4].
3
    let doubled = [1, 2, 3, 4].map(|x| x * 2);
4
    println!("map double = {:?}", doubled);
5

6
    // `std::array::from_fn` builds an array, inferring N from the target type.
7
    let squares: [usize; 5] = std::array::from_fn(|i| i * i);
8
    println!("squares    = {:?}", squares);
9

10
    // Arrays own their elements and yield them by value via IntoIterator
11
    // (stable since the 2021 edition).
12
    let odd_sum: i32 = [1, 2, 3].into_iter().filter(|&x| x % 2 == 1).sum();
13
    println!("odd sum    = {}", odd_sum);
14
}

Real output:

1
map double = [2, 4, 6, 8]
2
squares    = [0, 1, 4, 9, 16]
3
odd sum    = 4

std::array::from_fn is the idiomatic way to initialize a [T; N] element-by-element when T is not Copy (you cannot write [value; N] unless value: Copy).

Key Differences

Aspect	TypeScript fixed-length tuple	Rust const generics
What it parameterizes over	A literal tuple shape (`[number, number, number]`)	Any constant `N` of an integer / `bool` / `char` type
Generic over an arbitrary length	No — you write `Vec2`, `Vec3`, … separately	Yes — one `Vector<const N: usize>` covers all
Runtime representation	Erased; just a JS array	A real, distinct, monomorphized type per `N`
Length recoverable at runtime	Only via `arr.length` (no type involvement)	`N` is a compile-time constant usable in code
Mismatch detection	Compile-time only; silent at runtime	Compile-time and structurally distinct types
Cost	Zero (erased)	Zero at runtime; larger binary (monomorphization)
Allowed parameter “types”	Any tuple of types	Integers, `bool`, `char` only (stable)

Stable vs. nightly: the const-generics roadmap

What shipped in stable Rust (often called min_const_generics) is deliberately conservative. The rules you can rely on today:

Const generic parameters may be integers, bool, or char.
A const generic argument must be either a literal/const value, or a standalone const parameter (just N, not N + 1 or N * 2).

Computing with const parameters — e.g. returning [T; N + 1], or splitting [T; N] into [[T; CHUNK]; N / CHUNK] — needs the unstable generic_const_exprs feature and a nightly compiler. The standalone-argument restriction is exactly what produces the error in the next section. (For why some powerful type-system features stay unstable, see the sibling note on Specialization.)

Common Pitfalls

Pitfall 1: Trying to do arithmetic on a const parameter

A natural first instinct — return an array one element longer — does not compile on stable:

1
// does not compile: const arithmetic in array sizes is unstable.
2
fn push_one<const N: usize>(arr: [i32; N], x: i32) -> [i32; N + 1] {
3
    let mut out = [0; N + 1];
4
    out[..N].copy_from_slice(&arr);
5
    out[N] = x;
6
    out
7
}

The real compiler emits the same error for each use of N + 1 (here, both the return type and the [0; N + 1] array); the representative one is:

1
error: generic parameters may not be used in const operations
2
 --> src/main.rs:2:61
3
  |
4
2 | fn push_one<const N: usize>(arr: [i32; N], x: i32) -> [i32; N + 1] {
5
  |                                                             ^ cannot perform const operation using `N`
6
  |
7
  = help: const parameters may only be used as standalone arguments here, i.e. `N`

Tip: When you truly need a derived length, the stable workarounds are: return a Vec<T> (heap, dynamic length), take/return slices &[T], or — if N is small and known — hard-code the specific sizes. Reaching for nightly generic_const_exprs should be a last resort because the feature is incomplete and its rules still change.

Pitfall 2: Using a forbidden parameter type

Integers, bool, and char work; floating-point and arbitrary structs do not:

1
struct Flag<const ON: bool>;             // ok
2
struct Grid<const W: usize, const FILL: char>; // ok
3
struct Scaled<const FACTOR: f64>;        // does not compile

The real error:

1
error: `f64` is forbidden as the type of a const generic parameter
2
 --> src/main.rs:6:29
3
  |
4
6 | struct Scaled<const FACTOR: f64>;
5
  |                             ^^^
6
  |
7
  = note: the only supported types are integers, `bool`, and `char`

Floats are disallowed because const generics rely on structural equality of values to decide when two types are the same, and IEEE-754 equality (NaN != NaN, 0.0 == -0.0) does not give a clean, total notion of equality.

Pitfall 3: The compiler cannot infer `N`

If nothing at the call site pins down N, you get an inference error — not a default of zero:

1
fn make<const N: usize>() -> [u8; N] {
2
    [0; N]
3
}
4

5
fn main() {
6
    let arr = make(); // does not compile: N is unknown
7
    println!("{:?}", arr);
8
}

The real error tells you exactly how to fix it (the compiler reports E0284 once per unconstrained use, so you may also see a follow-on copy pointing at the println!; the key one is the first):

1
error[E0284]: type annotations needed for `[u8; _]`
2
 --> src/main.rs:7:9
3
  |
4
7 |     let arr = make();
5
  |         ^^^   ------ type must be known at this point
6
  |
7
note: required by a const generic parameter in `make`
8
 --> src/main.rs:1:9
9
  |
10
1 | fn make<const N: usize>() -> [u8; N] {
11
  |         ^^^^^^^^^^^^^^ required by this const generic parameter in `make`
12
help: consider giving `arr` an explicit type, where the value of const parameter `N` is specified
13
  |
14
7 |     let arr: [_; N] = make();
15
  |            ++++++++

The fix is to annotate (let arr: [u8; 4] = make();) or turbofish (make::<4>()).

Pitfall 4: Expecting different lengths to be interchangeable

Because each N is a distinct type, mixing them is a type error — which is the whole point, but it surprises developers coming from number[]:

1
let a = Vector { data: [1.0, 2.0, 3.0] }; // Vector<3>
2
let b = Vector { data: [4.0, 5.0] };      // Vector<2>
3
let _ = a + b; // does not compile

The real error:

1
error[E0308]: mismatched types
2
  --> src/main.rs:20:17
3
   |
4
20 |     let _ = a + b; // mismatched lengths
5
   |                 ^ expected `3`, found `2`
6
   |
7
   = note: expected struct `Vector<3>`
8
              found struct `Vector<2>`

Where TypeScript catches this only during type-checking (and plain JavaScript not at all, producing NaN), Rust makes the two lengths structurally different types, so the guarantee holds all the way through to the running binary.

Best Practices

Prefer [T; N] over Vec<T> only when the size is genuinely fixed and known at compile time. Const generics give you stack allocation, no length field, and aggressive optimization — but they also multiply monomorphized code. If lengths vary at runtime, a Vec<T> or slice is the right tool. See Section 21: Performance for the binary-size and inlining trade-offs of monomorphization.
Encode invariants in the type when a mismatch would be a real bug. Matrix and vector dimensions, fixed protocol-frame sizes, and ring-buffer capacities are excellent candidates: a wrong size becomes a compile error instead of a runtime panic or silent corruption.
Use std::array::from_fn to initialize non-Copy arrays. [None; N] fails when the element is not Copy; std::array::from_fn(|_| None) works for any N.

Give const parameters defaults when one size dominates. struct Buffer<T, const N: usize = 32> lets callers write Buffer<u8> for the common case and Buffer<u8, 8> to override:

1
struct Buffer<T, const N: usize = 32> {
2
    data: [T; N],
3
}
4

5
impl<T: Default + Copy, const N: usize> Buffer<T, N> {
6
    fn new() -> Self {
7
        Buffer { data: [T::default(); N] }
8
    }
9
}
10

11
fn main() {
12
    let a: Buffer<u8> = Buffer::new();    // default N = 32
13
    let b: Buffer<u8, 8> = Buffer::new(); // override
14
    println!("{} {}", a.data.len(), b.data.len()); // 32 8
15
}

Reach for ecosystem crates instead of hand-rolling. Const generics power heapless (fixed-capacity, allocation-free Vec/String/maps for embedded and real-time code) and the linear-algebra crate nalgebra (statically-sized Matrix<R, C>). Don’t reinvent a fixed-capacity collection if one of those fits.

1
# cargo add heapless
2
[dependencies]
3
heapless = "0.9.3"

1
use heapless::Vec;
2

3
fn main() {
4
    // heapless::Vec<T, const N: usize>: a fixed-capacity, no-heap vector.
5
    let mut v: Vec<u8, 4> = Vec::new();
6
    v.push(1).unwrap();
7
    v.push(2).unwrap();
8
    v.push(3).unwrap();
9
    v.push(4).unwrap();
10

11
    // Capacity is part of the type; the fifth push has nowhere to go.
12
    assert_eq!(v.push(5), Err(5));
13

14
    println!("len={} capacity={}", v.len(), v.capacity());
15
}

Real output:

1
len=4 capacity=4

Real-World Example

A statically-sized matrix where the type system enforces multiplication shapes. A 2x3 matrix can only multiply a 3xK matrix — the shared inner dimension 3 must match, and the result type 2xK is computed by the compiler. A shape mismatch never reaches runtime.

1
// An R x C matrix whose dimensions live in the type.
2
#[derive(Debug, Clone, Copy)]
3
struct Matrix<const R: usize, const C: usize> {
4
    rows: [[f64; C]; R],
5
}
6

7
impl<const R: usize, const C: usize> Matrix<R, C> {
8
    fn new(rows: [[f64; C]; R]) -> Self {
9
        Matrix { rows }
10
    }
11

12
    // (R x C) * (C x K) = (R x K). The shared dimension C is enforced by the
13
    // type system, so a shape mismatch is a compile error, never a panic.
14
    fn mul<const K: usize>(&self, other: &Matrix<C, K>) -> Matrix<R, K> {
15
        let mut out = [[0.0; K]; R];
16
        for i in 0..R {
17
            for j in 0..K {
18
                for k in 0..C {
19
                    out[i][j] += self.rows[i][k] * other.rows[k][j];
20
                }
21
            }
22
        }
23
        Matrix { rows: out }
24
    }
25
}
26

27
fn main() {
28
    let a: Matrix<2, 3> = Matrix::new([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]);
29
    let b: Matrix<3, 2> = Matrix::new([[7.0, 8.0], [9.0, 10.0], [11.0, 12.0]]);
30

31
    let c = a.mul(&b); // inferred as Matrix<2, 2>
32
    println!("{:?}", c.rows);
33
}

Real output:

1
[[58.0, 64.0], [139.0, 154.0]]

If you try to multiply incompatible shapes — say a Matrix<2, 3> by a Matrix<2, 4> — the compiler rejects it because the method requires the right-hand operand to be Matrix<C, K> where C = 3 (the full message also prints a note: method defined here pointing at mul, trimmed here for brevity):

1
error[E0308]: mismatched types
2
  --> src/main.rs:23:19
3
   |
4
23 |     let _ = a.mul(&b);
5
   |               --- ^^ expected `3`, found `2`
6
   |               |
7
   |               arguments to this method are incorrect
8
   |
9
   = note: expected reference `&Matrix<3, _>`
10
              found reference `&Matrix<2, 4>`

This is “make illegal states unrepresentable” applied to numeric code: dimension bugs that would be runtime exceptions in NumPy or a JavaScript math library become compile errors in Rust.

Exercises

Exercise 1: Identity matrix and trace

Difficulty: Beginner

Objective: Practice writing methods on a const-generic type and using N inside the body.

Instructions: Define struct Square<const N: usize> { cells: [[f64; N]; N] }. Implement Square::<N>::identity() that returns the N x N identity matrix (1.0 on the diagonal, 0.0 elsewhere), and a trace(&self) -> f64 method that sums the diagonal. Print trace of a 3x3 identity (it should be 3).

Solution

1
#[derive(Debug)]
2
struct Square<const N: usize> {
3
    cells: [[f64; N]; N],
4
}
5

6
impl<const N: usize> Square<N> {
7
    fn identity() -> Self {
8
        let mut cells = [[0.0; N]; N];
9
        for i in 0..N {
10
            cells[i][i] = 1.0;
11
        }
12
        Square { cells }
13
    }
14

15
    fn trace(&self) -> f64 {
16
        (0..N).map(|i| self.cells[i][i]).sum()
17
    }
18
}
19

20
fn main() {
21
    let id = Square::<3>::identity();
22
    println!("trace I3 = {}", id.trace()); // trace I3 = 3
23
}

Exercise 2: Fixed-capacity stack

Difficulty: Intermediate

Objective: Build a small allocation-free collection whose capacity is a type parameter, handling the “full” case without panicking.

Instructions: Implement struct Stack<T, const CAP: usize> backed by [Option<T>; CAP] and a length counter. Provide new(), push(&mut self, value: T) -> Result<(), T> (returning Err(value) when full), pop(&mut self) -> Option<T>, and is_full(&self) -> bool. Note that you must use std::array::from_fn(|_| None) to initialize the array, since T is not Copy.

Solution

1
struct Stack<T, const CAP: usize> {
2
    items: [Option<T>; CAP],
3
    len: usize,
4
}
5

6
impl<T, const CAP: usize> Stack<T, CAP> {
7
    fn new() -> Self {
8
        Stack { items: std::array::from_fn(|_| None), len: 0 }
9
    }
10

11
    fn push(&mut self, value: T) -> Result<(), T> {
12
        if self.len == CAP {
13
            return Err(value);
14
        }
15
        self.items[self.len] = Some(value);
16
        self.len += 1;
17
        Ok(())
18
    }
19

20
    fn pop(&mut self) -> Option<T> {
21
        if self.len == 0 {
22
            return None;
23
        }
24
        self.len -= 1;
25
        self.items[self.len].take()
26
    }
27

28
    fn is_full(&self) -> bool {
29
        self.len == CAP
30
    }
31
}
32

33
fn main() {
34
    let mut s: Stack<&str, 2> = Stack::new();
35
    assert!(s.push("a").is_ok());
36
    assert!(s.push("b").is_ok());
37
    assert_eq!(s.push("c"), Err("c")); // full
38
    assert!(s.is_full());
39
    println!("pop = {:?}", s.pop()); // pop = Some("b")
40
}

Exercise 3: Polynomial evaluation

Difficulty: Intermediate

Objective: Use a const generic to size a coefficient array and evaluate efficiently.

Instructions: Define struct Polynomial<const N: usize> { coeffs: [f64; N] } where coeffs[i] is the coefficient of x^i. Implement new(coeffs: [f64; N]) and eval(&self, x: f64) -> f64 using Horner’s method (fold from the highest-degree coefficient down). Verify that 2 + 3x + x^2 evaluated at x = 2 gives 12.

Solution

1
struct Polynomial<const N: usize> {
2
    coeffs: [f64; N], // coeffs[i] is the coefficient of x^i
3
}
4

5
impl<const N: usize> Polynomial<N> {
6
    fn new(coeffs: [f64; N]) -> Self {
7
        Polynomial { coeffs }
8
    }
9

10
    // Horner's method: ((... ) * x + c1) * x + c0.
11
    fn eval(&self, x: f64) -> f64 {
12
        self.coeffs.iter().rev().fold(0.0, |acc, &c| acc * x + c)
13
    }
14
}
15

16
fn main() {
17
    // 2 + 3x + x^2, at x = 2 -> 2 + 6 + 4 = 12
18
    let p = Polynomial::new([2.0, 3.0, 1.0]);
19
    println!("p(2) = {}", p.eval(2.0)); // p(2) = 12
20
}

Const Generics

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Declaring a const generic parameter

Supplying the value

Monomorphization makes each length a real type

impl<const N: usize> blocks

The standard library is built on this

Key Differences

Stable vs. nightly: the const-generics roadmap

Common Pitfalls

Pitfall 1: Trying to do arithmetic on a const parameter

Pitfall 2: Using a forbidden parameter type

Pitfall 3: The compiler cannot infer N

Pitfall 4: Expecting different lengths to be interchangeable

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: Identity matrix and trace

Exercise 2: Fixed-capacity stack

Exercise 3: Polynomial evaluation

`impl<const N: usize>` blocks

Pitfall 3: The compiler cannot infer `N`