Struct flatk::Subset

pub struct Subset<S, I = Box<[usize]>> { /* fields omitted */ }

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));

Translation independence

This struct is very similar to Chunked, with the main difference being that each index corresponds to a single element instead of a chunk starting point.

Translation independence refers to the need to ensure that indices remain valid after splitting. When the indices are owned or mutably borrowed, we could simply modify the indices when we split the subset, but when the indices are a borrowed slice, this is not possible. To resolve this, we chop the part of data below the first index to ensure that the first index serves as an offset to the rest of the indices, making the entire index array translation independent.

Because Subsets modify the underlying data storage, it can often be misleading when querying the underlying data at any given time using one of Storage, StorageMut or StorageView traits.

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.

Implementations

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

pub fn into_raw(self) -> (Option<I>, S)

Convert this subset into its internal representation.

pub unsafe fn from_raw(indices: Option<I>, data: S) -> Subset<S, I>

Construct a subset from a set of indices and a data set.

Note that independent of the value of the indices, the first element in the subset will be the first element in data, and all subsequent elements are taken from data[index - first] for each index in indices where first is the first index appearing in indices.

Safety

Constructing an invalid subset using this function isn’t itself unsafe, however calling various functions (except for Subset::validate) may be unsafe.

The given indices must be unique and in accending sorted order. All indices (minus the first) must be strictly less than the number of elements in data.

The Subset can be validated explicitly after creation using Subset::validate.

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 collection 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> Subset<S>

pub fn all<I>(data: S) -> Subset<S, I>

Create a subset with all elements from the original set.

Example

use flatk::*;
let subset = Subset::all::<Box<_>>(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());

pub fn all_def(data: S) -> Subset<S>

Create a subset with all elements from the original set.

This version of all creates the Subset type with the default index type, since it cannot be determined from the function arguments. In other words this function doesn’t require an additional generic parameter to be specified when the return type is ambiguous.

Example

use flatk::*;
let subset = Subset::all_def(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>(&'a self, other: &'a mut V) where
    V: Set + ViewMutIterator<'a> + ?Sized,
    <Self as ViewIterator<'a>>::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]>, 

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());

pub fn index_iter(&'a self) -> SubsetIndexIter<'a>

Immutably iterate over the indices stored by this subset.

The returned indices point to the superset from which this subset was created.

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.index_iter();
assert_eq!(Some(0), iter.next());
assert_eq!(Some(2), iter.next());
assert_eq!(Some(4), iter.next());
assert_eq!(None, iter.next());

This also works if the subset is entire:

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

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

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: 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

Constructs a potentially invalid instance of a type.

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>

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, 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>

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> Index<usize> for Subset<S, I> where
    S: Index<usize> + Set + ValueType,
    I: AsRef<[usize]>, 

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]);

type Output = S::Output

The returned type after indexing.

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

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]);

type Output = T

The returned type after indexing.

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

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]);

type Output = T

The returned type after indexing.

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>, 

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());

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?

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

unsafe fn isolate_unchecked(self, subset: Subset<S, O>) -> Self::Output

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

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

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

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

unsafe fn isolate_unchecked(self, set: Subset<S, O>) -> Self::Output

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

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

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

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

type Input = S::Input

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

fn map_storage<F: FnOnce(Self::Input) -> Out>(self, f: F) -> 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.

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());

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

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

Split the first element of this subset.

type First = S::First

unsafe fn split_first_unchecked(self) -> (Self::First, Self)

Split off the first element without checking if one exists.

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

type Storage = S::Storage

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>

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());

type StorageView = S::StorageView

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<'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: ViewMut<'a>,
    I: AsRef<[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]);

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

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: Copy, I: Copy> Copy for Subset<S, I>

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

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

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

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