Trait FromIterator

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

Available on crate feature dep_bytemuck only.

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>,

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

impl FromIterator<char> for Box<str>

impl FromIterator<char> for String

impl FromIterator<u8> for Bytes

impl FromIterator<u8> for BytesMut

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

impl FromIterator<String> for Box<str>

impl FromIterator<String> for String

impl FromIterator<OsString> for OsString

impl FromIterator<KeyEventState> for KeyEventState

impl FromIterator<KeyModifiers> for KeyModifiers

impl FromIterator<KeyboardEnhancementFlags> for KeyboardEnhancementFlags

impl FromIterator<CreateFlags> for devela::_dep::rustix::event::epoll::CreateFlags

impl FromIterator<EventfdFlags> for EventfdFlags

impl FromIterator<PollFlags> for PollFlags

impl FromIterator<CreateFlags> for devela::_dep::rustix::fs::inotify::CreateFlags

impl FromIterator<ReadFlags> for ReadFlags

impl FromIterator<WatchFlags> for WatchFlags

impl FromIterator<Access> for Access

impl FromIterator<AtFlags> for AtFlags

impl FromIterator<FallocateFlags> for FallocateFlags

impl FromIterator<FdFlags> for FdFlags

impl FromIterator<IFlags> for IFlags

impl FromIterator<MemfdFlags> for MemfdFlags

impl FromIterator<Mode> for Mode

impl FromIterator<MountFlags> for MountFlags

impl FromIterator<MountPropagationFlags> for MountPropagationFlags

impl FromIterator<OFlags> for OFlags

impl FromIterator<RenameFlags> for RenameFlags

impl FromIterator<ResolveFlags> for ResolveFlags

impl FromIterator<SealFlags> for SealFlags

impl FromIterator<StatVfsMountFlags> for StatVfsMountFlags

impl FromIterator<StatxFlags> for StatxFlags

impl FromIterator<UnmountFlags> for UnmountFlags

impl FromIterator<XattrFlags> for XattrFlags

impl FromIterator<DupFlags> for DupFlags

impl FromIterator<ReadWriteFlags> for ReadWriteFlags

impl FromIterator<EventFlags> for EventFlags

impl FromIterator<IoringAcceptFlags> for IoringAcceptFlags

impl FromIterator<IoringAsyncCancelFlags> for IoringAsyncCancelFlags

impl FromIterator<IoringCqFlags> for IoringCqFlags

impl FromIterator<IoringCqeFlags> for IoringCqeFlags

impl FromIterator<IoringEnterFlags> for IoringEnterFlags

impl FromIterator<IoringFeatureFlags> for IoringFeatureFlags

impl FromIterator<IoringFsyncFlags> for IoringFsyncFlags

impl FromIterator<IoringMsgringFlags> for IoringMsgringFlags

impl FromIterator<IoringOpFlags> for IoringOpFlags

impl FromIterator<IoringPollFlags> for IoringPollFlags

impl FromIterator<IoringRecvFlags> for IoringRecvFlags

impl FromIterator<IoringRegisterFlags> for IoringRegisterFlags

impl FromIterator<IoringRsrcFlags> for IoringRsrcFlags

impl FromIterator<IoringSendFlags> for IoringSendFlags

impl FromIterator<IoringSetupFlags> for IoringSetupFlags

impl FromIterator<IoringSqFlags> for IoringSqFlags

impl FromIterator<IoringSqeFlags> for IoringSqeFlags

impl FromIterator<IoringTimeoutFlags> for IoringTimeoutFlags

impl FromIterator<RecvFlags> for RecvFlags

impl FromIterator<RecvmsgOutFlags> for RecvmsgOutFlags

impl FromIterator<SendFlags> for SendFlags

impl FromIterator<SocketFlags> for SocketFlags

impl FromIterator<SpliceFlags> for devela::_dep::rustix::io_uring::SpliceFlags

impl FromIterator<MapFlags> for MapFlags

impl FromIterator<MlockAllFlags> for MlockAllFlags

impl FromIterator<MlockFlags> for MlockFlags

impl FromIterator<MprotectFlags> for MprotectFlags

impl FromIterator<MremapFlags> for MremapFlags

impl FromIterator<MsyncFlags> for MsyncFlags

impl FromIterator<ProtFlags> for ProtFlags

impl FromIterator<UserfaultfdFlags> for UserfaultfdFlags

impl FromIterator<FsMountFlags> for FsMountFlags

impl FromIterator<FsOpenFlags> for FsOpenFlags

impl FromIterator<FsPickFlags> for FsPickFlags

impl FromIterator<MountAttrFlags> for MountAttrFlags

impl FromIterator<MoveMountFlags> for MoveMountFlags

impl FromIterator<OpenTreeFlags> for OpenTreeFlags

impl FromIterator<SockaddrXdpFlags> for SockaddrXdpFlags

impl FromIterator<XdpDescOptions> for XdpDescOptions

impl FromIterator<XdpOptionsFlags> for XdpOptionsFlags

impl FromIterator<XdpRingFlags> for XdpRingFlags

impl FromIterator<XdpUmemRegFlags> for XdpUmemRegFlags

impl FromIterator<PipeFlags> for PipeFlags

impl FromIterator<SpliceFlags> for devela::_dep::rustix::pipe::SpliceFlags

impl FromIterator<FloatingPointEmulationControl> for FloatingPointEmulationControl

impl FromIterator<FloatingPointExceptionMode> for FloatingPointExceptionMode

impl FromIterator<MembarrierQuery> for MembarrierQuery

impl FromIterator<PidfdFlags> for PidfdFlags

impl FromIterator<PidfdGetfdFlags> for PidfdGetfdFlags

impl FromIterator<SpeculationFeatureControl> for SpeculationFeatureControl

impl FromIterator<SpeculationFeatureState> for SpeculationFeatureState

impl FromIterator<UnalignedAccessControl> for UnalignedAccessControl

impl FromIterator<WaitOptions> for WaitOptions

impl FromIterator<WaitidOptions> for WaitidOptions

impl FromIterator<OpenptFlags> for OpenptFlags

impl FromIterator<GetRandomFlags> for GetRandomFlags

impl FromIterator<ShmOFlags> for ShmOFlags

impl FromIterator<ControlModes> for ControlModes

impl FromIterator<InputModes> for InputModes

impl FromIterator<LocalModes> for LocalModes

impl FromIterator<OutputModes> for OutputModes

impl FromIterator<CapabilitiesSecureBits> for CapabilitiesSecureBits

impl FromIterator<CapabilityFlags> for CapabilityFlags

impl FromIterator<Flags> for devela::_dep::rustix::thread::FutexFlags

impl FromIterator<TaggedAddressMode> for TaggedAddressMode

impl FromIterator<ThreadNameSpaceType> for ThreadNameSpaceType

impl FromIterator<UnshareFlags> for UnshareFlags

impl FromIterator<TimerfdFlags> for TimerfdFlags

impl FromIterator<TimerfdTimerFlags> for TimerfdTimerFlags

impl FromIterator<Channels> for Channels

impl FromIterator<Flags> for Flags

impl FromIterator<PortCap> for PortCap

impl FromIterator<PortType> for PortType

impl FromIterator<Remove> for Remove

impl<'a> FromIterator<&'a char> for Box<str>

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

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

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

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

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

impl<'a> FromIterator<Cow<'a, str>> for Box<str>

impl<'a> FromIterator<Cow<'a, str>> for String

impl<'a> FromIterator<Cow<'a, OsStr>> for OsString

impl<'a> FromIterator<char> for Cow<'a, str>

impl<'a> FromIterator<String> for Cow<'a, str>

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

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,

impl<A> FromIterator<Box<str, A>> for Box<str>

where A: Allocator,

impl<A> FromIterator<Box<str, A>> for String

where A: Allocator,

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

Available on crate feature alloc only.

impl<A> FromIterator<A> for Array

where A: AsRef<JsValue>,

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

where V: FromIterator<A>,

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.

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

where V: FromIterator<A>,

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

impl<K, V> FromIterator<(K, V)> for BTreeMap<K, V>

where K: Ord,

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, A> FromIterator<(K, V)> for devela::all::HashMap<K, V, S, A>

where K: Eq + Hash, S: BuildHasher + Default, A: Default + Allocator,

impl<P> FromIterator<P> for PathBuf

where P: AsRef<Path>,

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

impl<T> FromIterator<T> for BTreeSet<T>

where T: Ord,

impl<T> FromIterator<T> for BinaryHeap<T>

where T: Ord,

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

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

impl<T> FromIterator<T> for 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);
}

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

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

impl<T, S> FromIterator<T> for devela::_dep::_std::collections::HashSet<T, S>

where T: Eq + Hash, 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,

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.