Bounded Vectors
A BoundedVec<T, MaxLen> is a growable storage similar to a Vec<T> except that it
is bounded with a maximum possible length. Unlike Vec, BoundedVec is not implemented
via slices and thus is not subject to the same restrictions slices are (notably, nested
slices - and thus nested vectors as well - 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 Vec<T> when there
is a reasonable maximum bound that can be placed on the vector.
Example:
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);
Methods
new
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:
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 always be specified
via a type signature:
fn foo() -> 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 foo's return value
v2
}
fn bad() {
let mut v3 = BoundedVec::new();
// Not Ok! We don't know if v3's MaxLen is at least 1, and the compiler often infers 0 by default.
v3.push(5);
}
Source code: test_programs/noir_test_success/bounded_vec/src/main.nr#L11-L27
This defaulting of MaxLen (and numeric generics in general) to zero may change in future noir versions
but for now make sure to use type annotations when using bounded vectors. Otherwise, you will receive a constraint failure at runtime when the vec is pushed to.
get
pub fn get(mut self: Self, index: u64) -> 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:
fn foo<N>(v: BoundedVec<u32, N>) {
let first = v.get(0);
let last = v.get(v.len() - 1);
assert(first != last);
}
get_unchecked
pub fn get_unchecked(mut self: Self, index: u64) -> 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:
fn sum_of_first_three<N>(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
}
Source code: test_programs/noir_test_success/bounded_vec/src/main.nr#L54-L64
push
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:
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);
Source code: test_programs/noir_test_success/bounded_vec/src/main.nr#L68-L76
pop
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:
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();
Source code: test_programs/noir_test_success/bounded_vec/src/main.nr#L81-L93
len
pub fn len(self) -> u64 {
Returns the current length of this vector
Example:
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);
Source code: test_programs/noir_test_success/bounded_vec/src/main.nr#L98-L113
max_len
pub fn max_len(_self: BoundedVec<T, MaxLen>) -> u64 {
Returns the maximum length of this vector. This is always
equal to the MaxLen parameter this vector was initialized with.
Example:
let mut v: BoundedVec<Field, 5> = BoundedVec::new();
assert(v.max_len() == 5);
v.push(10);
assert(v.max_len() == 5);
Source code: test_programs/noir_test_success/bounded_vec/src/main.nr#L118-L124
storage
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:
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]);
Source code: test_programs/noir_test_success/bounded_vec/src/main.nr#L129-L136
extend_from_array
pub fn extend_from_array<Len>(&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:
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);
Source code: test_programs/noir_test_success/bounded_vec/src/main.nr#L141-L148
extend_from_bounded_vec
pub fn extend_from_bounded_vec<Len>(&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.
Example:
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]);
Source code: test_programs/noir_test_success/bounded_vec/src/main.nr#L153-L162
any
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:
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);
Source code: test_programs/noir_test_success/bounded_vec/src/main.nr#L229-L235