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

## 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<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]

####
ⓘImportant traits for Box<I>

### Important traits for Box<I>

`impl<I> Iterator for Box<I> where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<R: Read + ?Sized> Read for Box<R>impl<W: Write + ?Sized> Write for Box<W>`

`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!(res == Ok(vec![2, 3]));Run

###

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

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

    use std::u16;

    let v = vec![1, 2];
    let res: Option<Vec<u16>> = v.iter().map(|&x: &u16|
        if x == u16::MAX { None }
        else { Some(x + 1) }
    ).collect();
    assert!(res == Some(vec![2, 3]));Run

###

`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 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 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 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 LinkedList<T>`

[src]

####

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

[src]

###

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

[src]

####
ⓘImportant traits for Vec<u8>

### Important traits for Vec<u8>

`impl Write for Vec<u8>`

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

[src]

###

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

[src]

####

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

[src]

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g. `str,u8` or `String,struct:Vec,test`)