Struct flatk::Subset

pub struct Subset<S, I = Box<[usize]>> {
    pub indices: Option<I>,
    pub data: S,
}

A Set that is a non-contiguous subset of some larger collection. B can be any borrowed collection type that implements the Set, and RemovePrefix traits. For iteration of subsets, the underlying type must also implement SplitFirst and SplitAt traits.

Example

The following example shows how to create a Subset from a standard Vec.

use flatk::*;
let v = vec![1,2,3,4,5];
let subset = Subset::from_indices(vec![0,2,4], v.as_slice());
let mut subset_iter = subset.iter();
assert_eq!(Some(&1), subset_iter.next());
assert_eq!(Some(&3), subset_iter.next());
assert_eq!(Some(&5), subset_iter.next());
assert_eq!(None, subset_iter.next());

The next example shows how to create a Subset from a UniChunked collection.

use flatk::*;
let mut v = Chunked3::from_flat(vec![1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]);
let mut subset = Subset::from_indices(vec![0,2,4], v.view_mut());
{
    let subset_view = subset.view();
    let mut subset_iter = subset_view.iter();
    assert_eq!(Some(&[1,2,3]), subset_iter.next());
    assert_eq!(Some(&[7,8,9]), subset_iter.next());
    assert_eq!(Some(&[13,14,15]), subset_iter.next());
    assert_eq!(None, subset_iter.next());
}
*subset.view_mut().isolate(1) = [0; 3];
assert_eq!(&[0,0,0], subset.view().at(1));

Fields

indices: Option<I>

An optional set of indices. When this is None, the subset is considered to be entire. Empty subsets are represented by a zero length array of indices: either Some(&[]) or Some(Vec::new()).

data: S

Because Subsets modify the underlying data, it is not useful to query what the data is at any given time. For a more transparent data structure that preserves the original data set, use Select. To expose any characteristics of the contained data type, use a trait. See ChunkSize for an example.

Methods

impl<S: Set + RemovePrefix> Subset<S, Vec<usize>>

pub fn from_indices(indices: Vec<usize>, data: S) -> Self

Create a subset of elements from the original set given at the specified indices.

Example

use flatk::*;
let v = vec![1,2,3];
let subset = Subset::from_indices(vec![0,2], v.as_slice());
assert_eq!(1, subset[0]);
assert_eq!(3, subset[1]);

impl<S: Set + RemovePrefix, I: AsRef<[usize]>> Subset<S, I>

pub fn from_unique_ordered_indices(indices: I, data: S) -> Self

Create a subset of elements from the original scollection corresponding to the given indices. In contrast to Subset::from_indices, this function expects the indices to be unique and in sorted order, instead of manully making it so.

Panics

This function panics when given a collection of unsorted indices. It also panics when indices are repeated.

Example

use flatk::*;
let v = vec![0,1,2,3];
let indices = vec![1,3];

let subset_view = Subset::from_unique_ordered_indices(indices.as_slice(), v.as_slice());
assert_eq!(1, subset_view[0]);
assert_eq!(3, subset_view[1]);

let subset = Subset::from_unique_ordered_indices(indices, v.as_slice());
assert_eq!(1, subset[0]);
assert_eq!(3, subset[1]);

impl<S, I> Subset<S, I>

pub fn all(data: S) -> Self

Create a subset with all elements from the original set.

Example

use flatk::*;
let subset = Subset::<_, Vec<_>>::all(vec![1,2,3]);
let subset_view = subset.view();
let mut subset_iter = subset_view.iter();
assert_eq!(Some(&1), subset_iter.next());
assert_eq!(Some(&2), subset_iter.next());
assert_eq!(Some(&3), subset_iter.next());
assert_eq!(None, subset_iter.next());

impl<S: Set, I: AsRef<[usize]>> Subset<S, I>

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

Find an element in the subset by its index in the superset. Return the index of the element in the subset if found. Since subset indices are always in sorted order, this function performs a binary search.

Examples

In the following simple example the element 3 is found at superset index 2 which is located at index 1 in the subset.

use flatk::*;
let superset =  vec![1,2,3,4,5,6];
let subset = Subset::from_unique_ordered_indices(vec![1,2,5], superset);
assert_eq!(Some(1), subset.find_by_index(2));
assert_eq!(None, subset.find_by_index(3));

Note that the superset index refers to the indices with which the subset was created. This means that even after we have split the subset, the input indices are expected to refer to the original subset. The following example demonstrates this by splitting the original subset in the pervious example.

use flatk::*;
let superset =  vec![1,2,3,4,5,6];
let subset = Subset::from_unique_ordered_indices(vec![1,2,5], superset);
let (_, r) = subset.view().split_at(1);
assert_eq!(Some(0), r.find_by_index(2));
assert_eq!(None, r.find_by_index(3));

impl<'a, S: Set, I> Subset<S, I>

pub fn indices(&self) -> Option<&I>

Get a references to the underlying indices. If None is returned, then this subset spans the entire domain data.

pub fn into_super(self) -> S

Return the superset of this Subset. This is just the set it was created with.

impl<'a, S, I> Subset<S, I> where
    Self: Set + ViewIterator<'a>, 

pub fn clone_into_other<V: ?Sized>(&'a self, other: &'a mut V) where
    V: Set + ViewMutIterator<'a>,
    Self::Item: CloneIntoOther<<V as ViewMutIterator<'a>>::Item>, 

The typical way to use this function is to clone from a SubsetView into an owned S type.

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![0,2,4];
let subset = Subset::from_unique_ordered_indices(indices.as_slice(), v.as_slice());
let mut owned = vec![0; 4];
subset.clone_into_other(&mut owned[..3]); // Need 3 elements to avoid panics.
let mut iter_owned = owned.iter();
assert_eq!(owned, vec![1,3,5,0]);

impl<'a, S, I> Subset<S, I> where
    S: Set + View<'a>,
    I: AsRef<[usize]>, 

Important traits for SubsetIter<S, I>

impl<S, I> Iterator for SubsetIter<S, I> where
    S: SplitAt + SplitFirst + Set + Dummy,
    I: SplitFirst + Clone,
    <I as SplitFirst>::First: Borrow<usize>,  type Item = S::First;

pub fn iter(&'a self) -> SubsetIter<S::Type, &'a [usize]>

Immutably iterate over a borrowed subset.

Example

use flatk::*;
let mut v = vec![1,2,3,4,5];
let mut subset = Subset::from_indices(vec![0,2,4], v.as_mut_slice());
let mut iter = subset.iter();
assert_eq!(Some(&1), iter.next());
assert_eq!(Some(&3), iter.next());
assert_eq!(Some(&5), iter.next());
assert_eq!(None, iter.next());

impl<'a, S, I> Subset<S, I> where
    S: Set + ViewMut<'a>,
    I: AsRef<[usize]>, 

Important traits for SubsetIter<S, I>

impl<S, I> Iterator for SubsetIter<S, I> where
    S: SplitAt + SplitFirst + Set + Dummy,
    I: SplitFirst + Clone,
    <I as SplitFirst>::First: Borrow<usize>,  type Item = S::First;

pub fn iter_mut(
    &'a mut self
) -> SubsetIter<<S as ViewMut<'a>>::Type, &'a [usize]>

Mutably iterate over a borrowed subset.

Example

use flatk::*;
let mut v = vec![1,2,3,4,5];
let mut subset = Subset::from_indices(vec![0,2,4], v.as_mut_slice());
for i in subset.iter_mut() {
    *i += 1;
}
assert_eq!(v, vec![2,2,4,4,6]);

impl<S: ChunkSize, I, N: Dimension> Subset<UniChunked<S, N>, I>

pub fn inner_chunk_size(&self) -> usize

Trait Implementations

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

fn chunk_size(&self) -> usize

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

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

Returns a copy of the value.

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

Performs copy-assignment from source.

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

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

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

Formats the value using the given formatter.

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

unsafe fn dummy() -> Self

impl<T> From<Vec<T>> for Subset<Vec<T>>

fn from(v: Vec<T>) -> Subset<Vec<T>>

Performs the conversion.

impl<'a, S, O> GetIndex<'a, Subset<S, O>> for usize where
    O: AsRef<[usize]>,
    S: Get<'a, usize>, 

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

fn get(self, subset: &Subset<S, O>) -> Option<Self::Output>

impl<'a, S, I> Index<usize> for Subset<S, I> where
    S: Index<usize> + Set + ValueType,
    I: AsRef<[usize]>, 

type Output = S::Output

The returned type after indexing.

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

Immutably index the subset.

Panics

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

Example

use flatk::*;
let c = Chunked2::from_flat((1..=12).collect::<Vec<_>>());
let subset = Subset::from_indices(vec![0,2,4], c.view());
assert_eq!([1,2], subset[0]);
assert_eq!([5,6], subset[1]);
assert_eq!([9,10], subset[2]);

impl<'a, T, I> Index<usize> for Subset<&'a [T], I> where
    I: AsRef<[usize]>, 

type Output = T

The returned type after indexing.

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

Immutably index the subset.

Panics

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

Example

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

impl<'a, T, I> Index<usize> for Subset<&'a mut [T], I> where
    I: AsRef<[usize]>, 

type Output = T

The returned type after indexing.

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

Immutably index the subset.

Panics

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

Example

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

impl<'a, S, I> IndexMut<usize> for Subset<S, I> where
    S: IndexMut<usize> + Set + ValueType,
    I: AsRef<[usize]>, 

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

Mutably index the subset.

Panics

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

Example

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

impl<'a, T, I> IndexMut<usize> for Subset<&'a mut [T], I> where
    I: AsRef<[usize]>, 

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

Mutably index the subset.

Panics

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

Example

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

impl<S, I> IntoIterator for Subset<S, I> where
    S: SplitAt + SplitFirst + Set + Dummy,
    I: SplitFirst + Clone,
    <I as SplitFirst>::First: Borrow<usize>, 

type Item = S::First

The type of the elements being iterated over.

type IntoIter = SubsetIter<S, I>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Convert a Subset into an iterator.

Example

use flatk::*;
let mut s = Subset::from_unique_ordered_indices(vec![1,3,5], vec![1,2,3,4,5,6]);
let mut iter = s.view().into_iter();
assert_eq!(Some(&2), iter.next());
assert_eq!(Some(&4), iter.next());
assert_eq!(Some(&6), iter.next());
assert_eq!(None, iter.next());

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

type Owned = Subset<S::Owned, I::Owned>

fn into_owned(self) -> Self::Owned

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

impl<S, I> IntoOwnedData for Subset<S, I> where
    S: IntoOwnedData, 

type OwnedData = Subset<S::OwnedData, I>

fn into_owned_data(self) -> Self::OwnedData

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

impl<S, O> IsolateIndex<Subset<S, O>> for usize where
    O: AsRef<[usize]>,
    S: Isolate<usize>, 

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

fn try_isolate(self, subset: Subset<S, O>) -> Option<Self::Output>

impl<S, O, N: Unsigned> IsolateIndex<Subset<S, O>> for StaticRange<N> where
    Range<usize>: IsolateIndex<Subset<S, O>>, 

type Output = <Range<usize> as IsolateIndex<Subset<S, O>>>::Output

fn try_isolate(self, set: Subset<S, O>) -> Option<Self::Output>

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

fn eq(&self, other: &Subset<S, I>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Subset<S, I>) -> bool

This method tests for !=.

impl<S: Set + RemovePrefix, I: RemovePrefix + AsRef<[usize]>> RemovePrefix for Subset<S, I>

fn remove_prefix(&mut self, n: usize)

This function will panic if n is larger than self.len().

impl<S: Set, I: AsRef<[usize]>> Set for Subset<S, I>

Required for Chunked and UniChunked subsets.

type Elem = S::Elem

Owned element of the set.

type Atom = S::Atom

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

fn len(&self) -> usize

Get the length of this subset.

Example

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

fn is_empty(&self) -> bool

impl<S, I> SplitFirst for Subset<S, I> where
    I: SplitFirst + AsRef<[usize]>,
    <I as SplitFirst>::First: Borrow<usize>,
    S: Set + SplitAt + SplitFirst, 

This impl enables Subsets of Subsets

type First = S::First

fn split_first(self) -> Option<(Self::First, Self)>

Split the first element of this subset.

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

type Storage = S::Storage

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 = Subset::from_indices(vec![0, 2, 3], s0.clone());
assert_eq!(s1.storage(), &v);

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

Pass through the conversion for structure type Subset.

type Output = Subset<S::Output, I>

fn storage_into(self) -> Self::Output

impl<S: StorageMut, I> StorageMut for Subset<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 = Subset::from_indices(vec![0, 2, 3], s0.clone());
assert_eq!(s1.storage_mut(), &mut v);

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

type StorageView = S::StorageView

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 = Subset::from_indices(vec![0, 2, 3], s0.clone());
assert_eq!(s1.storage_view(), v.as_slice());

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

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

fn truncate(&mut self, new_len: usize)

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

type Chunk = Subset<S, I>

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

impl<'a, S, I> View<'a> for Subset<S, I> where
    S: View<'a>,
    I: AsRef<[usize]>, 

Required for Chunked and UniChunked subsets.

type Type = Subset<S::Type, &'a [usize]>

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

impl<'a, S, I> ViewIterator<'a> for Subset<S, I> where
    S: Set + View<'a>,
    I: AsRef<[usize]>,
    <S as View<'a>>::Type: SplitAt + SplitFirst + Set + Dummy, 

type Item = <<S as View<'a>>::Type as SplitFirst>::First

type Iter = SubsetIter<S::Type, &'a [usize]>

fn view_iter(&'a self) -> Self::Iter

impl<'a, S, I> ViewMut<'a> for Subset<S, I> where
    S: Set + ViewMut<'a>,
    I: AsRef<[usize]>, 

type Type = Subset<S::Type, &'a [usize]>

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

Create a mutable view into this subset.

Example

use flatk::*;
let mut v = vec![1,2,3,4,5];
let mut subset = Subset::from_indices(vec![0,2,4], v.as_mut_slice());
let mut view = subset.view_mut();
for i in view.iter_mut() {
    *i += 1;
}
assert_eq!(v, vec![2,2,4,4,6]);

impl<'a, S, I> ViewMutIterator<'a> for Subset<S, I> where
    S: Set + ViewMut<'a>,
    I: AsRef<[usize]>,
    <S as ViewMut<'a>>::Type: SplitAt + SplitFirst + Set + Dummy, 

type Item = <<S as ViewMut<'a>>::Type as SplitFirst>::First

type Iter = SubsetIter<S::Type, &'a [usize]>

fn view_mut_iter(&'a mut self) -> Self::Iter

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