Creates a new iterator over the given array.

Creates an iterator over the elements in a partially-initialized buffer.

If you have a fully-initialized array, then use IntoIterator. But this is useful for returning partial results from unsafe code.

Safety

• The buffer[initialized] elements must all be initialized.
• The range must be canonical, with initialized.start <= initialized.end.
• The range must be in-bounds for the buffer, with initialized.end <= N. (Like how indexing [0][100..100] fails despite the range being empty.)

It's sound to have more elements initialized than mentioned, though that will most likely result in them being leaked.

Examples

#![feature(array_into_iter_constructors)]
#![feature(maybe_uninit_uninit_array_transpose)]
use std::array::IntoIter;
use std::mem::MaybeUninit;

# // Hi!  Thanks for reading the code. This is restricted to `Copy` because
# // otherwise it could leak. A fully-general version this would need a drop
# // guard to handle panics from the iterator, but this works for an example.
fn next_chunk<T: Copy, const N: usize>(
    it: &mut impl Iterator<Item = T>,
) -> Result<[T; N], IntoIter<T, N>> {
    let mut buffer = [const { MaybeUninit::uninit() }; N];
    let mut i = 0;
    while i < N {
        match it.next() {
            Some(x) => {
                buffer[i].write(x);
                i += 1;
            }
            None => {
                // SAFETY: We've initialized the first `i` items
                unsafe {
                    return Err(IntoIter::new_unchecked(buffer, 0..i));
                }
            }
        }
    }

    // SAFETY: We've initialized all N items
    unsafe { Ok(buffer.transpose().assume_init()) }
}

let r: [_; 4] = next_chunk(&mut (10..16)).unwrap();
assert_eq!(r, [10, 11, 12, 13]);
let r: IntoIter<_, 40> = next_chunk(&mut (10..16)).unwrap_err();
assert_eq!(r.collect::<Vec<_>>(), vec![10, 11, 12, 13, 14, 15]);

Creates an iterator over T which returns no elements.

If you just need an empty iterator, then use iter::empty() instead. And if you need an empty array, use [].

But this is useful when you need an array::IntoIter<T, N> specifically.

Examples

#![feature(array_into_iter_constructors)]
use std::array::IntoIter;

let empty = IntoIter::<i32, 3>::empty();
assert_eq!(empty.len(), 0);
assert_eq!(empty.as_slice(), &[]);

let empty = IntoIter::<std::convert::Infallible, 200>::empty();
assert_eq!(empty.len(), 0);

[1, 2].into_iter() and [].into_iter() have different types

#![feature(array_into_iter_constructors)]
use std::array::IntoIter;

pub fn get_bytes(b: bool) -> IntoIter<i8, 4> {
    if b {
        [1, 2, 3, 4].into_iter()
    } else {
        [].into_iter() // error[E0308]: mismatched types
    }
}

But using this method you can get an empty iterator of appropriate size:

#![feature(array_into_iter_constructors)]
use std::array::IntoIter;

pub fn get_bytes(b: bool) -> IntoIter<i8, 4> {
    if b {
        [1, 2, 3, 4].into_iter()
    } else {
        IntoIter::empty()
    }
}

assert_eq!(get_bytes(true).collect::<Vec<_>>(), vec![1, 2, 3, 4]);
assert_eq!(get_bytes(false).collect::<Vec<_>>(), vec![]);

Returns an immutable slice of all elements that have not been yielded yet.

Returns a mutable slice of all elements that have not been yielded yet.