1.0.0[−][src]Trait std::iter::FromIterator
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>,
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
Implementations on Foreign Types
impl<K, V, S> FromIterator<(K, V)> for HashMap<K, V, S> where
K: Eq + Hash,
S: BuildHasher + Default,
K: Eq + Hash,
S: BuildHasher + Default,
fn from_iter<T>(iter: T) -> HashMap<K, V, S> where
T: IntoIterator<Item = (K, V)>,
T: IntoIterator<Item = (K, V)>,
impl<T, S> FromIterator<T> for HashSet<T, S> where
S: BuildHasher + Default,
T: Eq + Hash,
S: BuildHasher + Default,
T: Eq + Hash,
fn from_iter<I>(iter: I) -> HashSet<T, S> where
I: IntoIterator<Item = T>,
I: IntoIterator<Item = T>,
Implementors
impl FromIterator<char> for String
[src]
fn from_iter<I>(iter: I) -> String where
I: IntoIterator<Item = char>,
[src]
I: IntoIterator<Item = char>,
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]
I: IntoIterator<Item = ()>,
impl FromIterator<String> for String
[src]
fn from_iter<I>(iter: I) -> String where
I: IntoIterator<Item = String>,
[src]
I: IntoIterator<Item = String>,
impl<'a> FromIterator<&'a char> for String
[src]
fn from_iter<I>(iter: I) -> String where
I: IntoIterator<Item = &'a char>,
[src]
I: IntoIterator<Item = &'a char>,
impl<'a> FromIterator<&'a str> for String
[src]
fn from_iter<I>(iter: I) -> String where
I: IntoIterator<Item = &'a str>,
[src]
I: IntoIterator<Item = &'a str>,
impl<'a> FromIterator<Cow<'a, str>> for String
[src]
impl<'a> FromIterator<char> for Cow<'a, str>
[src]
impl<'a> FromIterator<String> for Cow<'a, str>
[src]
impl<'a, 'b> FromIterator<&'b str> for Cow<'a, str>
[src]
impl<'a, T> FromIterator<T> for Cow<'a, [T]> where
T: Clone,
[src]
T: Clone,
impl<A> FromIterator<A> for Box<[A]>
[src]
ⓘImportant traits for Box<I>fn from_iter<T>(iter: T) -> Box<[A]> where
T: IntoIterator<Item = A>,
[src]
T: IntoIterator<Item = A>,
impl<A> FromIterator<A> for VecDeque<A>
[src]
fn from_iter<T>(iter: T) -> VecDeque<A> where
T: IntoIterator<Item = A>,
[src]
T: IntoIterator<Item = A>,
impl<A, E, V> FromIterator<Result<A, E>> for Result<V, E> where
V: FromIterator<A>,
[src]
V: FromIterator<A>,
fn from_iter<I>(iter: I) -> Result<V, E> where
I: IntoIterator<Item = Result<A, E>>,
[src]
I: IntoIterator<Item = Result<A, E>>,
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]
V: FromIterator<A>,
fn from_iter<I>(iter: I) -> Option<V> where
I: IntoIterator<Item = Option<A>>,
[src]
I: IntoIterator<Item = Option<A>>,
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]
K: Ord,
impl<K, V, S> FromIterator<(K, V)> for std::collections::HashMap<K, V, S> where
K: Eq + Hash,
S: BuildHasher + Default,
[src]
K: Eq + Hash,
S: BuildHasher + Default,
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]
T: Ord,
fn from_iter<I>(iter: I) -> BinaryHeap<T> where
I: IntoIterator<Item = T>,
[src]
I: IntoIterator<Item = T>,
impl<T> FromIterator<T> for BTreeSet<T> where
T: Ord,
[src]
T: Ord,
fn from_iter<I>(iter: I) -> BTreeSet<T> where
I: IntoIterator<Item = T>,
[src]
I: IntoIterator<Item = T>,
impl<T> FromIterator<T> for LinkedList<T>
[src]
fn from_iter<I>(iter: I) -> LinkedList<T> where
I: IntoIterator<Item = T>,
[src]
I: IntoIterator<Item = T>,
impl<T> FromIterator<T> for Rc<[T]>
[src]
fn from_iter<I>(iter: I) -> Rc<[T]> where
I: IntoIterator<Item = T>,
[src]
I: IntoIterator<Item = T>,
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]
I: IntoIterator<Item = T>,
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]
I: IntoIterator<Item = T>,
impl<T, S> FromIterator<T> for std::collections::HashSet<T, S> where
T: Eq + Hash,
S: BuildHasher + Default,
[src]
T: Eq + Hash,
S: BuildHasher + Default,