> Aztec.nr API reference, v6.0.0 (mainnet and testnet). Index: https://docs.aztec.network/aztec-nr-api/mainnet/llms.txt

# Struct BoundedVec

Module: `std::collections::bounded_vec`

```rust
pub struct BoundedVec<T, let MaxLen: u32>
{ /* private fields */ }
```

A `BoundedVec<T, MaxLen>` is a growable storage similar to a built-in vector except that it is bounded with a maximum possible length. `BoundedVec` is also not subject to the same restrictions vectors are (notably, nested vectors are disallowed).

Since a BoundedVec is backed by a normal array under the hood, growing the BoundedVec by pushing an additional element is also more efficient - the length only needs to be increased by one.

For these reasons `BoundedVec<T, N>` should generally be preferred over vectors when there is a reasonable maximum bound that can be placed on the vector.

Example:

```rust
let mut vector: BoundedVec<Field, 10> = BoundedVec::new();
for i in 0..5 {
    vector.push(i);
}
assert(vector.len() == 5);
assert(vector.max_len() == 10);
```

## Implementations

```rust
impl<T, let MaxLen: u32> BoundedVec<T, MaxLen>
```

```rust
pub fn new() -> Self
```

Creates a new, empty vector of length zero.

Since this container is backed by an array internally, it still needs an initial value to give each element. To resolve this, each element is zeroed internally. This value is guaranteed to be inaccessible unless `get_unchecked` is used.

Example:

```rust
let empty_vector: BoundedVec<Field, 10> = BoundedVec::new();
assert(empty_vector.len() == 0);
```

Note that whenever calling `new` the maximum length of the vector should generally be specified via a type signature:

```rust
fn good() -> BoundedVec<Field, 10> {
    // Ok! MaxLen is specified with a type annotation
    let v1: BoundedVec<Field, 3> = BoundedVec::new();
    let v2 = BoundedVec::new();

    // Ok! MaxLen is known from the type of `good`'s return value
    v2
}

fn bad() {
    // Error: Type annotation needed
    // The compiler can't infer `MaxLen` from the following code:
    let mut v3 = BoundedVec::new();
    v3.push(5);
}
```

```rust
pub fn get(&self, index: u32) -> T
```

Retrieves an element from the vector at the given index, starting from zero.

If the given index is equal to or greater than the length of the vector, this will issue a constraint failure.

Example:

```rust
fn foo<let N: u32>(v: BoundedVec<u32, N>) {
    let first = v.get(0);
    let last = v.get(v.len() - 1);
    assert(first != last);
}
```

```rust
pub fn get_unchecked(&self, index: u32) -> T
```

Retrieves an element from the vector at the given index, starting from zero, without performing a bounds check.

Since this function does not perform a bounds check on length before accessing the element, it is unsafe! Use at your own risk!

Example:

```rust
fn sum_of_first_three<let N: u32>(v: BoundedVec<u32, N>) -> u32 {
    // Always ensure the length is larger than the largest
    // index passed to get_unchecked
    assert(v.len() > 2);
    let first = v.get_unchecked(0);
    let second = v.get_unchecked(1);
    let third = v.get_unchecked(2);
    first + second + third
}
```

```rust
pub fn set(&mut self, index: u32, value: T)
```

Writes an element to the vector at the given index, starting from zero.

If the given index is equal to or greater than the length of the vector, this will issue a constraint failure.

Example:

```rust
fn foo<let N: u32>(v: BoundedVec<u32, N>) {
    let first = v.get(0);
    assert(first != 42);
    v.set(0, 42);
    let new_first = v.get(0);
    assert(new_first == 42);
}
```

```rust
pub fn set_unchecked(&mut self, index: u32, value: T)
```

Writes an element to the vector at the given index, starting from zero, without performing a bounds check.

Since this function does not perform a bounds check on length before accessing the element, it is unsafe! Use at your own risk!

Example:

```rust
fn set_unchecked_example() {
    let mut vec: BoundedVec<u32, 5> = BoundedVec::new();
    vec.extend_from_array([1, 2]);

    // Here we're safely writing within the valid range of `vec`
    // `vec` now has the value [42, 2]
    vec.set_unchecked(0, 42);

    // We can then safely read this value back out of `vec`.
    // Notice that we use the checked version of `get` which would prevent reading unsafe values.
    assert_eq(vec.get(0), 42);

    // We've now written past the end of `vec`.
    // As this index is still within the maximum potential length of `v`,
    // it won't cause a constraint failure.
    vec.set_unchecked(2, 42);
    println(vec);

    // This will write past the end of the maximum potential length of `vec`,
    // it will then trigger a constraint failure.
    vec.set_unchecked(5, 42);
    println(vec);
}
```

```rust
pub fn push(&mut self, elem: T)
```

Pushes an element to the end of the vector. This increases the length of the vector by one.

Panics if the new length of the vector will be greater than the max length.

Example:

```rust
let mut v: BoundedVec<Field, 2> = BoundedVec::new();

v.push(1);
v.push(2);

// Panics with failed assertion "push out of bounds"
v.push(3);
```

```rust
pub fn len(&self) -> u32
```

Returns the current length of this vector

Example:

```rust
let mut v: BoundedVec<Field, 4> = BoundedVec::new();
assert(v.len() == 0);

v.push(100);
assert(v.len() == 1);

v.push(200);
v.push(300);
v.push(400);
assert(v.len() == 4);

let _ = v.pop();
let _ = v.pop();
assert(v.len() == 2);
```

```rust
pub fn set_len(&mut self, len: u32)
```

Sets the length of the vector to any value between `0` and `MaxLen`.

Increasing the length exposes elements that were written past the current length (e.g. with `set_unchecked`); decreasing it discards trailing elements. Note that this does not zero out any element of the backing storage, so elements beyond the new length remain readable through `storage`.

Example:

```rust
let mut v: BoundedVec<Field, 10> = BoundedVec::from([1, 2, 3, 4, 5]);

assert(v.len() == 5);
v.set_unchecked(5, 6);
v.set_unchecked(6, 7);
v.set_unchecked(7, 8);
v.set_len(8);
assert(v.len() == 8);

// The length can also be reduced.
v.set_len(2);
assert(v.len() == 2);
```

```rust
pub fn truncate(&mut self, len: u32)
```

Shortens the vector to `len`, keeping the first `len` elements.

If `len` is greater than or equal to the current length, the vector is left unchanged. Regardless of the current length, after this call the vector is guaranteed to hold no more than `len` elements.

Example:

```rust
let mut v: BoundedVec<Field, 10> = BoundedVec::from([1, 2, 3, 4, 5]);

v.truncate(3);
assert(v.len() == 3);

// Truncating to a length greater than the current length is a no-op.
v.truncate(8);
assert(v.len() == 3);
```

```rust
pub fn max_len(_self: &Self) -> u32
```

Returns the maximum length of this vector. This is always equal to the `MaxLen` parameter this vector was initialized with.

Example:

```rust
let mut v: BoundedVec<Field, 5> = BoundedVec::new();

assert(v.max_len() == 5);
v.push(10);
assert(v.max_len() == 5);
```

```rust
pub fn storage(self) -> [T; MaxLen]
```

Returns the internal array within this vector.

Since arrays in Noir are immutable, mutating the returned storage array will not mutate the storage held internally by this vector.

Note that uninitialized elements may be zeroed out!

Example:

```rust
let mut v: BoundedVec<Field, 5> = BoundedVec::new();

assert(v.storage() == [0, 0, 0, 0, 0]);

v.push(57);
assert(v.storage() == [57, 0, 0, 0, 0]);
```

```rust
pub fn extend_from_array<let Len: u32>(&mut self, array: [T; Len])
```

Pushes each element from the given array to this vector.

Panics if pushing each element would cause the length of this vector to exceed the maximum length.

Example:

```rust
let mut vec: BoundedVec<Field, 3> = BoundedVec::new();
vec.extend_from_array([2, 4]);

assert(vec.len == 2);
assert(vec.get(0) == 2);
assert(vec.get(1) == 4);
```

```rust
pub fn extend_from_vector(&mut self, vector: [T])
```

Pushes each element from the given vector to this vector.

Panics if pushing each element would cause the length of this vector to exceed the maximum length.

Example:

```rust
let mut vec: BoundedVec<Field, 3> = BoundedVec::new();
vec.extend_from_vector([2, 4].as_vector());

assert(vec.len == 2);
assert(vec.get(0) == 2);
assert(vec.get(1) == 4);
```

```rust
pub fn extend_from_bounded_vec<let Len: u32>(&mut self, vec: BoundedVec<T, Len>)
```

Pushes each element from the other vector to this vector. The length of the other vector is left unchanged.

Panics if pushing each element would cause the length of this vector to exceed the maximum length.

```rust
let mut v1: BoundedVec<Field, 5> = BoundedVec::new();
let mut v2: BoundedVec<Field, 7> = BoundedVec::new();

v2.extend_from_array([1, 2, 3]);
v1.extend_from_bounded_vec(v2);

assert(v1.storage() == [1, 2, 3, 0, 0]);
assert(v2.storage() == [1, 2, 3, 0, 0, 0, 0]);
```

```rust
pub fn from_array<let Len: u32>(array: [T; Len]) -> Self
```

Creates a new vector, populating it with values derived from an array input. The maximum length of the vector is determined based on the type signature.

Example:

```rust
let bounded_vec: BoundedVec<Field, 10> = BoundedVec::from_array([1, 2, 3])
```

```rust
pub fn pop(&mut self) -> T
```

Pops the element at the end of the vector. This will decrease the length of the vector by one.

Panics if the vector is empty.

Example:

```rust
let mut v: BoundedVec<Field, 2> = BoundedVec::new();
v.push(1);
v.push(2);

let two = v.pop();
let one = v.pop();

assert(two == 2);
assert(one == 1);

// error: cannot pop from an empty vector
let _ = v.pop();
```

```rust
pub fn any<Env>(self, predicate: fn[Env](T) -> bool) -> bool
```

Returns true if the given predicate returns true for any element in this vector.

Example:

```rust
let mut v: BoundedVec<u32, 3> = BoundedVec::new();
v.extend_from_array([2, 4, 6]);

let all_even = !v.any(|elem: u32| elem % 2 != 0);
assert(all_even);
```

```rust
pub fn map<U, Env>(&self, f: fn[Env](T) -> U) -> BoundedVec<U, MaxLen>
```

Creates a new vector of equal size by calling a closure on each element in this vector.

Example:

```rust
let vec: BoundedVec<u32, 4> = BoundedVec::from_array([1, 2, 3, 4]);
let result = vec.map(|value| value * 2);

let expected = BoundedVec::from_array([2, 4, 6, 8]);
assert_eq(result, expected);
```

```rust
pub fn mapi<U, Env>(&self, f: fn[Env](u32, T) -> U) -> BoundedVec<U, MaxLen>
```

Creates a new vector of equal size by calling a closure on each element in this vector, along with its index.

Example:

```rust
let vec: BoundedVec<u32, 4> = BoundedVec::from_array([1, 2, 3, 4]);
let result = vec.mapi(|i, value| i + value * 2);

let expected = BoundedVec::from_array([2, 5, 8, 11]);
assert_eq(result, expected);
```

```rust
pub fn for_each<Env>(&self, f: fn[Env](T))
```

Calls a closure on each element in this vector.

Example:

```rust
let vec: BoundedVec<u32, 4> = BoundedVec::from_array([1, 2, 3, 4]);
let mut result = BoundedVec::<u32, 4>::new();
vec.for_each(|value| result.push(value * 2));

let expected = BoundedVec::from_array([2, 4, 6, 8]);
assert_eq(result, expected);
```

```rust
pub fn for_eachi<Env>(&self, f: fn[Env](u32, T))
```

Calls a closure on each element in this vector, along with its index.

Example:

```rust
let vec: BoundedVec<u32, 4> = BoundedVec::from_array([1, 2, 3, 4]);
let mut result = BoundedVec::<u32, 4>::new();
vec.for_eachi(|i, value| result.push(i + value * 2));

let expected = BoundedVec::from_array([2, 5, 8, 11]);
assert_eq(result, expected);
```

```rust
pub fn from_parts(array: [T; MaxLen], len: u32) -> Self
```

Creates a new BoundedVec from the given array and length. The given length must be less than or equal to the length of the array.

Example:

```rust
let vec: BoundedVec<u32, 4> = BoundedVec::from_parts([1, 2, 3, 0], 3);
assert_eq(vec.len(), 3);
```

## Trait implementations

```rust
impl<let MaxLen: u32, T> Eq for BoundedVec<T, MaxLen>
where
    T: Eq
```

```rust
pub fn eq(self, other: Self) -> bool
```

```rust
impl<let Len: u32, let MaxLen: u32, T> From<[T; Len]> for BoundedVec<T, MaxLen>
```

```rust
pub fn from(array: [T; Len]) -> Self
```