Struct Select 

pub struct Select<S, I = Vec<usize>> {
    pub indices: I,
    pub target: S,
}

A Set that is a non-contiguous, unordered and possibly duplicated selection of some larger collection. S can be any borrowed collection type that implements Set. Note that it doesn’t make much sense to have a Select type own the data that it selects from, although it’s possible to create one.

Simple Usage Examples

The following example shows how to Select from a range.

use flatk::*;
let selection = Select::new(vec![0,2,4,0,1], 5..10);
let mut iter = selection.iter();
assert_eq!(Some((0, 5)), iter.next());
assert_eq!(Some((2, 7)), iter.next());
assert_eq!(Some((4, 9)), iter.next());
assert_eq!(Some((0, 5)), iter.next());
assert_eq!(Some((1, 6)), iter.next());
assert_eq!(None, iter.next());

The next example shows how to Select from a UniChunked view.

use flatk::*;
let mut v = Chunked3::from_flat((1..=15).collect::<Vec<_>>());
let mut selection = Select::new(vec![1,0,4,4,1], v.view_mut());
*selection.view_mut().isolate(0).1 = [0; 3];
{
    let selection_view = selection.view();
    let mut iter = selection_view.iter();
    assert_eq!(Some((1, &[0,0,0])), iter.next());
    assert_eq!(Some((0, &[1,2,3])), iter.next());
    assert_eq!(Some((4, &[13,14,15])), iter.next());
    assert_eq!(Some((4, &[13,14,15])), iter.next());
    assert_eq!(Some((1, &[0,0,0])), iter.next());
    assert_eq!(None, iter.next());
}

Mutable Selections

A Selection of a mutable borrow cannot be SplitAt, which means it cannot be Chunked. This is because a split selection must have a copy of the mutable borrow since an index from any half of the split can access any part of the data. This of course breaks Rust’s aliasing rules. It is possible, however to bypass this restriction by using interior mutability.

Common Uses

Selections are a useful way to annotate arrays of indices into some other array or even a range. It is not uncommon to use a Vec<usize> to represent indices into another collection. Using Select instead lets the user be explicit about where these indices are pointing without having to annotate the indices themselves.

Fields

indices: I

target: S

Implementations

impl<S, I> Select<S, I>

where S: Set, I: AsIndexSlice,

pub fn new(indices: I, target: S) -> Self

Create a selection of elements from the original set from the given indices.

Example

use flatk::*;
let v = vec!['a', 'b', 'c'];
let selection = Select::new(vec![1,2,1], v.as_slice());
assert_eq!('b', selection[0]);
assert_eq!('c', selection[1]);
assert_eq!('b', selection[2]);

impl<S: Set> Select<S, Range<usize>>

pub fn from_range(indices: Range<usize>, target: S) -> Self

Create a selection of elements from the original set from the given indices.

Example

use flatk::*;
let v = vec!['a', 'b', 'c'];
let selection = Select::from_range(1..3, v.as_slice());
assert_eq!('b', selection[0]);
assert_eq!('c', selection[1]);

impl<'a, S, I> Select<S, I>

where S: Set + IntoOwned + Get<'a, usize>, <S as IntoOwned>::Owned: FromIterator<<S as Set>::Elem>, <S as Get<'a, usize>>::Output: IntoOwned<Owned = <S as Set>::Elem>, I: AsIndexSlice,

pub fn collapse(self) -> S::Owned

Collapse the target values pointed to by indices into the structure given by the indices. In other words, replace indices with the target data they point to producing a new collection. This function allocates.

Examples

In the following simple example, we convert a selection of characters from a standard Vec into a standard owned Vec of characters.

use flatk::*;
let v = vec!['a', 'b', 'c'];
let selection = Select::new(vec![1,2,1], v.as_slice());
assert_eq!(vec!['b', 'c', 'b'], selection.collapse());

A more complex example below shows how selections of chunked types can be collapsed as well.

use flatk::*;
// Start with a vector of words stored as Strings.
let v = vec!["World", "Coffee", "Cat", " ", "Hello", "Refrigerator", "!"];

// Convert the strings to bytes.
let bytes: Vec<Vec<u8>> = v
    .into_iter()
    .map(|word| word.to_string().into_bytes())
    .collect();

// Chunk the nested vector at word boundaries.
let words = Chunked::<Vec<u8>>::from_nested_vec(bytes);

// Select some of the words from the collection.
let selection = Select::new(vec![4, 3, 0, 6, 3, 4, 6], words);

// Collapse the selected words into an owned collection.
let collapsed = selection.view().collapse();

assert_eq!(
    "Hello World! Hello!",
    String::from_utf8(collapsed.data().clone()).unwrap().as_str()
);

impl<'a, S, I> Select<S, I>

where S: Set + Get<'a, usize, Output = &'a <S as Set>::Elem> + View<'a>, I: AsIndexSlice, <S as View<'a>>::Type: IntoIterator<Item = S::Output>, <S as Set>::Elem: 'a,

pub fn clone_values_into<V>(&'a self, other: &'a mut V)

where V: ViewMut<'a> + ?Sized, <V as ViewMut<'a>>::Type: Set + IntoIterator<Item = &'a mut S::Elem>, <S as Set>::Elem: Clone,

The typical way to use this function is to clone from a SelectView into a mutable S type. This function disregards indies, and simply clones the underlying target data.

Panics

This function panics if other has a length unequal to self.len().

Example

use flatk::*;
let v = vec![1,2,3,4,5];
let indices = vec![3,3,4,0];
let selection = Select::new(indices.as_slice(), v.as_slice());
let mut owned = vec![0; 5];
selection.clone_values_into(&mut owned[..4]); // Need 4 elements to avoid panics.
let mut iter_owned = owned.iter();
assert_eq!(owned, vec![4,4,5,1,0]);

impl<'a, S> Select<S, Range<usize>>

where S: Set + Get<'a, usize, Output = &'a <S as Set>::Elem> + View<'a>, <S as View<'a>>::Type: IntoIterator<Item = S::Output>, <S as Set>::Elem: 'a,

pub fn clone_values_into<V>(&'a self, other: &'a mut V)

where V: ViewMut<'a> + ?Sized, <V as ViewMut<'a>>::Type: Set + IntoIterator<Item = &'a mut S::Elem>, <S as Set>::Elem: Clone,

The typical way to use this function is to clone from a SelectView into a mutable S type. This function disregards indies, and simply clones the underlying target data.

Panics

This function panics if other has a length unequal to self.len().

impl<'a, S, I> Select<S, I>

where S: Set + Get<'a, usize> + View<'a>, I: AsIndexSlice,

pub fn iter( &'a self, ) -> impl Iterator<Item = (usize, <S as Get<'a, usize>>::Output)> + Clone

impl<'a, S, I> Select<S, I>

where S: Set + Get<'a, usize> + View<'a> + Sync, <S as Get<'a, usize>>::Output: Send, I: AsIndexSlice + Sync,

pub fn par_iter( &'a self, ) -> impl IndexedParallelIterator<Item = (usize, <S as Get<'a, usize>>::Output)> + Clone

impl<'a, S> Select<S, Range<usize>>

where S: Set + Get<'a, usize> + View<'a>,

pub fn iter( &'a self, ) -> impl Iterator<Item = (usize, <S as Get<'a, usize>>::Output)> + Clone

impl<'a, S> Select<S, Range<usize>>

where S: Set + Get<'a, usize> + View<'a> + Sync, <S as Get<'a, usize>>::Output: Send,

pub fn par_iter( &'a self, ) -> impl IndexedParallelIterator<Item = (usize, <S as Get<'a, usize>>::Output)> + Clone

impl<S, I> Select<S, I>

where I: AsIndexSlice,

pub fn index_iter(&self) -> Iter<'_, usize>

pub fn index_par_iter(&self) -> Iter<'_, usize>

impl<S, I> Select<S, I>

where I: AsMut<[usize]>,

pub fn index_iter_mut(&mut self) -> IterMut<'_, usize>

pub fn index_par_iter_mut(&mut self) -> IterMut<'_, usize>

Trait Implementations

impl<S: ChunkSize, I> ChunkSize for Select<S, I>

fn chunk_size(&self) -> usize

impl<S, I: Clear> Clear for Select<S, I>

fn clear(&mut self)

Remove all elements from the current set without necessarily deallocating the space previously used.

impl<S: Clone, I: Clone> Clone for Select<S, I>

fn clone(&self) -> Select<S, I>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<S: Debug, I: Debug> Debug for Select<S, I>

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

Formats the value using the given formatter.

impl<S: Dummy, I: Dummy> Dummy for Select<S, I>

unsafe fn dummy() -> Self

Constructs a potentially invalid instance of a type.

impl<'a, S, I> GetIndex<'a, Select<S, I>> for &usize

where I: AsIndexSlice, S: Get<'a, usize>,

type Output = (usize, <S as Get<'a, usize>>::Output)

fn get(self, selection: &Select<S, I>) -> Option<Self::Output>

Gets the value in the set at this index.

unsafe fn at_unchecked(self, set: &S) -> Self::Output

where Self: Sized,

Gets the value in the set at this index.

impl<'a, S, I> GetIndex<'a, Select<S, I>> for usize

where I: AsIndexSlice, S: Get<'a, usize>,

type Output = (usize, <S as Get<'a, usize>>::Output)

fn get(self, selection: &Select<S, I>) -> Option<Self::Output>

Gets the value in the set at this index.

unsafe fn at_unchecked(self, set: &S) -> Self::Output

where Self: Sized,

Gets the value in the set at this index.

impl<'a, S> GetIndex<'a, Select<S, Range<usize>>> for &usize

where S: Get<'a, usize>,

type Output = (usize, <S as Get<'a, usize>>::Output)

fn get(self, selection: &Select<S, Range<usize>>) -> Option<Self::Output>

Gets the value in the set at this index.

unsafe fn at_unchecked(self, set: &S) -> Self::Output

where Self: Sized,

Gets the value in the set at this index.

impl<'a, S> GetIndex<'a, Select<S, Range<usize>>> for usize

where S: Get<'a, usize>,

type Output = (usize, <S as Get<'a, usize>>::Output)

fn get(self, selection: &Select<S, Range<usize>>) -> Option<Self::Output>

Gets the value in the set at this index.

unsafe fn at_unchecked(self, set: &S) -> Self::Output

where Self: Sized,

Gets the value in the set at this index.

impl<'a, T, I> Index<usize> for Select<&'a [T], I>

where I: AsIndexSlice,

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

Immutably index the selection of elements from a borrowed slice.

Panics

This function panics if the index is out of bounds or if the selection is empty.

Example

use flatk::*;
let v = vec![1,2,3,4,5];
let selection = Select::new(vec![0,2,0,4], v.as_slice());
assert_eq!(3, selection[1]);
assert_eq!(1, selection[2]);

type Output = T

The returned type after indexing.

impl<'a, T> Index<usize> for Select<&'a [T], Range<usize>>

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

Immutably index the selection of elements from a borrowed slice.

Panics

This function panics if the index is out of bounds or if the selection is empty.

type Output = T

The returned type after indexing.

impl<'a, T, I> Index<usize> for Select<&'a mut [T], I>

where I: AsIndexSlice,

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

Immutably index a selection of elements from a mutably borrowed slice.

Panics

This function panics if the index is out of bounds or if the selection is empty.

Example

use flatk::*;
let mut v = vec![1,2,3,4,5];
let mut selection = Select::new(vec![3,2,0,4], v.as_mut_slice());
assert_eq!(3, selection[1]);

type Output = T

The returned type after indexing.

impl<'a, T> Index<usize> for Select<&'a mut [T], Range<usize>>

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

Immutably index a selection of elements from a mutably borrowed slice.

Panics

This function panics if the index is out of bounds or if the selection is empty.

type Output = T

The returned type after indexing.

impl<S, I> Index<usize> for Select<S, I>

where S: Index<usize> + Set + ValueType, I: AsIndexSlice,

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

Immutably index the selection.

Panics

This function panics if the index is out of bounds or if the selection is empty.

Example

use flatk::*;
let selection = Select::new(vec![0,2,0,4], Chunked2::from_flat(1..=12));
assert_eq!((0, 1..3), selection.at(0));
assert_eq!((2, 5..7), selection.at(1));
assert_eq!((0, 1..3), selection.at(2));
assert_eq!((4, 9..11), selection.at(3));

type Output = <S as Index<usize>>::Output

The returned type after indexing.

impl<S> Index<usize> for Select<S, Range<usize>>

where S: Index<usize> + Set + ValueType,

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

Immutably index the selection.

Panics

This function panics if the index is out of bounds or if the selection is empty.

type Output = <S as Index<usize>>::Output

The returned type after indexing.

impl<'a, T, I> IndexMut<usize> for Select<&'a mut [T], I>

where I: AsIndexSlice,

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

Mutably index a selection of elements from a mutably borrowed slice.

Panics

This function panics if the index is out of bounds or if the selection is empty.

Example

use flatk::*;
let mut v = vec![1,2,3,4,5];
let mut selection = Select::new(vec![4,0,2,4], v.as_mut_slice());
assert_eq!(selection[0], 5);
selection[0] = 100;
assert_eq!(selection[0], 100);
assert_eq!(selection[1], 1);
assert_eq!(selection[2], 3);
assert_eq!(selection[3], 100);

impl<'a, T> IndexMut<usize> for Select<&'a mut [T], Range<usize>>

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

Mutably index a selection of elements from a mutably borrowed slice.

Panics

This function panics if the index is out of bounds or if the selection is empty.

impl<S, I> IndexMut<usize> for Select<S, I>

where S: IndexMut<usize> + Set + ValueType, I: AsIndexSlice,

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

Mutably index the selection.

Panics

This function panics if the index is out of bounds or if the selection is empty.

Example

use flatk::*;
let mut v = vec![1,2,3,4,5];
let mut selection = Select::new(vec![0,2,0,4], v.as_mut_slice());
assert_eq!(selection[0], 1);
assert_eq!(selection[1], 3);
assert_eq!(selection[2], 1);
assert_eq!(selection[3], 5);
selection[2] = 100;
assert_eq!(selection[0], 100);
assert_eq!(selection[1], 3);
assert_eq!(selection[2], 100);
assert_eq!(selection[3], 5);

impl<S> IndexMut<usize> for Select<S, Range<usize>>

where S: IndexMut<usize> + Set + ValueType,

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

Mutably index the selection.

Panics

This function panics if the index is out of bounds or if the selection is empty.

impl<S: IntoOwned, I: IntoOwned> IntoOwned for Select<S, I>

type Owned = Select<<S as IntoOwned>::Owned, <I as IntoOwned>::Owned>

fn into_owned(self) -> Self::Owned

fn clone_into(self, target: &mut Self::Owned)

impl<S, I> IntoOwnedData for Select<S, I>

where S: IntoOwnedData,

type OwnedData = Select<<S as IntoOwnedData>::OwnedData, I>

fn into_owned_data(self) -> Self::OwnedData

fn clone_into(self, target: &mut Self::OwnedData)

impl<S, I> IsolateIndex<Select<S, I>> for Range<usize>

where I: Isolate<Range<usize>>,

Isolating a range from a selection will preserve the original target data set.

type Output = Select<S, <I as Isolate<Range<usize>>>::Output>

unsafe fn isolate_unchecked(self, selection: Select<S, I>) -> Self::Output

Attempts to isolate a value in the given set at this index.

fn try_isolate(self, selection: Select<S, I>) -> Option<Self::Output>

Attempts to isolate a value in the given set at this index.

impl<S, I> IsolateIndex<Select<S, I>> for usize

where I: Isolate<usize>, <I as Isolate<usize>>::Output: Borrow<usize>, S: Isolate<usize>,

type Output = (<I as Isolate<usize>>::Output, <S as Isolate<usize>>::Output)

unsafe fn isolate_unchecked(self, selection: Select<S, I>) -> Self::Output

Attempts to isolate a value in the given set at this index.

fn try_isolate(self, selection: Select<S, I>) -> Option<Self::Output>

Attempts to isolate a value in the given set at this index.

impl<S: MapStorage<Out>, I, Out> MapStorage<Out> for Select<S, I>

type Input = <S as MapStorage<Out>>::Input

type Output = Select<<S as MapStorage<Out>>::Output, I>

fn map_storage<F: FnOnce(Self::Input) -> Out>(self, f: F) -> Self::Output

impl<S: PartialEq, I: PartialEq> PartialEq for Select<S, I>

fn eq(&self, other: &Select<S, I>) -> 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<S, I: RemovePrefix> RemovePrefix for Select<S, I>

fn remove_prefix(&mut self, n: usize)

Remove n elements from the beginning.

impl<S, I: Reserve> Reserve for Select<S, I>

fn reserve_with_storage(&mut self, n: usize, storage_n: usize)

fn reserve(&mut self, n: usize)

impl<S: Set, I: AsIndexSlice> Set for Select<S, I>

fn len(&self) -> usize

Get the number of selected elements.

Example

use flatk::*;
let v = vec![1,2,3,4,5];
let selection = Select::new(vec![4,0,1,4], v.as_slice());
assert_eq!(4, selection.len());

type Elem = <S as Set>::Elem

Owned element of the set.

type Atom = <S as Set>::Atom

The most basic element contained by this collection. If this collection contains other collections, this type should be different than Elem.

fn is_empty(&self) -> bool

impl<S: Set> Set for Select<S, Range<usize>>

fn len(&self) -> usize

Get the number of selected elements.

Example

use flatk::*;
let v = vec![1,2,3,4,5];
let selection = Select::from_range(1..3, v.as_slice());
assert_eq!(2, selection.len());

type Elem = <S as Set>::Elem

Owned element of the set.

type Atom = <S as Set>::Atom

The most basic element contained by this collection. If this collection contains other collections, this type should be different than Elem.

fn is_empty(&self) -> bool

impl<V, I> SplitAt for Select<V, I>

where V: Set + Clone, I: SplitAt,

fn split_at(self, mid: usize) -> (Self, Self)

Split this selection into two at the given index mid.

Example

use flatk::*;
let v = vec![1,2,3,4,5];
let indices = vec![3,2,0,4,2];
let selection = Select::new(indices.as_slice(), v.as_slice());
let (l, r) = selection.split_at(2);
let mut iter_l = l.iter();
assert_eq!(Some((3, &4)), iter_l.next());
assert_eq!(Some((2, &3)), iter_l.next());
assert_eq!(None, iter_l.next());
let mut iter_r = r.iter();
assert_eq!(Some((0, &1)), iter_r.next());
assert_eq!(Some((4, &5)), iter_r.next());
assert_eq!(Some((2, &3)), iter_r.next()); // Note that 3 is shared between l and r
assert_eq!(None, iter_r.next());

impl<S: Storage, I> Storage for Select<S, I>

fn storage(&self) -> &Self::Storage

Return an immutable reference to the underlying storage type.

Example

use flatk::*;
let v = vec![1,2,3,4,5,6,7,8,9,10,11,12];
let s0 = Chunked3::from_flat(v.clone());
let s1 = Select::new(vec![1, 1, 0, 2], s0.clone());
assert_eq!(s1.storage(), &v);

type Storage = <S as Storage>::Storage

impl<S: StorageInto<T>, I, T> StorageInto<T> for Select<S, I>

Pass through the conversion for structure type Select.

type Output = Select<<S as StorageInto<T>>::Output, I>

fn storage_into(self) -> Self::Output

impl<S: StorageMut, I> StorageMut for Select<S, I>

fn storage_mut(&mut self) -> &mut Self::Storage

Return a mutable reference to the underlying storage type.

Example

use flatk::*;
let mut v = vec![1,2,3,4,5,6,7,8,9,10,11,12];
let mut s0 = Chunked3::from_flat(v.clone());
let mut s1 = Select::new(vec![1, 1, 0, 2], s0.clone());
assert_eq!(s1.storage_mut(), &mut v);

impl<'a, S: StorageView<'a>, I> StorageView<'a> for Select<S, I>

fn storage_view(&'a self) -> Self::StorageView

Return a view to the underlying storage type.

Example

use flatk::*;
let v = vec![1,2,3,4,5,6,7,8,9,10,11,12];
let s0 = Chunked3::from_flat(v.clone());
let s1 = Select::new(vec![1, 1, 0, 2], s0.clone());
assert_eq!(s1.storage_view(), v.as_slice());

type StorageView = <S as StorageView<'a>>::StorageView

impl<S, I: Truncate> Truncate for Select<S, I>

fn truncate(&mut self, new_len: usize)

impl<S, I, M> UniChunkable<M> for Select<S, I>

type Chunk = Select<S, I>

impl<'a, S, I> View<'a> for Select<S, I>

where S: View<'a>, I: AsIndexSlice,

type Type = Select<<S as View<'a>>::Type, &'a [usize]>

fn view(&'a self) -> Self::Type

impl<'a, S> View<'a> for Select<S, Range<usize>>

where S: View<'a>,

type Type = Select<<S as View<'a>>::Type, Range<usize>>

fn view(&'a self) -> Self::Type

impl<'a, S, I> ViewMut<'a> for Select<S, I>

where S: Set + ViewMut<'a>, I: AsIndexSlice,

fn view_mut(&'a mut self) -> Self::Type

Create a mutable view of this selection.

Example

use flatk::*;
let mut v = vec!['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h'];
let mut selection = Select::new(vec![1,2,4,1], v.as_mut_slice());

{
    let view = selection.view();
    let mut iter = view.iter();
    assert_eq!(Some((1, &'b')), iter.next());
    assert_eq!(Some((2, &'c')), iter.next());
    assert_eq!(Some((4, &'e')), iter.next());
    assert_eq!(Some((1, &'b')), iter.next());
    assert_eq!(None, iter.next());
}

// Change all referenced elements to 'a'.
let mut view = selection.view_mut();
for &i in view.indices.iter() {
    view.target[i] = 'a';
}

let view = selection.view();
let mut iter = view.iter();
assert_eq!(Some((1, &'a')), iter.next());
assert_eq!(Some((2, &'a')), iter.next());
assert_eq!(Some((4, &'a')), iter.next());
assert_eq!(Some((1, &'a')), iter.next());
assert_eq!(None, iter.next());

type Type = Select<<S as ViewMut<'a>>::Type, &'a [usize]>

impl<'a, S> ViewMut<'a> for Select<S, Range<usize>>

where S: Set + ViewMut<'a>,

type Type = Select<<S as ViewMut<'a>>::Type, Range<usize>>

fn view_mut(&'a mut self) -> Self::Type

impl<S: Copy, I: Copy> Copy for Select<S, I>

impl<S, I> DynamicRangeIndexType for Select<S, I>

impl<S, I> StructuralPartialEq for Select<S, I>

impl<S, I> ValueType for Select<S, I>

impl<S: Viewed, I: Viewed> Viewed for Select<S, I>