Struct Slice 

pub struct Slice<T: Soars, D: ?Sized = [()]> { /* private fields */ }

A dynamically-sized view into the contents of a Soa.

Slice and Soa have the same relationship as [T] and [Vec]. The related types SliceRef and SliceMut are equivalent to &[T] and &mut [T].

This struct provides most of the implementation for Soa, SliceRef, and SliceMut via Deref impls. It is not usually constructed directly but instead used through one of these other types. The SliceRef and SliceMut wrappers attach lifetimes and ensure the same borrowing rules as & and &mut.

While [Vec] can return &[T] for all its slice methods, returning &Slice is not always possible. That is why SliceRef and SliceMut are necessary. While fat pointers allow packing length information as slice metadata, this is insufficient for SoA slices, which require multiple pointers alongside the length. Therefore, SoA slice references cannot be created on the stack and returned like normal slices can.

Implementations

impl<T> Slice<T>

where T: Soars,

pub const fn len(&self) -> usize

Returns the number of elements in the slice, also referred to as its length.

Examples

let soa = soa![Foo(1), Foo(2), Foo(3)];
assert_eq!(soa.len(), 3);

pub const fn is_empty(&self) -> bool

Returns true if the slice contains no elements.

Examples

let mut soa = Soa::<Foo>::new();
assert!(soa.is_empty());
soa.push(Foo(1));
assert!(!soa.is_empty());

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

Returns an iterator over the elements.

The iterator yields all items from start to end.

Examples

let soa = soa![Foo(1), Foo(2), Foo(4)];
let mut iter = soa.iter();
assert_eq!(iter.next(), Some(FooRef(&1)));
assert_eq!(iter.next(), Some(FooRef(&2)));
assert_eq!(iter.next(), Some(FooRef(&4)));
assert_eq!(iter.next(), None);

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

Returns an iterator over the elements that allows modifying each value.

The iterator yields all items from start to end.

Examples

let mut soa = soa![Foo(1), Foo(2), Foo(4)];
for mut elem in soa.iter_mut() {
    *elem.0 *= 2;
}
assert_eq!(soa, soa![Foo(2), Foo(4), Foo(8)]);

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

where I: SoaIndex<T>,

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.

Examples

let soa = soa![Foo(10), Foo(40), Foo(30), Foo(20)];
assert_eq!(soa.get(1), Some(FooRef(&40)));
assert!(soa.get(4).is_none());
assert_eq!(soa.get(..), Some(soa![Foo(10), Foo(40), Foo(30), Foo(20)].as_slice()));
assert_eq!(soa.get(..2), Some(soa![Foo(10), Foo(40)].as_slice()));
assert_eq!(soa.get(..=2), Some(soa![Foo(10), Foo(40), Foo(30)].as_slice()));
assert_eq!(soa.get(2..), Some(soa![Foo(30), Foo(20)].as_slice()));
assert_eq!(soa.get(1..3), Some(soa![Foo(40), Foo(30)].as_slice()));
assert_eq!(soa.get(1..=3), Some(soa![Foo(40), Foo(30), Foo(20)].as_slice()));
assert!(soa.get(2..5).is_none());

pub fn get_mut<I>(&mut self, index: I) -> Option<I::OutputMut<'_>>

where I: SoaIndex<T>,

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.

Examples

let mut soa = soa![Foo(1), Foo(2), Foo(3)];
if let Some(mut elem) = soa.get_mut(1) {
    *elem.0 = 42;
}
assert_eq!(soa, soa![Foo(1), Foo(42), Foo(3)]);

pub fn idx<I>(&self, index: I) -> I::Output<'_>

where I: SoaIndex<T>,

Returns a reference to the element at the given index.

This is similar to Index, which is not implementable for this type. See get for a non-panicking version.

Panics

Panics if the index is out-of-bounds, which is whenever SoaIndex::get returns None.

Examples

let soa = soa![Foo(10), Foo(40), Foo(30), Foo(90)];
assert_eq!(soa.idx(3), FooRef(&90));
assert_eq!(soa.idx(1..3), soa![Foo(40), Foo(30)]);

pub fn idx_mut<I>(&mut self, index: I) -> I::OutputMut<'_>

where I: SoaIndex<T>,

Returns a mutable reference to the element at the given index.

This is similar to IndexMut, which is not implementable for this type. See get_mut for a non-panicking version.

Panics

Panics if the index is out-of-bounds, which is whenever SoaIndex::get_mut returns None.

Examples

let mut soa = soa![Foo(10), Foo(20), Foo(30)];
*soa.idx_mut(1).0 = 42;
assert_eq!(soa, soa![Foo(10), Foo(42), Foo(30)]);

pub fn split_at(&self, mid: usize) -> (SliceRef<'_, T>, SliceRef<'_, T>)

Divides one slice into two at an index.

The first will contain all indices from [0, mid) (excluding the index mid itself) and the second will contain all indices from [mid, len) (excluding the index len itself).

Panics

Panics if mid > len. For a non-panicking alternative see split_at_checked.

Examples

let soa = soa![Foo(1), Foo(2), Foo(3), Foo(4), Foo(5)];
let (l, r) = soa.split_at(3);
assert_eq!(l, soa![Foo(1), Foo(2), Foo(3)]);
assert_eq!(r, soa![Foo(4), Foo(5)]);

pub fn split_at_mut(&mut self, mid: usize) -> (SliceMut<'_, T>, SliceMut<'_, T>)

Divides one mutable slice into two at an index.

The first will contain all indices from [0, mid) (excluding the index mid itself) and the second will contain all indices from [mid, len) (excluding the index len itself).

Panics

Panics if mid > len. For a non-panicking alternative see split_at_mut_checked.

Examples

let mut soa = soa![Foo(1), Foo(2), Foo(3), Foo(4), Foo(5)];
let (l, r) = soa.split_at_mut(3);
assert_eq!(l, soa![Foo(1), Foo(2), Foo(3)]);
assert_eq!(r, soa![Foo(4), Foo(5)]);

pub fn split_at_checked( &self, mid: usize, ) -> Option<(SliceRef<'_, T>, SliceRef<'_, T>)>

Divides one slice into two at an index, returning None if the slice is too short.

If mid ≤ len returns a pair of slices where the first will contain all indices from [0, mid) (excluding the index mid itself) and the second will contain all indices from [mid, len) (excluding the index len itself).

Otherwise, if mid > len, returns None.

Examples

let soa = soa![Foo(1), Foo(2), Foo(3), Foo(4)];

{
    let (l, r) = soa.split_at_checked(0).unwrap();
    assert_eq!(l, soa![]);
    assert_eq!(r, soa);
}

{
    let (l, r) = soa.split_at_checked(2).unwrap();
    assert_eq!(l, soa![Foo(1), Foo(2)]);
    assert_eq!(r, soa![Foo(3), Foo(4)]);
}

{
    let (l, r) = soa.split_at_checked(4).unwrap();
    assert_eq!(l, soa);
    assert_eq!(r, soa![]);
}

assert_eq!(None, soa.split_at_checked(5));

pub fn split_at_mut_checked( &mut self, mid: usize, ) -> Option<(SliceMut<'_, T>, SliceMut<'_, T>)>

Divides one mutable slice into two at an index, returning None if the slice is too short.

If mid ≤ len returns a pair of slices where the first will contain all indices from [0, mid) (excluding the index mid itself) and the second will contain all indices from [mid, len) (excluding the index len itself).

Otherwise, if mid > len, returns None.

Examples

let mut soa = soa![Foo(1), Foo(2), Foo(3), Foo(4)];

{
    let (l, r) = soa.split_at_mut_checked(0).unwrap();
    assert_eq!(l, soa![]);
    assert_eq!(r, soa![Foo(1), Foo(2), Foo(3), Foo(4)]);
}

{
    let (l, r) = soa.split_at_mut_checked(2).unwrap();
    assert_eq!(l, soa![Foo(1), Foo(2)]);
    assert_eq!(r, soa![Foo(3), Foo(4)]);
}

{
    let (l, r) = soa.split_at_mut_checked(4).unwrap();
    assert_eq!(l, soa![Foo(1), Foo(2), Foo(3), Foo(4)]);
    assert_eq!(r, soa![]);
}

assert_eq!(None, soa.split_at_mut_checked(5));

pub unsafe fn split_at_unchecked( &self, mid: usize, ) -> (SliceRef<'_, T>, SliceRef<'_, T>)

Divides one slice into two at an index without doing bounds checking.

The first will contain all indices from [0, mid) (excluding the index mid itself) and the second will contain all indices from [mid, len) (excluding the index len itself).

For a safe alternative, see split_at.

Safety

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

Examples

let soa = soa![Foo(1), Foo(2), Foo(3)];
let (l, r) = unsafe { soa.split_at_unchecked(2) };
assert_eq!(l, soa![Foo(1), Foo(2)]);
assert_eq!(r, soa![Foo(3)]);

pub unsafe fn split_at_mut_unchecked( &mut self, mid: usize, ) -> (SliceMut<'_, T>, SliceMut<'_, T>)

Divides one mutable slice into two at an index without doing bounds checking.

The first will contain all indices from [0, mid) (excluding the index mid itself) and the second will contain all indices from [mid, len) (excluding the index len itself).

For a safe alternative, see split_at_mut.

Safety

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

Examples

let mut soa = soa![Foo(1), Foo(2), Foo(3)];
let (l, r) = unsafe { soa.split_at_mut_unchecked(1) };
assert_eq!(l, soa![Foo(1)]);
assert_eq!(r, soa![Foo(2), Foo(3)]);

pub fn swap(&mut self, a: usize, b: usize)

Swaps the position of two elements.

Arguments

• a: The index of the first element
• b: The index of the second element

Panics

Panics if a or b is out of bounds.

Examples

let mut soa = soa![Foo(0), Foo(1), Foo(2), Foo(3), Foo(4)];
soa.swap(2, 4);
assert_eq!(soa, soa![Foo(0), Foo(1), Foo(4), Foo(3), Foo(2)]);

pub fn first(&self) -> Option<T::Ref<'_>>

Returns the first element of the slice, or None if empty.

Examples

let soa = soa![Foo(10), Foo(40), Foo(30)];
assert_eq!(soa.first(), Some(FooRef(&10)));

let soa = Soa::<Foo>::new();
assert_eq!(soa.first(), None);

pub fn first_mut(&mut self) -> Option<T::RefMut<'_>>

Returns a mutable reference to the first element of the slice, or None if empty.

Examples

let mut soa = soa![Foo(0), Foo(1), Foo(2)];
if let Some(mut first) = soa.first_mut() {
    *first.0 = 5;
}
assert_eq!(soa, soa![Foo(5), Foo(1), Foo(2)]);

pub fn last(&self) -> Option<T::Ref<'_>>

Returns the last element of the slice, or None if empty.

Examples

let soa = soa![Foo(10), Foo(40), Foo(30)];
assert_eq!(soa.last(), Some(FooRef(&30)));

let soa = Soa::<Foo>::new();
assert_eq!(soa.last(), None);

pub fn last_mut(&mut self) -> Option<T::RefMut<'_>>

Returns a mutable reference to the last element of the slice, or None if empty.

Examples

let mut soa = soa![Foo(0), Foo(1), Foo(2)];
if let Some(mut last) = soa.last_mut() {
    *last.0 = 5;
}
assert_eq!(soa, soa![Foo(0), Foo(1), Foo(5)]);

pub fn chunks_exact(&self, chunk_size: usize) -> ChunksExact<'_, T>

Returns an iterator over chunk_size elements of the slice at a time, starting at the beginning of the slice.

The chunks are slices and do not overlap. If chunk_size does not divide the length of the slice, then the last up to chunk_size-1 elements will be omitted and can be retrieved from the remainder function of the iterator.

Due to each chunk having exactly chunk_size elements, the compiler can often optimize the resulting code better than in the case of chunks.

Examples

let soa = soa![Foo('l'), Foo('o'), Foo('r'), Foo('e'), Foo('m')];
let mut iter = soa.chunks_exact(2);
assert_eq!(iter.next(), Some(soa![Foo('l'), Foo('o')].as_slice()));
assert_eq!(iter.next(), Some(soa![Foo('r'), Foo('e')].as_slice()));
assert!(iter.next().is_none());
assert_eq!(iter.remainder(), &soa![Foo('m')]);

pub fn slices(&self) -> T::Slices<'_>

Returns a collection of slices for each field of the slice.

For convenience, slices can also be aquired using the getter methods for individual fields.

Examples

let soa = soa![Foo { foo: 1, bar: 2 }, Foo { foo: 3, bar: 4 }];
let slices = soa.slices();
assert_eq!(slices.foo, soa.foo());
assert_eq!(slices.bar, soa.bar());

pub fn slices_mut(&mut self) -> T::SlicesMut<'_>

Returns a collection of mutable slices for each field of the slice.

For convenience, individual mutable slices can also be aquired using the getter methods for individual fields. This method is necessary to be able to mutably borrow multiple SoA fields simultaneously.

Examples

let mut soa = soa![Foo { foo: 1, bar: 0 }, Foo { foo: 2, bar: 0 }];
let slices = soa.slices_mut();
for (foo, bar) in slices.foo.iter().zip(slices.bar) {
    *bar = foo * 2;
}
assert_eq!(soa.bar(), [2, 4]);

Trait Implementations

impl<T> AsMut<Slice<T>> for Slice<T>

where T: Soars,

fn as_mut(&mut self) -> &mut Self

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

impl<T> AsMut<Slice<T>> for SliceMut<'_, T>

where T: Soars,

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

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

impl<T> AsMut<Slice<T>> for Soa<T>

where T: Soars,

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

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

impl<T> AsMutSlice for Slice<T>

where T: Soars,

fn as_mut_slice(&mut self) -> SliceMut<'_, Self::Item>

Returns a SliceMut containing the entire array.

impl<T> AsRef<Slice<T>> for IntoIter<T>

where T: Soars,

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

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

impl<'a, T> AsRef<Slice<T>> for Iter<'a, T>

where T: 'a + Soars,

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

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

impl<'a, T> AsRef<Slice<T>> for IterMut<'a, T>

where T: 'a + Soars,

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

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

impl<T> AsRef<Slice<T>> for Slice<T>

where T: Soars,

fn as_ref(&self) -> &Self

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

impl<T> AsRef<Slice<T>> for SliceMut<'_, T>

where T: Soars,

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

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

impl<T> AsRef<Slice<T>> for SliceRef<'_, T>

where T: Soars,

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

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

impl<T> AsRef<Slice<T>> for Soa<T>

where T: Soars,

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

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

impl<T> AsSlice for Slice<T>

where T: Soars,

type Item = T

The type that the slice contains.

fn as_slice(&self) -> SliceRef<'_, Self::Item>

Returns a SliceRef containing the entire array.

impl<T> Borrow<Slice<T>> for SliceMut<'_, T>

where T: Soars,

fn borrow(&self) -> &Slice<T>

Immutably borrows from an owned value.

impl<T> Borrow<Slice<T>> for SliceRef<'_, T>

where T: Soars,

fn borrow(&self) -> &Slice<T>

Immutably borrows from an owned value.

impl<T> Borrow<Slice<T>> for Soa<T>

where T: Soars,

fn borrow(&self) -> &Slice<T>

Immutably borrows from an owned value.

impl<T> BorrowMut<Slice<T>> for SliceMut<'_, T>

where T: Soars,

fn borrow_mut(&mut self) -> &mut Slice<T>

Mutably borrows from an owned value.

impl<T> BorrowMut<Slice<T>> for Soa<T>

where T: Soars,

fn borrow_mut(&mut self) -> &mut Slice<T>

Mutably borrows from an owned value.

impl<T> Clone for Slice<T, ()>

where T: Soars,

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Slice<T>

where T: Soars, for<'a> T::Ref<'a>: Debug,

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

Formats the value using the given formatter.

impl<T> Deref for Slice<T>

where T: Soars,

type Target = <T as Soars>::Deref

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T> DerefMut for Slice<T>

where T: Soars,

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<T> Hash for Slice<T>

where T: Soars, for<'a> T::Ref<'a>: Hash,

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

Feeds this value into the given Hasher.

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

where T: Soars,

type Item = <T as Soars>::Ref<'a>

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 Slice<T>

where T: Soars,

type Item = <T as Soars>::RefMut<'a>

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> Ord for Slice<T>

where T: Soars, for<'a> T::Ref<'a>: Ord,

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

This method returns an Ordering between self and other.

impl<T, R> PartialEq<R> for Slice<T>

where T: Soars, R: AsSlice<Item = T> + ?Sized, for<'a> T::Ref<'a>: PartialEq,

fn eq(&self, other: &R) -> 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 for Slice<T>

where T: Soars, for<'a> T::Ref<'a>: PartialOrd,

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> Copy for Slice<T, ()>

where T: Soars,

impl<T> Eq for Slice<T>

where T: Soars, for<'a> T::Ref<'a>: Eq,

impl<T, D: ?Sized> Send for Slice<T, D>

where T: Send + Soars,

impl<T, D: ?Sized> Sync for Slice<T, D>

where T: Sync + Soars,