Trait orx_fixed_vec::prelude::PinnedVec

source ·

pub trait PinnedVec<T> {
    type Iter<'a>: Iterator<Item = &'a T>
       where T: 'a,
             Self: 'a;

Show 20 methods    // Required methods
    fn index_of(&self, data: &T) -> Option<usize>;
    fn clear(&mut self);
    fn capacity(&self) -> usize;
    fn extend_from_slice(&mut self, other: &[T])
       where T: Clone;
    fn get(&self, index: usize) -> Option<&T>;
    fn get_mut(&mut self, index: usize) -> Option<&mut T>;
    unsafe fn get_unchecked(&self, index: usize) -> &T;
    unsafe fn get_unchecked_mut(&mut self, index: usize) -> &mut T;
    fn is_empty(&self) -> bool;
    fn len(&self) -> usize;
    fn push(&mut self, value: T);
    unsafe fn unsafe_insert(&mut self, index: usize, element: T);
    unsafe fn unsafe_remove(&mut self, index: usize) -> T;
    unsafe fn unsafe_pop(&mut self) -> Option<T>;
    unsafe fn unsafe_swap(&mut self, a: usize, b: usize);
    unsafe fn unsafe_truncate(&mut self, len: usize);
    unsafe fn unsafe_clone(&self) -> Self
       where T: Clone;
    fn iter(&self) -> Self::Iter<'_>;
    fn partial_eq<S>(&self, other: S) -> bool
       where S: AsRef<[T]>,
             T: PartialEq;
    fn debug(&self, f: &mut Formatter<'_>) -> Result<(), Error>
       where T: Debug;
}

Expand description

Trait for vector representations differing from std::vec::Vec by the following:

=> memory location of an element already pushed to the collection never changes unless any of the following mut-methods is called:

clear, resize, truncate,
insert
remove, pop.

Equivalently:

=> the mut-methods push or extend_from_slice do not change memory locations of priorly added elements.

This pinned property is crticial and required for building collections such as orx-imp-vec::ImpVec.

Safety: Pinned Elements

Note that, together with PinnedVecSimple, this trait defines the required signature for implementing pinned vectors. However, the implementor struct is responsible for guaranteeing that push and extend_from_slice do not change memory locations of already added elements.

As expected, push and extend_from_slice are mut-methods. However, when the PinnedVec with pinned guarantees is wrapped in an ImpVec, these methods require only &self allowing to safely and conveniently represent complex-for-rust data structures.

Safety: Self Referential Vectors

One of the two main goals of the target ImpVec is to make it safe and convenient to build self-referential data structures, such as linked lists or trees. Elements of the vector being self-referential or not has a critical impact on safety of the mut-methods.

The arguments below are based on the possibility of self-referential vectors where elements can hold references to each other. This is not common in rust; however, it is safely possible with data structures such as ImpVec.

For instance, as expected insert is a safe method if the elements of the vector do not hold references to each other. However, if they do, since insert will change memory locations of existing elements, this operation is unsafe.

Therefore, the distinction is provided by the trait NotSelfRefVecItem.

For PinnedVec<T>

all mut-methods which change the memory locations of existing items such as insert, remove and swap are unsafe since this would invalidate the references held by other elements,
all mut-methods which remove elements from the vector such as pop, truncate or remove are unsafe since there might be elements holding a reference to the removed items,
- with the exception that clear is safe since all elements are gone at once,
additionally clone is unsafe because the cloned elements would be holding references to the original vector.

However, all these methods become safe if T: NotSelfRefVecItem through the type system as follows:

every V: PinnedVec<T> also automatically implements PinnedVecSimple<V>,
and PinnedVecSimple<V> provides safe versions of the above mentioned methods.

This makes sense since all the mentioned unsafety stems from the possibility of elements holding references to each other.

Note that NotSelfRefVecItem is a marker trait which means that the implementor takes the responsibility. Further, it is implemented for most primitive types.

Trait orx_fixed_vec::prelude::PinnedVec

Required Associated Types§

type Iter<'a>: Iterator<Item = &'a T> where T: 'a, Self: 'a

Required Methods§

fn index_of(&self, data: &T) -> Option<usize>

fn clear(&mut self)

fn capacity(&self) -> usize

fn extend_from_slice(&mut self, other: &[T])where T: Clone,

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

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

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

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

fn is_empty(&self) -> bool

fn len(&self) -> usize

fn push(&mut self, value: T)

unsafe fn unsafe_insert(&mut self, index: usize, element: T)

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

unsafe fn unsafe_pop(&mut self) -> Option<T>

unsafe fn unsafe_swap(&mut self, a: usize, b: usize)

unsafe fn unsafe_truncate(&mut self, len: usize)

unsafe fn unsafe_clone(&self) -> Selfwhere T: Clone,

fn iter(&self) -> Self::Iter<'_>

fn partial_eq<S>(&self, other: S) -> boolwhere S: AsRef<[T]>, T: PartialEq,

fn debug(&self, f: &mut Formatter<'_>) -> Result<(), Error>where T: Debug,

Object Safety§

Implementors§

impl<T> PinnedVec<T> for FixedVec<T>

type Iter<'a> = Iter<'a, T> where T: 'a, Self: 'a

fn extend_from_slice(&mut self, other: &[T])
where T: Clone,

unsafe fn unsafe_clone(&self) -> Self
where T: Clone,

fn partial_eq<S>(&self, other: S) -> bool
where S: AsRef<[T]>, T: PartialEq,

fn debug(&self, f: &mut Formatter<'_>) -> Result<(), Error>
where T: Debug,