Struct Vec 

pub struct Vec<T> { /* private fields */ }

A concurrent, in-place growable vector.

This type behaves similarly to the standard library Vec except that it is guaranteed to never reallocate, and as such can support concurrent reads while also supporting growth. The vector grows similarly to the standard library vector, but instead of reallocating, it commits more memory.

All operations are lock-free. In order to support this, each element consists of a T and an AtomicBool used to denote whether the element has been initialized. That means that there is a memory overhead equal to align_of::<T>(). You can avoid this overhead if you have a byte of memory to spare in your T or by packing the bit into an existing atomic field in T by using RawVec.

If you don’t specify a [growth strategy], exponential growth with a growth factor of 2 is used, which is the same strategy that the standard library Vec uses.

Implementations

impl Vec<()>

pub const fn builder(max_capacity: usize) -> VecBuilder

Returns a builder for a new Vec.

max_capacity is the maximum capacity the vector can ever have. The vector is guaranteed to never exceed this capacity. The capacity can be excessively huge, as none of the memory is committed until you push elements into the vector or reserve capacity.

This function is implemented on Vec<()> so that you don’t have to import the VecBuilder type too. The type parameter has no relation to the built Vec.

impl<T> Vec<T>

pub fn new(max_capacity: usize) -> Self

Creates a new Vec.

max_capacity is the maximum capacity the vector can ever have. The vector is guaranteed to never exceed this capacity. The capacity can be excessively huge, as none of the memory is committed until you push elements into the vector or reserve capacity.

See the builder function for more creation options.

Panics

• Panics if the max_capacity would exceed isize::MAX bytes.
• Panics if reserving the allocation returns an error.

pub const fn dangling() -> Self

Creates a dangling Vec.

This is useful as a placeholder value to defer allocation until later or if no allocation is needed.

pub fn max_capacity(&self) -> usize

Returns the maximum capacity that was used when creating the Vec.

pub fn capacity(&self) -> usize

Returns the total number of elements the vector can hold without committing more memory.

pub fn len(&self) -> usize

Returns the number of elements in the vector.

This number may exceed capacity, doesn’t correspond to the number of initialized elements, and also doesn’t synchronize with setting the capacity.

pub fn is_empty(&self) -> bool

Returns true if the vector contains no elements.

This counts elements that failed to be pushed due to an error.

pub fn push(&self, value: T) -> usize

Appends an element to the end of the vector. Returns the index of the inserted element.

pub fn push_with(&self, f: impl FnOnce(usize) -> T) -> usize

Appends an element to the end of the vector.

f is called with the index of the element and the result is written to the element. Returns the index of the element.

pub fn push_mut(&mut self, value: T) -> usize

Appends an element to the end of the vector. Returns the index of the inserted element.

pub fn push_with_mut(&mut self, f: impl FnOnce(usize) -> T) -> usize

Appends an element to the end of the vector.

f is called with the index of the element and the result is written to the element. Returns the index of the element.

pub fn get(&self, index: usize) -> Option<&T>

Returns a reference to an element of the vector.

pub fn get_mut(&mut self, index: usize) -> Option<&mut T>

Returns a mutable reference to an element of the vector.

pub unsafe fn get_unchecked(&self, index: usize) -> &T

Returns a reference to an element of the vector without doing any checks.

Safety

index must have been previously acquired through push or push_mut on self.

pub unsafe fn get_unchecked_mut(&mut self, index: usize) -> &mut T

Returns a mutable reference to an element of the vector without doing any checks.

Safety

index must have been previously acquired through push or push_mut on self.

pub fn iter(&self) -> Iter<'_, T>

Returns an iterator that yields references to elements of the vector.

pub fn iter_mut(&mut self) -> IterMut<'_, T>

Returns an iterator that yields mutable references to elements of the vector.

pub fn reserve(&self, additional: usize)

Reserves capacity for at least additional more elements.

Not to be confused with reserving virtual memory; this method is named so as to match the standard library vector.

The new capacity is at least self.len() + additional. If this capacity is below the one calculated using the growth strategy, the latter is used. Does nothing if the capacity is already sufficient.

Panics

• Panics if self.len() + additional would exceed self.max_capacity().
• Panics if committing the new capacity fails.

pub fn reserve_exact(&self, additional: usize)

Reserves the minimum capacity required for additional more elements.

Not to be confused with reserving virtual memory; this method is named so as to match the standard library vector.

The new capacity is at least self.len() + additional. The growth strategy is ignored, but the new capacity can still be greater due to the alignment to the page size. Does nothing if the capacity is already sufficient.

Panics

• Panics if self.len() + additional would exceed self.max_capacity().
• Panics if committing the new capacity fails.

pub fn try_reserve(&self, additional: usize) -> Result<(), TryReserveError>

Tries to reserve capacity for at least additional more elements, returning an error on failure.

Not to be confused with reserving virtual memory; this method is named so as to match the standard library vector.

The new capacity is at least self.len() + additional. If this capacity is below the one calculated using the growth strategy, the latter is used. Does nothing if the capacity is already sufficient.

Errors

• Returns an error if self.len() + additional would exceed self.max_capacity().
• Returns an error if committing the new capacity fails.

pub fn try_reserve_exact( &self, additional: usize, ) -> Result<(), TryReserveError>

Tries to reserve the minimum capacity required for additional more elements, returning an error on failure.

Not to be confused with reserving virtual memory; this method is named so as to match the standard library vector.

The new capacity is at least self.len() + additional. The growth strategy is ignored, but the new capacity can still be greater due to the alignment to the page size. Does nothing if the capacity is already sufficient.

Errors

• Returns an error if self.len() + additional would exceed self.max_capacity().
• Returns an error if committing the new capacity fails.

Trait Implementations

impl<T> AsMut<Vec<T>> for Vec<T>

fn as_mut(&mut self) -> &mut Vec<T>

Converts this type into a mutable reference of the (usually inferred) input type.

impl<T> AsRef<Vec<T>> for Vec<T>

fn as_ref(&self) -> &Vec<T>

Converts this type into a shared reference of the (usually inferred) input type.

impl<T: Debug> Debug for Vec<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a, T: Copy> Extend<&'a T> for Vec<T>

fn extend<I: IntoIterator<Item = &'a T>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<T> Extend<T> for Vec<T>

fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<T: Hash> Hash for Vec<T>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T> Index<usize> for Vec<T>

type Output = T

The returned type after indexing.

fn index(&self, index: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T> IndexMut<usize> for Vec<T>

fn index_mut(&mut self, index: usize) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<'a, T> IntoIterator for &'a Vec<T>

type Item = &'a T

The type of the elements being iterated over.

type IntoIter = Iter<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, T> IntoIterator for &'a mut Vec<T>

type Item = &'a mut T

The type of the elements being iterated over.

type IntoIter = IterMut<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T> IntoIterator for Vec<T>

type Item = T

The type of the elements being iterated over.

type IntoIter = IntoIter<T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T: Ord> Ord for Vec<T>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T: PartialEq<U>, U> PartialEq<&[U]> for Vec<T>

fn eq(&self, other: &&[U]) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: PartialEq<U>, U, const N: usize> PartialEq<&[U; N]> for Vec<T>

fn eq(&self, other: &&[U; N]) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: PartialEq<U>, U> PartialEq<&mut [U]> for Vec<T>

fn eq(&self, other: &&mut [U]) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: PartialEq<U>, U> PartialEq<[U]> for Vec<T>

fn eq(&self, other: &[U]) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: PartialEq<U>, U, const N: usize> PartialEq<[U; N]> for Vec<T>

fn eq(&self, other: &[U; N]) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: PartialEq<U>, U> PartialEq<Vec<U>> for &[T]

fn eq(&self, other: &Vec<U>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: PartialEq<U>, U> PartialEq<Vec<U>> for &mut [T]

fn eq(&self, other: &Vec<U>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: PartialEq<U>, U> PartialEq<Vec<U>> for [T]

fn eq(&self, other: &Vec<U>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: PartialEq<U> + Clone, U> PartialEq<Vec<U>> for Cow<'_, [T]>

Available on crate feature alloc only.

fn eq(&self, other: &Vec<U>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: PartialEq<U>, U> PartialEq<Vec<U>> for Vec<T>

fn eq(&self, other: &Vec<U>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: PartialOrd> PartialOrd for Vec<T>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T: Eq> Eq for Vec<T>

impl<T: Send> Send for Vec<T>

impl<T: Send + Sync> Sync for Vec<T>