Trait otter_api_tests::iter::FromIterator1.0.0[−][src]

pub trait FromIterator<A> {
    fn from_iter<T>(iter: T) -> Self
    where
        T: IntoIterator<Item = A>;
}
Expand description

Conversion from an Iterator.

By implementing FromIterator for a type, you define how it will be created from an iterator. This is common for types which describe a collection of some kind.

FromIterator::from_iter() is rarely called explicitly, and is instead used through Iterator::collect() method. See Iterator::collect()’s documentation for more examples.

See also: IntoIterator.

Examples

Basic usage:

use std::iter::FromIterator;

let five_fives = std::iter::repeat(5).take(5);

let v = Vec::from_iter(five_fives);

assert_eq!(v, vec![5, 5, 5, 5, 5]);

Using Iterator::collect() to implicitly use FromIterator:

let five_fives = std::iter::repeat(5).take(5);

let v: Vec<i32> = five_fives.collect();

assert_eq!(v, vec![5, 5, 5, 5, 5]);

Implementing FromIterator for your type:

use std::iter::FromIterator;

// A sample collection, that's just a wrapper over Vec<T>
#[derive(Debug)]
struct MyCollection(Vec<i32>);

// Let's give it some methods so we can create one and add things
// to it.
impl MyCollection {
    fn new() -> MyCollection {
        MyCollection(Vec::new())
    }

    fn add(&mut self, elem: i32) {
        self.0.push(elem);
    }
}

// and we'll implement FromIterator
impl FromIterator<i32> for MyCollection {
    fn from_iter<I: IntoIterator<Item=i32>>(iter: I) -> Self {
        let mut c = MyCollection::new();

        for i in iter {
            c.add(i);
        }

        c
    }
}

// Now we can make a new iterator...
let iter = (0..5).into_iter();

// ... and make a MyCollection out of it
let c = MyCollection::from_iter(iter);

assert_eq!(c.0, vec![0, 1, 2, 3, 4]);

// collect works too!

let iter = (0..5).into_iter();
let c: MyCollection = iter.collect();

assert_eq!(c.0, vec![0, 1, 2, 3, 4]);

Required methods

Creates a value from an iterator.

See the module-level documentation for more.

Examples

Basic usage:

use std::iter::FromIterator;

let five_fives = std::iter::repeat(5).take(5);

let v = Vec::from_iter(five_fives);

assert_eq!(v, vec![5, 5, 5, 5, 5]);

Implementations on Foreign Types

Collapses all unit items from an iterator into one.

This is more useful when combined with higher-level abstractions, like collecting to a Result<(), E> where you only care about errors:

use std::io::*;
let data = vec![1, 2, 3, 4, 5];
let res: Result<()> = data.iter()
    .map(|x| writeln!(stdout(), "{}", x))
    .collect();
assert!(res.is_ok());

Takes each element in the Iterator and collects it into an Rc<[T]>.

Performance characteristics

The general case

In the general case, collecting into Rc<[T]> is done by first collecting into a Vec<T>. That is, when writing the following:

let evens: Rc<[u8]> = (0..10).filter(|&x| x % 2 == 0).collect();

this behaves as if we wrote:

let evens: Rc<[u8]> = (0..10).filter(|&x| x % 2 == 0)
    .collect::<Vec<_>>() // The first set of allocations happens here.
    .into(); // A second allocation for `Rc<[T]>` happens here.

This will allocate as many times as needed for constructing the Vec<T> and then it will allocate once for turning the Vec<T> into the Rc<[T]>.

Iterators of known length

When your Iterator implements TrustedLen and is of an exact size, a single allocation will be made for the Rc<[T]>. For example:

let evens: Rc<[u8]> = (0..10).collect(); // Just a single allocation happens here.

Create a slab from an iterator of key-value pairs.

If the iterator produces duplicate keys, the previous value is replaced with the later one. The keys does not need to be sorted beforehand, and this function always takes O(n) time. Note that the returned slab will use space proportional to the largest key, so don’t use Slab with untrusted keys.

Examples


let vec = vec![(2,'a'), (6,'b'), (7,'c')];
let slab = vec.into_iter().collect::<Slab<char>>();
assert_eq!(slab.len(), 3);
assert!(slab.capacity() >= 8);
assert_eq!(slab[2], 'a');

With duplicate and unsorted keys:


let vec = vec![(20,'a'), (10,'b'), (11,'c'), (10,'d')];
let slab = vec.into_iter().collect::<Slab<char>>();
assert_eq!(slab.len(), 3);
assert_eq!(slab[10], 'd');

Create an IndexMap from the sequence of key-value pairs in the iterable.

from_iter uses the same logic as extend. See extend for more details.

Implementors