std::iter::FromIterator - Rust
Description: API documentation for the Rust `FromIterator` trait in crate `std`.
Keywords: rust, rustlang, rust-lang, FromIterator

# 1.0.0[−][src]Trait std::iter::FromIterator

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

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`'s `from_iter` is rarely called explicitly, and is instead used through `Iterator`'s `collect` method. See `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]);

Run

Using `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

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

Run

## Required methods

### `fn from_iter<T>(iter: T) -> Self where
T: IntoIterator<Item = A>,`

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

Run
Loading content...

## Implementations on Foreign Types

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

#### `fn from_iter<I>(iter: I) -> HashSet<T, S> where
I: IntoIterator<Item = T>,`

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

#### `fn from_iter<T>(iter: T) -> HashMap<K, V, S> where
T: IntoIterator<Item = (K, V)>,`

Loading content...

## Implementors

### `impl FromIterator<char> for String`[src]

#### `fn from_iter<I>(iter: I) -> String where
I: IntoIterator<Item = char>,` [src]

### `impl FromIterator<()> for ()`[src]

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

#### `fn from_iter<I>(iter: I) where
I: IntoIterator<Item = ()>,` [src]

### `impl FromIterator<Box<str>> for String`[src]

#### `fn from_iter<I>(iter: I) -> String where
I: IntoIterator<Item = Box<str>>,` [src]

### `impl FromIterator<String> for String`[src]

#### `fn from_iter<I>(iter: I) -> String where
I: IntoIterator<Item = String>,` [src]

### `impl<'a> FromIterator<&'a char> for String`[src]

#### `fn from_iter<I>(iter: I) -> String where
I: IntoIterator<Item = &'a char>,` [src]

### `impl<'a> FromIterator<&'a str> for String`[src]

#### `fn from_iter<I>(iter: I) -> String where
I: IntoIterator<Item = &'a str>,` [src]

### `impl<'a> FromIterator<Cow<'a, str>> for String`[src]

#### `fn from_iter<I>(iter: I) -> String where
I: IntoIterator<Item = Cow<'a, str>>,` [src]

### `impl<'a> FromIterator<char> for Cow<'a, str>`[src]

#### `fn from_iter<I>(it: I) -> Cow<'a, str> where
I: IntoIterator<Item = char>,` [src]

### `impl<'a> FromIterator<String> for Cow<'a, str>`[src]

#### `fn from_iter<I>(it: I) -> Cow<'a, str> where
I: IntoIterator<Item = String>,` [src]

### `impl<'a, 'b> FromIterator<&'b str> for Cow<'a, str>`[src]

#### `fn from_iter<I>(it: I) -> Cow<'a, str> where
I: IntoIterator<Item = &'b str>,` [src]

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

#### `fn from_iter<I>(it: I) -> Cow<'a, [T]> where
I: IntoIterator<Item = T>,` [src]

### `impl<A> FromIterator<A> for Box<[A]>`[src]

#### `fn from_iter<T>(iter: T) -> Box<[A]> where
T: IntoIterator<Item = A>,` [src]

### `impl<A> FromIterator<A> for VecDeque<A>`[src]

#### `fn from_iter<T>(iter: T) -> VecDeque<A> where
T: IntoIterator<Item = A>,` [src]

### `impl<A, E, V> FromIterator<Result<A, E>> for Result<V, E> where
V: FromIterator<A>,` [src]

#### `fn from_iter<I>(iter: I) -> Result<V, E> where
I: IntoIterator<Item = Result<A, E>>,` [src]

Takes each element in the `Iterator`: if it is an `Err`, no further elements are taken, and the `Err` is returned. Should no `Err` occur, a container with the values of each `Result` is returned.

Here is an example which increments every integer in a vector, checking for overflow:

    let v = vec![1, 2];
    let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
        x.checked_add(1).ok_or("Overflow!")
    ).collect();
    assert_eq!(res, Ok(vec![2, 3]));

Run

Here is another example that tries to subtract one from another list of integers, this time checking for underflow:

    let v = vec![1, 2, 0];
    let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
        x.checked_sub(1).ok_or("Underflow!")
    ).collect();
    assert_eq!(res, Err("Underflow!"));

Run

Here is a variation on the previous example, showing that no further elements are taken from `iter` after the first `Err`.

    let v = vec![3, 2, 1, 10];
    let mut shared = 0;
    let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| {
        shared += x;
        x.checked_sub(2).ok_or("Underflow!")
    }).collect();
    assert_eq!(res, Err("Underflow!"));
    assert_eq!(shared, 6);

Run

Since the third element caused an underflow, no further elements were taken, so the final value of `shared` is 6 (= `3 + 2 + 1`), not 16.

### `impl<A, V> FromIterator<Option<A>> for Option<V> where
V: FromIterator<A>,` [src]

#### `fn from_iter<I>(iter: I) -> Option<V> where
I: IntoIterator<Item = Option<A>>,` [src]

Takes each element in the `Iterator`: if it is `None`, no further elements are taken, and the `None` is returned. Should no `None` occur, a container with the values of each `Option` is returned.

# Examples

Here is an example which increments every integer in a vector. We use the checked variant of `add` that returns `None` when the calculation would result in an overflow.

    let items = vec![0_u16, 1, 2];

    let res: Option<Vec<u16>> = items
        .iter()
        .map(|x| x.checked_add(1))
        .collect();

    assert_eq!(res, Some(vec![1, 2, 3]));

Run

As you can see, this will return the expected, valid items.

Here is another example that tries to subtract one from another list of integers, this time checking for underflow:

    let items = vec![2_u16, 1, 0];

    let res: Option<Vec<u16>> = items
        .iter()
        .map(|x| x.checked_sub(1))
        .collect();

    assert_eq!(res, None);

Run

Since the last element is zero, it would underflow. Thus, the resulting value is `None`.

Here is a variation on the previous example, showing that no further elements are taken from `iter` after the first `None`.

    let items = vec![3_u16, 2, 1, 10];

    let mut shared = 0;

    let res: Option<Vec<u16>> = items
        .iter()
        .map(|x| { shared += x; x.checked_sub(2) })
        .collect();

    assert_eq!(res, None);
    assert_eq!(shared, 6);

Run

Since the third element caused an underflow, no further elements were taken, so the final value of `shared` is 6 (= `3 + 2 + 1`), not 16.

### `impl<K, V> FromIterator<(K, V)> for BTreeMap<K, V> where
K: Ord,` [src]

#### `fn from_iter<T>(iter: T) -> BTreeMap<K, V> where
T: IntoIterator<Item = (K, V)>,` [src]

### `impl<K, V, S> FromIterator<(K, V)> for std::collections::HashMap<K, V, S> where
K: Eq + Hash,
S: BuildHasher + Default,` [src]

#### `fn from_iter<T: IntoIterator<Item = (K, V)>>(iter: T) -> HashMap<K, V, S>`[src]

### `impl<P: AsRef<Path>> FromIterator<P> for PathBuf`[src]

#### `fn from_iter<I: IntoIterator<Item = P>>(iter: I) -> PathBuf`[src]

### `impl<T> FromIterator<T> for BTreeSet<T> where
T: Ord,` [src]

#### `fn from_iter<I>(iter: I) -> BTreeSet<T> where
I: IntoIterator<Item = T>,` [src]

### `impl<T> FromIterator<T> for BinaryHeap<T> where
T: Ord,` [src]

#### `fn from_iter<I>(iter: I) -> BinaryHeap<T> where
I: IntoIterator<Item = T>,` [src]

### `impl<T> FromIterator<T> for LinkedList<T>`[src]

#### `fn from_iter<I>(iter: I) -> LinkedList<T> where
I: IntoIterator<Item = T>,` [src]

### `impl<T> FromIterator<T> for Rc<[T]>`[src]

#### `fn from_iter<I>(iter: I) -> Rc<[T]> where
I: IntoIterator<Item = T>,` [src]

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

Run

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.

Run

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.

Run

### `impl<T> FromIterator<T> for Arc<[T]>`[src]

#### `fn from_iter<I>(iter: I) -> Arc<[T]> where
I: IntoIterator<Item = T>,` [src]

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

# Performance characteristics

## The general case

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

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

Run

this behaves as if we wrote:

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

Run

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 `Arc<[T]>`.

## Iterators of known length

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

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

Run

### `impl<T> FromIterator<T> for Vec<T>`[src]

#### `fn from_iter<I>(iter: I) -> Vec<T> where
I: IntoIterator<Item = T>,` [src]

### `impl<T, S> FromIterator<T> for std::collections::HashSet<T, S> where
T: Eq + Hash,
S: BuildHasher + Default,` [src]

#### `fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> HashSet<T, S>`[src]

Loading content...