packed_streaming_iterator

Trait Streaming

Source 
pub trait Streaming: StreamingIterator + Sized {
    // Provided methods
    fn enumerate(self) -> Enumerate<Self> { ... }
    fn zip<J: StreamingIterator>(self, j: J) -> Zip<Self, J> { ... }
    fn map_ref_and<F, R, T>(self, f: F) -> MapRefAnd<Self, F, R, T>
       where F: for<'a> FnMut(&'a Self::Item) -> RefAnd<'a, R, T> { ... }
    fn map_mut_and<F, R, T>(self, f: F) -> MapMutRefAnd<Self, F, R, T>
       where F: for<'a> FnMut(&'a mut Self::Item) -> MutRefAnd<'a, R, T> { ... }
    fn combinations_with<'a, J, F>(
        &'a mut self,
        f: F,
    ) -> MutRefAnd<'a, Self, Combinations<J, F>>
       where J: StreamingIterator,
             F: FnMut() -> J { ... }
    fn inner_combinations<T, F, S>(
        self,
        target: T,
        f: F,
        stack: S,
    ) -> InnerCombinations<T, F, S>
       where Self: Clone,
             F: Fn(&Self::Item) -> T,
             S: Stack<Item = Self>,
             T: AddAssign<T> + SubAssign<T> + Ord + Clone { ... }
    fn cfilter<F: FnMut(&Self::Item) -> bool>(self, f: F) -> CFilter<Self, F> { ... }
    fn cmap<F: FnMut(&Self::Item) -> B, B>(self, f: F) -> CMap<Self, F, B> { ... }
    fn cflat_map<F, J>(self, f: F) -> CFlatMap<Self, F, J>
       where J: StreamingIterator,
             F: FnMut(&Self::Item) -> J { ... }
}
Expand description

Supertrait implemented for any StreamingIterator, used to provide additional methods.

Provided Methods§

Source

fn enumerate(self) -> Enumerate<Self>

Creates a StreamingIterator that gives the current iteration count and Item.

The Iterator returned yields type &Enumerate<Self>, on which calling the Enumerate::unwrap method returns the tuple (n,&item) where Self::get() would have yielded &items.

if Self: StreamingIteratorMut, self.enumerate is also StreamingIteratorMut, and to retrieve tuples (usize,&mut Item), self.enumerate().next_mut().unwrap().unwrap_mut() can be called.

§Examples
use streaming_iterator::StreamingIterator;
use packed_streaming_iterator::Streaming;
 
let mut planets = streaming_iterator::convert(["Mercury".to_owned(),"Venus".to_owned(),
                                               "Earth".to_owned(),"Mars".to_owned()])
    .enumerate();

assert_eq!(planets.next()
    .unwrap() // next() returns Option<_>
    .unwrap() // call unwrap() to retrieve tuple
, (0,&"Mercury".to_owned()));
assert_eq!(planets.next().unwrap().unwrap(),(1,&"Venus".to_owned()));
Source

fn zip<J: StreamingIterator>(self, j: J) -> Zip<Self, J>

‘Zips up’ two streaming iterators into a single streaming iterator of pairs.

The new iterator returns Zip objects, on which unwrap() can be called to retrieve a tuple (&I::Item,&J::Item). It ends if either of the input iterators ends.

If both iterators are StreamingIteratorMut, self.zip(other).next_mut().unwrap().unwrap_mut() yields (&mut I::Item,&mut J::Item).

§Examples
use streaming_iterator::StreamingIterator;
use packed_streaming_iterator::Streaming;
 
let mut words = streaming_iterator::convert(["a","bcd","ef"]);
let mut numbers = streaming_iterator::convert([vec![1,2],vec![3,4,5],vec![6]]);

let mut iter = words.zip(numbers);

assert_eq!(iter.next()
    .unwrap() // next() returns Option<_>
    .unwrap() // retrieve tuple
,(&"a",&vec![1,2]));
assert_eq!(iter.next().unwrap().unwrap(),(&"bcd",&vec!(3,4,5)));
Source

fn map_ref_and<F, R, T>(self, f: F) -> MapRefAnd<Self, F, R, T>
where F: for<'a> FnMut(&'a Self::Item) -> RefAnd<'a, R, T>,

Maps a streaming iterator over one type to one over another by applying a closure.

The Reason the Iterator::map method has multiple analogues for streaming iterators (StreamingIterator::map,StreamingIterator::map_ref,…), is that with streaming iterators it is common for the mapped-to type to reference back to the original item. At the same time we cannot express the corresponding lifetime constraints:

ⓘ
F: for<'a> FnMut(&'a I::Item) -> T where T: 'a

therefore StreamingIterator::map is:

F: for<'a> FnMut(&'a I::Item) -> T

and StreamingIterator::map_ref is:

F: for<'a> Fn(&'a I::Item) -> &'a T

Streaming::map_ref_and and Streaming::map_mut_and bridge the gap by allowing the RefAnd(or MutRefAnd) type, consisting of a reference and some other value. The only remaining limitation is only being able to have a single reference back, but this can be circumvented by referencing the entire thing and later splitting it up.

§Examples
use streaming_iterator::StreamingIterator;
use packed_streaming_iterator::{Streaming,RefAnd};
 
let names = streaming_iterator::convert(["Jimmy","Carl","Jeff"]);
let mut iter = names.map_ref_and(|name| RefAnd::new(name, name.len()));

assert_eq!(iter.next().unwrap() // next() returns Option<RefAnd<'_,_,_>>
    .unwrap() // retrieve the tuple
, (&"Jimmy", &5));
assert_eq!(iter.next().unwrap().unwrap(),(&"Carl",&4));

MapRefAnd and MapMutRefAnd also implement Clone if Self and F do, correctly pointing the references to the cloned iterator.

Source

fn map_mut_and<F, R, T>(self, f: F) -> MapMutRefAnd<Self, F, R, T>
where F: for<'a> FnMut(&'a mut Self::Item) -> MutRefAnd<'a, R, T>,

Streaming::map_ref_and with a mutable pointer back for StreamingIteratorMuts.

see Streaming::map_ref_and.

If we map to another streaming iterator (if you impl StreamingIterator for MutRefAnd<'_,_,(your type)>), StreamingIteratorMut::flatten works correctly.

Source

fn combinations_with<'a, J, F>( &'a mut self, f: F, ) -> MutRefAnd<'a, Self, Combinations<J, F>>
where J: StreamingIterator, F: FnMut() -> J,

Streaming iterator over all pairs of one Item from self and one from a second iterator generated by a function.

This adapter does not consume `self`, but holds a mutable reference to it instead. Make sure self stays in scope for the existance of the adapter.

The closure gets called once for each item from self.

the yielded Items are of type MutRefAnd<'_,Self,Combinations<(other iterator),(generating function)>> and still have to be unwrap_full()’ed to get (&Self::Item, &J::Item).

§Examples
use streaming_iterator::StreamingIterator;
use packed_streaming_iterator::{Streaming,RefAnd};
 
let mut a = streaming_iterator::convert([1,2,3]);
let mut iter = a.combinations_with(|| {
    streaming_iterator::convert(['a','b','c'])
});

let result: Vec<(usize,char)> = iter.map(|combination| {
        let (ref_a,ref_b) = combination.unwrap_full();
        (*ref_a,*ref_b)
    }).cloned().collect();

assert_eq!(result, vec![(1,'a'),(1,'b'),(1,'c'),
                        (2,'a'),(2,'b'),(2,'c'),
                        (3,'a'),(3,'b'),(3,'c')]);
Source

fn inner_combinations<T, F, S>( self, target: T, f: F, stack: S, ) -> InnerCombinations<T, F, S>
where Self: Clone, F: Fn(&Self::Item) -> T, S: Stack<Item = Self>, T: AddAssign<T> + SubAssign<T> + Ord + Clone,

Streaming iterator adapter to find selections of items from one cloneable streaming iterator.

A function f is used to calculate a T for the Self::Items, where T implements std::cmp::Ord. self has to be ordered by this total ordering, from smallest to largest. T also has to implement std::ops::AddAssign<T> and std::ops::SubAssign<T>, the inverse operation.

inner_combinations then iterates over the ordered sets of Self::Items with repeats, for which the T values sum to target.

Usually, the stack argument will be Vec::new() of type Vec<Self>. In the Example T is usize.

§Examples
use streaming_iterator::StreamingIterator;
use packed_streaming_iterator::{Streaming,RefAnd};
 
let mut a = streaming_iterator::convert([vec![1],vec![0],vec![3,2],vec![4,5,6]]);
let mut iter = a.inner_combinations(4,|s| s.len(), Vec::new());

let result: Vec<_> = iter.map(|combination| { // combination: &Vec<&(type of a)>
        combination.into_iter().map(|i| i.get()
            // i is of type type_of(a), use get() to get type_of(a)::Item 
            .expect("these are guaranteed to be Some() if iter.get() returned Some().").clone())
            .collect::<Vec<_>>()
    }).cloned().collect();

assert_eq!(result, vec![vec![vec![1],vec![1],vec![1],vec![1]],
                        vec![vec![1],vec![1],vec![1],vec![0]],
                        vec![vec![1],vec![1],vec![0],vec![0]],
                        vec![vec![1],vec![1],vec![3,2]],
                        vec![vec![1],vec![0],vec![0],vec![0]],
                        vec![vec![1],vec![0],vec![3,2]],
                        vec![vec![1],vec![4,5,6]],
                        vec![vec![0],vec![0],vec![0],vec![0]],
                        vec![vec![0],vec![0],vec![3,2]],
                        vec![vec![0],vec![4,5,6]],
                        vec![vec![3,2],vec![3,2]]]);
// all ordered  combinations with a combined length of 4.

If you implement Stack for your own type such that Stack::try_push might fail, e.g. when the stack is full, inner_combinations() will correctly iterate over all combinations which consist of a number of elements that does fit.

Source

fn cfilter<F: FnMut(&Self::Item) -> bool>(self, f: F) -> CFilter<Self, F>

A copy of StreamingIterator::filter where the output derives Clone

Source

fn cmap<F: FnMut(&Self::Item) -> B, B>(self, f: F) -> CMap<Self, F, B>

A copy of StreamingIterator::map where the output derives Clone

Source

fn cflat_map<F, J>(self, f: F) -> CFlatMap<Self, F, J>
where J: StreamingIterator, F: FnMut(&Self::Item) -> J,

A copy of StreamingIterator::flat_map where the output derives Clone

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§