Trait IteratorFrom

1.0.0 ยท Source
pub trait IteratorFrom<A>: Sized {
    // Required method
    fn from_iter<T>(iter: T) -> Self
       where T: IntoIterator<Item = A>;
}
Expand description

๐Ÿ”„ core Conversion from an Iterator.

Re-exported from core::iter:: FromIteratorโ†’IteratorFrom.


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ยง

1.0.0 ยท Source

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

Dyn Compatibilityยง

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementorsยง

Sourceยง

impl FromIterator<char> for ByteString

1.80.0 ยท Sourceยง

impl FromIterator<char> for devela::all::Box<str>

1.0.0 ยท Sourceยง

impl FromIterator<char> for String

Sourceยง

impl FromIterator<u8> for ByteString

ยง

impl FromIterator<u8> for Bytes

ยง

impl FromIterator<u8> for BytesMut

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());
Sourceยง

impl FromIterator<ByteString> for ByteString

ยง

impl FromIterator<KeyEventState> for KeyEventState

ยง

impl FromIterator<KeyModifiers> for KeyModifiers

ยง

impl FromIterator<KeyboardEnhancementFlags> for KeyboardEnhancementFlags

ยง

impl FromIterator<Flags> for devela::_dep::ffmpeg_the_third::codec::decoder::slice::Flags

ยง

impl FromIterator<Check> for Check

ยง

impl FromIterator<Conceal> for Conceal

ยง

impl FromIterator<Flags> for devela::_dep::ffmpeg_the_third::codec::packet::Flags

ยง

impl FromIterator<Capabilities> for Capabilities

ยง

impl FromIterator<CodecProperties> for CodecProperties

ยง

impl FromIterator<Debug> for Debug

ยง

impl FromIterator<Flags> for devela::_dep::ffmpeg_the_third::codec::Flags

ยง

impl FromIterator<Flags> for devela::_dep::ffmpeg_the_third::codec::subtitle::Flags

ยง

impl FromIterator<Flags> for devela::_dep::ffmpeg_the_third::filter::Flags

ยง

impl FromIterator<Disposition> for Disposition

ยง

impl FromIterator<Flags> for devela::_dep::ffmpeg_the_third::format::Flags

ยง

impl FromIterator<Flags> for devela::_dep::ffmpeg_the_third::software::resampling::Flags

ยง

impl FromIterator<Flags> for devela::_dep::ffmpeg_the_third::software::scaling::Flags

ยง

impl FromIterator<ChannelLayoutMask> for ChannelLayoutMask

ยง

impl FromIterator<Flags> for devela::_dep::ffmpeg_the_third::util::frame::Flags

ยง

impl FromIterator<Flags> for devela::_dep::ffmpeg_the_third::util::log::Flags

ยง

impl FromIterator<Type> for Type

ยง

impl FromIterator<InitFlag> for devela::_dep::sdl2::image::InitFlag

ยง

impl FromIterator<Mod> for Mod

ยง

impl FromIterator<MessageBoxButtonFlag> for MessageBoxButtonFlag

ยง

impl FromIterator<MessageBoxFlag> for MessageBoxFlag

ยง

impl FromIterator<AllowChangeFlag> for AllowChangeFlag

ยง

impl FromIterator<InitFlag> for devela::_dep::sdl2::mixer::InitFlag

ยง

impl FromIterator<FontStyle> for FontStyle

ยง

impl FromIterator<Channels> for Channels

ยง

impl FromIterator<Table> for ArrayOfTables

1.52.0 ยท Sourceยง

impl FromIterator<OsString> for OsString

1.80.0 ยท Sourceยง

impl FromIterator<String> for devela::all::Box<str>

1.4.0 ยท Sourceยง

impl FromIterator<String> for String

ยง

impl FromIterator<ControlModes> for ControlModes

ยง

impl FromIterator<DupFlags> for DupFlags

ยง

impl FromIterator<EfdFlags> for EfdFlags

ยง

impl FromIterator<EpollCreateFlags> for EpollCreateFlags

ยง

impl FromIterator<EpollFlags> for EpollFlags

ยง

impl FromIterator<EventMask> for EventMask

ยง

impl FromIterator<FdFlags> for FdFlags

ยง

impl FromIterator<Flags> for Flags

ยง

impl FromIterator<InputModes> for InputModes

ยง

impl FromIterator<LocalModes> for LocalModes

ยง

impl FromIterator<OutputModes> for OutputModes

ยง

impl FromIterator<PortCap> for PortCap

ยง

impl FromIterator<PortType> for PortType

ยง

impl FromIterator<ReadWriteFlags> for ReadWriteFlags

ยง

impl FromIterator<Remove> for Remove

ยง

impl FromIterator<Transformations> for Transformations

ยง

impl FromIterator<WatchMask> for WatchMask

1.80.0 ยท Sourceยง

impl<'a> FromIterator<&'a char> for devela::all::Box<str>

1.17.0 ยท Sourceยง

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

Sourceยง

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

1.80.0 ยท Sourceยง

impl<'a> FromIterator<&'a str> for devela::all::Box<str>

1.0.0 ยท Sourceยง

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

ยง

impl<'a> FromIterator<&'a u8> for BytesMut

Sourceยง

impl<'a> FromIterator<&'a ByteStr> for ByteString

1.52.0 ยท Sourceยง

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

Sourceยง

impl<'a> FromIterator<&'a [u8]> for ByteString

ยง

impl<'a> FromIterator<(String, String)> for Owned<'a>

1.80.0 ยท Sourceยง

impl<'a> FromIterator<Cow<'a, str>> for devela::all::Box<str>

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>

ยง

impl<'a, 'b> FromIterator<&'b (&'b str, &'b str)> for Owned<'a>

ยง

impl<'a, 'b> FromIterator<&'b (String, String)> for Owned<'a>

1.12.0 ยท Sourceยง

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

ยง

impl<'a, 'b> FromIterator<(&'b str, &'b str)> for Owned<'a>

1.0.0 ยท Sourceยง

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

ยง

impl<A> FromIterator<<A as Array>::Item> for SmallVec<A>
where A: Array,

1.80.0 ยท Sourceยง

impl<A> FromIterator<Box<str, A>> for devela::all::Box<str>
where A: Allocator,

1.45.0 ยท Sourceยง

impl<A> FromIterator<Box<str, A>> for String
where A: Allocator,

Sourceยง

impl<A> FromIterator<A> for VecChunk<A>

Available on crate feature alloc only.
1.0.0 ยท Sourceยง

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

1.79.0 ยท Sourceยง

impl<A, EA> FromIterator<(EAโ‚, EAโ‚‚, โ€ฆ, EAโ‚™)> for (Aโ‚, Aโ‚‚, โ€ฆ, Aโ‚™)
where A: Default + Extend<EA>,

This implementation turns an iterator of tuples into a tuple of types which implement Default and Extend.

This is similar to Iterator::unzip, but is also composable with other FromIterator implementations:

let string = "1,2,123,4";

// Example given for a 2-tuple, but 1- through 12-tuples are supported
let (numbers, lengths): (Vec<_>, Vec<_>) = string
    .split(',')
    .map(|s| s.parse().map(|n: u32| (n, s.len())))
    .collect::<Result<_, _>>()?;

assert_eq!(numbers, [1, 2, 123, 4]);
assert_eq!(lengths, [1, 1, 3, 1]);

This trait is implemented for tuples up to twelve items long. The impls for 1- and 3- through 12-ary tuples were stabilized after 2-tuples, in 1.85.0.

1.0.0 ยท Sourceยง

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

ยง

impl<I> FromIterator<I> for devela::_dep::allocator_api2::boxed::Box<[I]>

1.32.0 ยท Sourceยง

impl<I> FromIterator<I> for devela::all::Box<[I]>

ยง

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

ยง

impl<K, V> FromIterator<(K, V)> for Value
where K: Into<Key>, V: Into<Value>,

ยง

impl<K, V> FromIterator<(K, V)> for InlineTable
where K: Into<Key>, V: Into<Value>,

ยง

impl<K, V> FromIterator<(K, V)> for Table
where K: Into<Key>, V: Into<Item>,

1.0.0 ยท Sourceยง

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

1.0.0 ยท Sourceยง

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

ยง

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

ยง

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

1.0.0 ยท Sourceยง

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

ยง

impl<T> FromIterator<(HeaderName, T)> for HeaderMap<T>

ยง

impl<T> FromIterator<Steal<T>> for Steal<T>

1.37.0 ยท Sourceยง

impl<T> FromIterator<T> for devela::_dep::_alloc::sync::Arc<[T]>

ยง

impl<T> FromIterator<T> for devela::_dep::allocator_api2::vec::Vec<T>

ยง

impl<T> FromIterator<T> for devela::all::Arc<[T]>

1.0.0 ยท Sourceยง

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

1.0.0 ยท Sourceยง

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

1.0.0 ยท Sourceยง

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

1.37.0 ยท Sourceยง

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

1.0.0 ยท Sourceยง

impl<T> FromIterator<T> for devela::all::Vec<T>

Collects an iterator into a Vec, commonly called via Iterator::collect()

ยงAllocation behavior

In general Vec does not guarantee any particular growth or allocation strategy. That also applies to this trait impl.

Note: This section covers implementation details and is therefore exempt from stability guarantees.

Vec may use any or none of the following strategies, depending on the supplied iterator:

  • preallocate based on Iterator::size_hint()
    • and panic if the number of items is outside the provided lower/upper bounds
  • use an amortized growth strategy similar to pushing one item at a time
  • perform the iteration in-place on the original allocation backing the iterator

The last case warrants some attention. It is an optimization that in many cases reduces peak memory consumption and improves cache locality. But when big, short-lived allocations are created, only a small fraction of their items get collected, no further use is made of the spare capacity and the resulting Vec is moved into a longer-lived structure, then this can lead to the large allocations having their lifetimes unnecessarily extended which can result in increased memory footprint.

In cases where this is an issue, the excess capacity can be discarded with Vec::shrink_to(), Vec::shrink_to_fit() or by collecting into Box<[T]> instead, which additionally reduces the size of the long-lived struct.

static LONG_LIVED: Mutex<Vec<Vec<u16>>> = Mutex::new(Vec::new());

for i in 0..10 {
    let big_temporary: Vec<u16> = (0..1024).collect();
    // discard most items
    let mut result: Vec<_> = big_temporary.into_iter().filter(|i| i % 100 == 0).collect();
    // without this a lot of unused capacity might be moved into the global
    result.shrink_to_fit();
    LONG_LIVED.lock().unwrap().push(result);
}
1.0.0 ยท Sourceยง

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

ยง

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

ยง

impl<T, F> FromIterator<F> for JoinSet<T>
where F: Future<Output = T> + Send + 'static, T: Send + 'static,

Collect an iterator of futures into a JoinSet.

This is equivalent to calling JoinSet::spawn on each element of the iterator.

ยงExamples

The main example from JoinSetโ€™s documentation can also be written using collect:

use tokio::task::JoinSet;

#[tokio::main]
async fn main() {
    let mut set: JoinSet<_> = (0..10).map(|i| async move { i }).collect();

    let mut seen = [false; 10];
    while let Some(res) = set.join_next().await {
        let idx = res.unwrap();
        seen[idx] = true;
    }

    for i in 0..10 {
        assert!(seen[i]);
    }
}
1.0.0 ยท Sourceยง

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

ยง

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

ยง

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

Sourceยง

impl<T, const CAP: usize> FromIterator<T> for ArrayVec<T, CAP>

Create an ArrayVec from an iterator.

Panics if the number of elements in the iterator exceeds the arrayvecโ€™s capacity.

ยง

impl<V> FromIterator<(usize, V)> for VecMap<V>

ยง

impl<V> FromIterator<V> for Value
where V: Into<Value>,

ยง

impl<V> FromIterator<V> for Array
where V: Into<Value>,