Trait Rollercoaster 

pub trait Rollercoaster: Iterator
where
    Self: Sized,
{
    // Provided methods
    fn memory(self) -> Memory<Self> { ... }
    fn group_by<P, K>(self, predicate: P) -> GroupBy<Self, P>
       where P: FnMut(&Self::Item) -> K,
             K: GroupKind { ... }
    fn append<I: Iterator<Item = Self::Item>>(self, items: I) -> Concat<Self, I> { ... }
    fn prepend<I: Iterator<Item = Self::Item>>(
        self,
        items: I,
    ) -> Concat<Self, I> { ... }
    fn unique_by<K, F>(self, identify: F) -> Unique<Self, K, F>
       where K: Hash + Eq,
             F: FnMut(&Self::Item) -> K { ... }
    fn unique(self) -> Unique<Self, Self::Item, fn(&Self::Item) -> Self::Item>
       where Self::Item: Hash + Eq + Copy { ... }
}

Adds useful extension iterators for any Iterator.

Please consult the documentation for more information.

Usage

use rollercoaster::Rollercoaster;

// Now we can use the extra
// iterator extensions on any iterator.
let result: Vec<_> = [1, 2, 2, 3, 4, 5]
    .into_iter()
    .unique()
    .group_by(|x| *x > 3)
    .map(|g| g.items)
    .collect();

assert_eq!(result, vec![
    vec![1, 2, 3],
    vec![4, 5]
])

Provided Methods

fn memory(self) -> Memory<Self>

Creates an iterator that allows remembering one or more values for the next iterations.

Why?

Sometimes you are working with an iterator in a way where you need to own values, and at the same time conditionally perform some action on them across iterations.

As an example, this is used in group_by() to allow lazy grouping.

How is this different from peekable()?

Unlike Peekable, it allows you to own the value from the current iteration and choose to use it again in the next one.

Memory also works in the opposite way, there is no peeking and instead you can check some condition in the next iteration.

Example

let mut nums = vec![1, 2, 3, 4, 5, 3].into_iter().memory();

for n in nums.by_ref() {
    // When 4 is encountered, we want to sum it with
    // everything after it.
    if n == 4 {
        nums.remember(n);
        break;
    }
}

let summed: u32 = nums.sum();
assert_eq!(summed, 12);

fn group_by<P, K>(self, predicate: P) -> GroupBy<Self, P>

where P: FnMut(&Self::Item) -> K, K: GroupKind,

Creates an iterator that group items by a predicate.

The value returned by the predicate decides which group the set of items belong to.

Note that a new group is created each time the value returned by the predicate changes. It does not group all items into a set of specific groups.

Example

let words = vec!["super", "sad", "mega", "rude", "cool", "sand"];

let grouped: Vec<_> = words
    .into_iter()
    .group_by(|w| w.starts_with("s"))
    .map(|g| g.items)
    .collect();

assert_eq!(grouped, vec![
    vec!["super", "sad"],
    vec!["mega", "rude", "cool"],
    vec!["sand"],
]);

fn append<I: Iterator<Item = Self::Item>>(self, items: I) -> Concat<Self, I>

Creates an iterator that appends another iterator to the end of the existing iterator.

Example

let a = vec!["monads", "are", "just", "monoids"];
let b = vec!["in", "the", "category", "of", "endofunctors"];

let result: Vec<_> = a
    .into_iter()
    .append(b.into_iter())
    .collect();

assert_eq!(
    result.join(" "),
    "monads are just monoids in the category of endofunctors".to_string()
);

fn prepend<I: Iterator<Item = Self::Item>>(self, items: I) -> Concat<Self, I>

Creates an iterator that prepends another iterator to the start of the existing iterator. This is the same as items.append(self)

Example

let a = vec!["opposite", "day"];
let yoda = vec!["it", "is"];

let result: Vec<_> = a
    .into_iter()
    .prepend(yoda.into_iter())
    .collect();

assert_eq!(result.join(" "), "it is opposite day".to_string());

fn unique_by<K, F>(self, identify: F) -> Unique<Self, K, F>

where K: Hash + Eq, F: FnMut(&Self::Item) -> K,

Creates an iterator that returns only unique values.

The closure F is called on each item, where the returned value K is checked against a HashSet. This means that K must implement Hash + Eq.

If you are working with simple values, you can try using unique instead.

Example

let words = vec![
    "I",
    "A",
    "am",
    "no",
    "to",
    "ha",
    "unique",
    "people",
    "me",
];

let result: Vec<_> = words
    .into_iter()
    .unique_by(|s| s.len())
    .collect();

assert_eq!(result, vec!["I", "am", "unique"]);

fn unique(self) -> Unique<Self, Self::Item, fn(&Self::Item) -> Self::Item>

where Self::Item: Hash + Eq + Copy,

Creates an iterator that returns unique values.

Each value is cloned and checked against a HashSet. This means Item must implement Eq + Hash + Copy.

If you need to specify a custom key per item, use unique_by() instead.

Example

let result: Vec<_> = vec![1, 1, 4, 5, 2, 1, 4, 3, 2]
    .into_iter()
    .unique()
    .collect();

assert_eq!(result, vec![1, 4, 5, 2, 3]);

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

impl<T: Iterator> Rollercoaster for T