pub trait FromIterator<A> {
fn from_iter<T>(iter: T) -> Self
where
T: IntoIterator<Item = A>;
}
mtls
only.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]);
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]);
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);
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]);
Required Methods
fn from_iter<T>(iter: T) -> Self where
T: IntoIterator<Item = A>,
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:
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
1.52.0 · sourceimpl<'a> FromIterator<Cow<'a, OsStr>> for OsString
impl<'a> FromIterator<Cow<'a, OsStr>> for OsString
1.52.0 · sourceimpl<'a> FromIterator<&'a OsStr> for OsString
impl<'a> FromIterator<&'a OsStr> for OsString
fn from_iter<I>(iter: I) -> OsString where
I: IntoIterator<Item = &'a OsStr>,
sourceimpl<P> FromIterator<P> for PathBuf where
P: AsRef<Path>,
impl<P> FromIterator<P> for PathBuf where
P: AsRef<Path>,
fn from_iter<I>(iter: I) -> PathBuf where
I: IntoIterator<Item = P>,
1.52.0 · sourceimpl FromIterator<OsString> for OsString
impl FromIterator<OsString> for OsString
fn from_iter<I>(iter: I) -> OsString where
I: IntoIterator<Item = OsString>,
1.23.0 · sourceimpl FromIterator<()> for ()
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());
fn from_iter<I>(iter: I) where
I: IntoIterator<Item = ()>,
1.37.0 · sourceimpl<T> FromIterator<T> for Rc<[T]>
impl<T> FromIterator<T> for Rc<[T]>
sourcefn from_iter<I>(iter: I) -> Rc<[T]> where
I: IntoIterator<Item = T>,
fn from_iter<I>(iter: I) -> Rc<[T]> where
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();
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.
1.12.0 · sourceimpl<'a> FromIterator<char> for Cow<'a, str>
impl<'a> FromIterator<char> for Cow<'a, str>
1.12.0 · sourceimpl<'a, 'b> FromIterator<&'b str> for Cow<'a, str>
impl<'a, 'b> FromIterator<&'b str> for Cow<'a, str>
1.37.0 · sourceimpl<T> FromIterator<T> for Arc<[T]>
impl<T> FromIterator<T> for Arc<[T]>
sourcefn from_iter<I>(iter: I) -> Arc<[T]> where
I: IntoIterator<Item = T>,
fn from_iter<I>(iter: I) -> Arc<[T]> where
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();
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.
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.
1.12.0 · sourceimpl<'a> FromIterator<String> for Cow<'a, str>
impl<'a> FromIterator<String> for Cow<'a, str>
impl<St> FromIterator<St> for SelectAll<St> where
St: Stream + Unpin,
impl<St> FromIterator<St> for SelectAll<St> where
St: Stream + Unpin,
fn from_iter<T>(iter: T) -> SelectAll<St> where
T: IntoIterator<Item = St>,
impl<Fut> FromIterator<Fut> for SelectOk<Fut> where
Fut: TryFuture + Unpin,
impl<Fut> FromIterator<Fut> for SelectOk<Fut> where
Fut: TryFuture + Unpin,
fn from_iter<T>(iter: T) -> SelectOk<Fut> where
T: IntoIterator<Item = Fut>,
impl<Fut> FromIterator<Fut> for FuturesUnordered<Fut>
impl<Fut> FromIterator<Fut> for FuturesUnordered<Fut>
fn from_iter<I>(iter: I) -> FuturesUnordered<Fut> where
I: IntoIterator<Item = Fut>,
impl<F> FromIterator<F> for TryJoinAll<F> where
F: TryFuture,
impl<F> FromIterator<F> for TryJoinAll<F> where
F: TryFuture,
fn from_iter<T>(iter: T) -> TryJoinAll<F> where
T: IntoIterator<Item = F>,
impl<Fut> FromIterator<Fut> for SelectAll<Fut> where
Fut: Future + Unpin,
impl<Fut> FromIterator<Fut> for SelectAll<Fut> where
Fut: Future + Unpin,
fn from_iter<T>(iter: T) -> SelectAll<Fut> where
T: IntoIterator<Item = Fut>,
impl<Fut> FromIterator<Fut> for FuturesOrdered<Fut> where
Fut: Future,
impl<Fut> FromIterator<Fut> for FuturesOrdered<Fut> where
Fut: Future,
fn from_iter<T>(iter: T) -> FuturesOrdered<Fut> where
T: IntoIterator<Item = Fut>,
impl<F> FromIterator<F> for JoinAll<F> where
F: Future,
impl<F> FromIterator<F> for JoinAll<F> where
F: Future,
fn from_iter<T>(iter: T) -> JoinAll<F> where
T: IntoIterator<Item = F>,
impl<T> FromIterator<(usize, T)> for Slab<T>
impl<T> FromIterator<(usize, T)> for Slab<T>
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');