Struct FixedVec 

pub struct FixedVec<T: ?Sized>(/* private fields */);

A vector designed for DST.

Implementations

impl<T: ?Sized> FixedVec<T>

pub const fn new(metadata: <T as Pointee>::Metadata) -> Self

Constructs a new, empty FixedVec<T>, with provided metadata.

The vector will not allocate until elements are pushed onto it.

Examples

let mut vec: FixedVec<UnsizedSlice<u32, u64>> = FixedVec::new(6);

pub const fn new_like(ptr: *const T) -> Self

Constructs a new, empty FixedVec<T>. The metadata is obtained from the provided pointer.

The vector will not allocate until elements are pushed onto it.

Examples

let array = [0u32, 1, 2];
let mut vec: FixedVec<[u32]> = FixedVec::new_like(array.as_slice());

pub fn with_capacity( metadata: <T as Pointee>::Metadata, capacity: usize, ) -> Self

Constructs a new, empty FixedVec<T> with at least the specified capacity.

pub fn with_capacity_like(ptr: *const T, capacity: usize) -> Self

Constructs a new, empty FixedVec<T> with at least the specified capacity. The metadata is obtained from the provided pointer.

pub fn capacity(&self) -> usize

Returns the total number of elements the vector can hold without reallocating.

Examples

let mut vec: FixedVec<UnsizedSlice<u32, u32>> = FixedVec::with_capacity(3, 10);
// SAFETY: u32 is trivial.
unsafe{ vec.push_with(|_| {}) };
assert_eq!(vec.capacity(), 10);

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more elements to be inserted in the given FixedVec<T>. The collection may reserve more space to speculatively avoid frequent reallocations. After calling reserve, capacity will be greater than or equal to self.len() + additional. Does nothing if capacity is already sufficient.

Panics

Panics if the new capacity exceeds isize::MAX bytes.

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the vector as much as possible.

It will drop down as close as possible to the length but the allocator may still inform the vector that there is space for a few more elements.

Examples

let mut vec: FixedVec<UnsizedSlice<u32, u32>> = FixedVec::with_capacity(3, 10);
// SAFETY: u32 is trivial.
unsafe{ vec.push_with(|_| {}) };
assert_eq!(vec.capacity(), 10);
vec.shrink_to_fit();
assert!(vec.capacity() >= 1);

pub fn shrink_to(&mut self, min_capacity: usize)

Shrinks the capacity of the vector with a lower bound.

The capacity will remain at least as large as both the length and the supplied value.

If the current capacity is less than the lower limit, this is a no-op.

Examples

let mut vec: FixedVec<UnsizedSlice<u32, u32>> = FixedVec::with_capacity(3, 10);
// SAFETY: u32 is trivial.
unsafe{ vec.push_with(|_| {}) };
assert_eq!(vec.capacity(), 10);
vec.shrink_to(2);
assert!(vec.capacity() >= 2);
vec.shrink_to(0);
assert!(vec.capacity() >= 1);

pub fn truncate(&mut self, len: usize)

Shortens the vector, keeping the first len elements and dropping the rest.

If len is greater than the vector’s current length, this has no effect.

Note that this method has no effect on the allocated capacity of the vector.

Examples

Truncating a five element vector to two elements:

let mut vec: FixedVec<UnsizedSlice<u32, u32>> = FixedVec::with_capacity(3, 10);
// SAFETY: u32 is trivial.
unsafe{ vec.push_with(|slice| { slice.header.write(1); }) };
unsafe{ vec.push_with(|slice| { slice.header.write(2); }) };
unsafe{ vec.push_with(|slice| { slice.header.write(3); }) };
vec.truncate(2);
assert_eq!(vec.len(), 2);
assert_eq!(vec[0].header, 1);
assert_eq!(vec[1].header, 2);

No truncation occurs when len is greater than the vector’s current length:

let mut vec: FixedVec<UnsizedSlice<u32, u32>> = FixedVec::with_capacity(3, 10);
// SAFETY: u32 is trivial.
unsafe{ vec.push_with(|slice| { slice.header.write(1); }) };
unsafe{ vec.push_with(|slice| { slice.header.write(2); }) };
unsafe{ vec.push_with(|slice| { slice.header.write(3); }) };
vec.truncate(8);
assert_eq!(vec.len(), 3);
assert_eq!(vec[0].header, 1);
assert_eq!(vec[1].header, 2);
assert_eq!(vec[2].header, 3);

Truncating when len == 0 is equivalent to calling the clear method.

let mut vec: FixedVec<UnsizedSlice<u32, u32>> = FixedVec::with_capacity(3, 10);
// SAFETY: u32 is trivial.
unsafe{ vec.push_with(|slice| { slice.header.write(1); }) };
unsafe{ vec.push_with(|slice| { slice.header.write(2); }) };
unsafe{ vec.push_with(|slice| { slice.header.write(3); }) };
vec.truncate(0);
assert_eq!(vec.len(), 0);

pub fn as_ptr(&self) -> *const T

Returns a raw pointer to the vector’s buffer, or a dangling raw pointer valid for zero sized reads if the vector didn’t allocate.

The caller must ensure that the vector outlives the pointer this function returns, or else it will end up pointing to garbage. Modifying the vector may cause its buffer to be reallocated, which would also make any pointers to it invalid.

The caller must also ensure that the memory the pointer (non-transitively) points to is never written to (except inside an UnsafeCell) using this pointer or any pointer derived from it. If you need to mutate the contents of the slice, use as_mut_ptr.

pub fn as_mut_ptr(&mut self) -> *mut T

Returns an unsafe mutable pointer to the vector’s buffer, or a dangling raw pointer valid for zero sized reads if the vector didn’t allocate.

The caller must ensure that the vector outlives the pointer this function returns, or else it will end up pointing to garbage. Modifying the vector may cause its buffer to be reallocated, which would also make any pointers to it invalid.

Examples

#![feature(ptr_metadata)]

// Allocate vector big enough for 1 elements.
let size = 1;
let mut x: FixedVec<UnsizedSlice<u32, u32>> = FixedVec::with_capacity(2, size);
let x_ptr = x.as_mut_ptr();

// Initialize elements via raw pointer writes, then set length.
unsafe {
    let u32_ptr = x_ptr.to_raw_parts().0 as *mut u32;
    for i in 0..3 {
        *u32_ptr.add(i) = i as u32;
    }
    x.set_len(size);
}
assert_eq!(x[0].header, 0);
assert_eq!(&x[0].slice, &[1, 2]);

pub unsafe fn set_len(&mut self, new_len: usize)

Forces the length of the vector to new_len.

This is a low-level operation that maintains none of the normal invariants of the type. Normally changing the length of a vector is done using one of the safe operations instead, such as truncate, extend, or clear.

Safety

• new_len must be less than or equal to capacity().
• The elements at old_len..new_len must be initialized.

pub fn swap_remove(&mut self, index: usize) -> Box<T>

Removes an element from the vector and returns it.

The removed element is replaced by the last element of the vector.

This does not preserve ordering, but is O(1). If you need to preserve the element order, use remove instead.

Panics

Panics if index is out of bounds.

Examples

let mut v = FixedVec::<str>::new(3);
v.push(Box::from("foo"));
v.push(Box::from("bar"));
v.push(Box::from("baz"));
v.push(Box::from("qux"));

assert_eq!(v.swap_remove(1).as_ref(), "bar");
assert_eq!(&v[1], "qux");

assert_eq!(v.swap_remove(0).as_ref(), "foo");
assert_eq!(&v[0], "baz");

pub fn insert(&mut self, index: usize, element: Box<T>)

Inserts an element at position index within the vector, shifting all elements after it to the right.

Panics

Panics if index > len.

Examples

#![feature(maybe_uninit_write_slice)]

let mut vec = FixedVec::<[i32]>::new(2);
unsafe {
    vec.push_with(|slice| { slice.write_copy_of_slice(&[1, 1]); });
    vec.insert(0, Box::<[i32]>::new_zeroed_unsized(2).assume_init());
}
assert_eq!(&vec[0], [0, 0]);
assert_eq!(&vec[1], [1, 1]);

pub unsafe fn insert_with( &mut self, index: usize, f: impl FnOnce(&mut T::Target), )

where T: MaybeUninitProject,

Inserts an element at position index within the vector, shifting all elements after it to the right.

Panics

Panics if index > len.

Safety

The caller should ensure the new element being initialized.

Examples

#![feature(maybe_uninit_write_slice)]

let mut vec = FixedVec::<[i32]>::new(2);
unsafe {
    vec.push_with(|slice| { slice.write_copy_of_slice(&[1, 1]); });
    vec.insert_with(0, |slice| { slice.write_copy_of_slice(&[0, 0]); });
}
assert_eq!(&vec[0], [0, 0]);
assert_eq!(&vec[1], [1, 1]);

pub fn insert_clone(&mut self, index: usize, element: &T)

where T: UnsizedClone,

Inserts an element at position index within the vector, shifting all elements after it to the right.

Panics

Panics if index > len.

Examples

let element0: Box<[i32]> = Box::from([0, 0]);
let element1: Box<[i32]> = Box::from([1, 1]);

let mut vec = FixedVec::<[i32]>::new(2);
vec.push_clone(element1.as_ref());
vec.insert_clone(0, element0.as_ref());
assert_eq!(&vec[0], [0, 0]);
assert_eq!(&vec[1], [1, 1]);

pub fn remove(&mut self, index: usize) -> Box<T>

Removes and returns the element at position index within the vector, shifting all elements after it to the left.

Panics

Panics if index is out of bounds.

Examples

#![feature(maybe_uninit_write_slice)]

let mut vec = FixedVec::<[i32]>::new(2);
unsafe {
    vec.push_with(|slice| { slice.write_copy_of_slice(&[0, 0]); });
    vec.push_with(|slice| { slice.write_copy_of_slice(&[1, 1]); });
}
assert_eq!(vec.remove(0).as_ref(), &[0, 0]);
assert_eq!(&vec[0], &[1, 1]);

pub fn push(&mut self, value: Box<T>)

Appends an element to the back of a collection.

Panics

Panics if the new capacity exceeds isize::MAX bytes.

pub unsafe fn push_with(&mut self, f: impl FnOnce(&mut T::Target))

where T: MaybeUninitProject,

Appends an element to the back of a collection.

Panics

Panics if the new capacity exceeds isize::MAX bytes.

Safety

The same as insert_with.

pub fn push_clone(&mut self, value: &T)

where T: UnsizedClone,

Appends an element to the back of a collection.

Panics

Panics if the new capacity exceeds isize::MAX bytes.

pub fn pop(&mut self) -> Option<Box<T>>

Removes the last element from a vector and returns it, or None if it is empty.

pub fn clear(&mut self)

Clears the vector, removing all values.

Note that this method has no effect on the allocated capacity of the vector.

Examples

let mut vec = FixedVec::<[i32]>::new(2);
unsafe {
    vec.push_with(|slice| {});
    vec.push_with(|slice| {});
}
vec.clear();
assert!(vec.is_empty());

pub fn len(&self) -> usize

Returns the number of elements in the vector, also referred to as its ‘length’.

Examples

let mut vec = FixedVec::<[i32]>::new(2);
unsafe {
    vec.push_with(|slice| {});
    vec.push_with(|slice| {});
}
assert_eq!(vec.len(), 2);

pub fn is_empty(&self) -> bool

Returns true if the vector contains no elements.

Examples

let mut vec = FixedVec::<[i32]>::new(2);
assert!(vec.is_empty());
unsafe {
    vec.push_with(|slice| {});
    vec.push_with(|slice| {});
}
assert!(!vec.is_empty());

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

Returns an iterator over the vector.

The iterator yields all items from start to end.

Examples

#![feature(maybe_uninit_write_slice)]

let mut vec = FixedVec::<[i32]>::new(2);
unsafe {
    vec.push_with(|slice| { slice.write_copy_of_slice(&[0, 0]); });
    vec.push_with(|slice| { slice.write_copy_of_slice(&[1, 1]); });
    vec.push_with(|slice| { slice.write_copy_of_slice(&[2, 2]); });
}

let mut iterator = vec.iter();

assert_eq!(iterator.next(), Some(&[0, 0][..]));
assert_eq!(iterator.next(), Some(&[1, 1][..]));
assert_eq!(iterator.next(), Some(&[2, 2][..]));
assert_eq!(iterator.next(), None);

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

Returns an iterator that allows modifying each value.

The iterator yields all items from start to end.

Examples

#![feature(maybe_uninit_write_slice)]

let mut vec = FixedVec::<[i32]>::new(2);
unsafe {
    vec.push_with(|slice| { slice.write_copy_of_slice(&[0, 0]); });
    vec.push_with(|slice| { slice.write_copy_of_slice(&[1, 1]); });
    vec.push_with(|slice| { slice.write_copy_of_slice(&[2, 2]); });
}

for elem in vec.iter_mut() {
    elem[0] += 2;
    elem[1] *= 2;
}

let mut iterator = vec.iter();

assert_eq!(iterator.next(), Some(&[2, 0][..]));
assert_eq!(iterator.next(), Some(&[3, 2][..]));
assert_eq!(iterator.next(), Some(&[4, 4][..]));
assert_eq!(iterator.next(), None);

pub fn get<I: SliceIndex<Self>>(&self, index: I) -> Option<&I::Output>

Returns a reference to an element or subslice depending on the type of index.

• If given a position, returns a reference to the element at that position or None if out of bounds.
• If given a range, returns the subslice corresponding to that range, or None if out of bounds.

pub fn get_mut<I: SliceIndex<Self>>( &mut self, index: I, ) -> Option<&mut I::Output>

Returns a mutable reference to an element or subslice depending on the type of index (see get) or None if the index is out of bounds.

pub unsafe fn get_unchecked<I: SliceIndex<Self>>(&self, index: I) -> &I::Output

Returns a reference to an element or subslice, without doing bounds checking.

For a safe alternative see get.

Safety

Calling this method with an out-of-bounds index is undefined behavior even if the resulting reference is not used.

pub unsafe fn get_unchecked_mut<I: SliceIndex<Self>>( &mut self, index: I, ) -> &mut I::Output

Returns a mutable reference to an element or subslice, without doing bounds checking.

For a safe alternative see get_mut.

Safety

Calling this method with an out-of-bounds index is undefined behavior even if the resulting reference is not used.

Trait Implementations

impl<T: ?Sized + UnsizedClone> Clone for FixedVec<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: ?Sized> Drop for FixedVec<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: ?Sized> Extend<Box<T>> for FixedVec<T>

fn extend<I: IntoIterator<Item = Box<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: ?Sized, I: SliceIndex<FixedVec<T>>> Index<I> for FixedVec<T>

type Output = <I as SliceIndex<FixedVec<T>>>::Output

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<T: ?Sized, I: SliceIndex<FixedVec<T>>> IndexMut<I> for FixedVec<T>

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

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

impl<'a, T: ?Sized> IntoIterator for &'a FixedVec<T>

type Item = &'a T

The type of the elements being iterated over.

type IntoIter = FixedVecIter<'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: ?Sized> IntoIterator for &'a mut FixedVec<T>

type Item = &'a mut T

The type of the elements being iterated over.

type IntoIter = FixedVecIterMut<'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: ?Sized> SliceIndex<FixedVec<T>> for RangeFull

type Output = FixedVec<T>

The output type returned by methods.

fn get(self, slice: &FixedVec<T>) -> Option<&Self::Output>

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

Returns a shared reference to the output at this location, if in bounds.

fn get_mut(self, slice: &mut FixedVec<T>) -> Option<&mut Self::Output>

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

Returns a mutable reference to the output at this location, if in bounds.

unsafe fn get_unchecked(self, slice: *const FixedVec<T>) -> *const Self::Output

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

Returns a pointer to the output at this location, without performing any bounds checking.

unsafe fn get_unchecked_mut(self, slice: *mut FixedVec<T>) -> *mut Self::Output

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

Returns a mutable pointer to the output at this location, without performing any bounds checking.

fn index(self, slice: &FixedVec<T>) -> &Self::Output

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

Returns a shared reference to the output at this location, panicking if out of bounds.

fn index_mut(self, slice: &mut FixedVec<T>) -> &mut Self::Output

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

Returns a mutable reference to the output at this location, panicking if out of bounds.

impl<T: ?Sized> SliceIndex<FixedVec<T>> for usize

type Output = T

The output type returned by methods.

fn get(self, slice: &FixedVec<T>) -> Option<&Self::Output>

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

Returns a shared reference to the output at this location, if in bounds.

fn get_mut(self, slice: &mut FixedVec<T>) -> Option<&mut Self::Output>

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

Returns a mutable reference to the output at this location, if in bounds.

unsafe fn get_unchecked(self, slice: *const FixedVec<T>) -> *const Self::Output

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

Returns a pointer to the output at this location, without performing any bounds checking.

unsafe fn get_unchecked_mut(self, slice: *mut FixedVec<T>) -> *mut Self::Output

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

Returns a mutable pointer to the output at this location, without performing any bounds checking.

fn index(self, slice: &FixedVec<T>) -> &Self::Output

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

Returns a shared reference to the output at this location, panicking if out of bounds.

fn index_mut(self, slice: &mut FixedVec<T>) -> &mut Self::Output

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

Returns a mutable reference to the output at this location, panicking if out of bounds.