Struct flatk::Select[−][src]

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

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

Implementations

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

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

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

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

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

Trait Implementations

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

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Constructs a potentially invalid instance of a type. Read more

Gets the value in the set at this index.

Gets the value in the set at this index. Read more

Gets the value in the set at this index.

Gets the value in the set at this index. Read more

Gets the value in the set at this index.

Gets the value in the set at this index. Read more

Gets the value in the set at this index.

Gets the value in the set at this index. Read more

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

The returned type after indexing.

Immutably index the selection.

Panics

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

The returned type after indexing.

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

The returned type after indexing.

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.

The returned type after indexing.

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

The returned type after indexing.

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.

The returned type after indexing.

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

Mutably index the selection.

Panics

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

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

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.

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

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

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

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

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

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

This method tests for !=.

Remove n elements from the beginning.

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

Owned element of the set.

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

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

Owned element of the set.

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

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

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

Pass through the conversion for structure type Select.

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

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

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

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Return a value at the given index. This is provided as the checked version of get that will panic if the equivalent get call is None, which typically means that the given index is out of bounds. Read more

Return a value at the given index. Read more

Performs the conversion.

Produce a chunk iterator with the given stride chunk_size. One notable difference between this trait and chunks* methods on slices is that chunks_iter should panic when the underlying data cannot split into chunk_size sized chunks exactly. Read more

Unchecked version of isolate. Read more

Return a value at the given index. This is provided as the checked version of try_isolate that will panic if the equivalent try_isolate call is None, which typically means that the given index is out of bounds. Read more

The alignment of pointer.

The type for initializers.

Initializes a with the given initializer. Read more

Dereferences the given pointer. Read more

Mutably dereferences the given pointer. Read more

Drops the object pointed to by the given pointer. Read more

Should always be Self

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.