Trait std::iter::FromIterator

1.0.0 · source ·
pub trait FromIterator<A>: Sized {
    // Required method
    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.

If you want to create a collection from the contents of an iterator, the Iterator::collect() method is preferred. However, when you need to specify the container type, FromIterator::from_iter() can be more readable than using a turbofish (e.g. ::<Vec<_>>()). See the Iterator::collect() documentation for more examples of its use.

See also: IntoIterator.

§Examples

Basic usage:

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

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

Using FromIterator::from_iter() as a more readable alternative to Iterator::collect():

use std::collections::VecDeque;
let first = (0..10).collect::<VecDeque<i32>>();
let second = VecDeque::from_iter(0..10);

assert_eq!(first, second);
Run

Implementing FromIterator for your type:

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

Required Methods§

source

fn from_iter<T>(iter: T) -> Selfwhere T: IntoIterator<Item = A>,

Creates a value from an iterator.

See the module-level documentation for more.

§Examples
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]);
Run

Object Safety§

This trait is not object safe.

Implementors§

source§

impl FromIterator<char> for String

1.23.0 · source§

impl FromIterator<()> for ()

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());
Run
1.45.0 · source§

impl FromIterator<Box<str>> for String

1.52.0 · source§

impl FromIterator<OsString> for OsString

1.4.0 · source§

impl FromIterator<String> for String

1.17.0 · source§

impl<'a> FromIterator<&'a char> for String

source§

impl<'a> FromIterator<&'a str> for String

1.52.0 · source§

impl<'a> FromIterator<&'a OsStr> for OsString

1.19.0 · source§

impl<'a> FromIterator<Cow<'a, str>> for String

1.52.0 · source§

impl<'a> FromIterator<Cow<'a, OsStr>> for OsString

1.12.0 · source§

impl<'a> FromIterator<char> for Cow<'a, str>

1.12.0 · source§

impl<'a> FromIterator<String> for Cow<'a, str>

1.12.0 · source§

impl<'a, 'b> FromIterator<&'b str> for Cow<'a, str>

source§

impl<'a, T> FromIterator<T> for Cow<'a, [T]>where T: Clone,

source§

impl<A, E, V> FromIterator<Result<A, E>> for Result<V, E>where V: FromIterator<A>,

source§

impl<A, V> FromIterator<Option<A>> for Option<V>where V: FromIterator<A>,

1.32.0 · source§

impl<I> FromIterator<I> for Box<[I]>

source§

impl<K, V> FromIterator<(K, V)> for BTreeMap<K, V>where K: Ord,

source§

impl<K, V, S> FromIterator<(K, V)> for HashMap<K, V, S>where K: Eq + Hash, S: BuildHasher + Default,

source§

impl<P: AsRef<Path>> FromIterator<P> for PathBuf

source§

impl<T> FromIterator<T> for BTreeSet<T>where T: Ord,

source§

impl<T> FromIterator<T> for BinaryHeap<T>where T: Ord,

source§

impl<T> FromIterator<T> for LinkedList<T>

source§

impl<T> FromIterator<T> for VecDeque<T>

1.37.0 · source§

impl<T> FromIterator<T> for Rc<[T]>

1.37.0 · source§

impl<T> FromIterator<T> for Arc<[T]>

source§

impl<T> FromIterator<T> for Vec<T>

source§

impl<T, S> FromIterator<T> for HashSet<T, S>where T: Eq + Hash, S: BuildHasher + Default,