Add array::IntoIter::{empty, from_raw_parts}

`array::IntoIter` has a bunch of really handy logic for dealing with partial arrays, but it's currently hamstrung by only being creatable from a fully-initialized array.

This PR adds two new constructors:
- a safe & const `empty`, since `[].into_iter()` gives `<T, 0>`, not `<T, N>`.
- an unsafe `from_raw_parts`, to allow experimentation with new uses.

(Slice & vec iterators don't need `from_raw_parts` because you `from_raw_parts` the slice or vec instead, but there's no useful way to made a `<[T; N]>::from_raw_parts`, so I think this is a reasonable place to have one.)

Author: scottmcm

library/core/src/array/iter.rs

@@ -84,6 +84,135 @@ impl<T, const N: usize> IntoIter<T, N> {
         IntoIterator::into_iter(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 in 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_array_assume_init)]
+    /// #![feature(maybe_uninit_uninit_array)]
+    /// 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 = MaybeUninit::uninit_array();
+    ///     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::from_raw_parts(buffer, 0..i));
+    ///                 }
+    ///             }
+    ///         }
+    ///     }
+    ///
+    ///     // SAFETY: We've initialized all N items
+    ///     unsafe { Ok(MaybeUninit::array_assume_init(buffer)) }
+    /// }
+    ///
+    /// 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]);
+    /// ```
+    #[unstable(feature = "array_into_iter_constructors", issue = "88888888")]
+    #[rustc_const_unstable(feature = "array_into_iter_constructors_const", issue = "88888888")]
+    pub const unsafe fn from_raw_parts(
+        buffer: [MaybeUninit<T>; N],
+        initialized: Range<usize>,
+    ) -> Self {
+        Self { data: buffer, alive: initialized }
+    }
+
+    /// Creates an iterator over `T` which returns no elements.
+    ///
+    /// If you just need an empty iterator, then use
+    /// [`iter::empty()`](crate::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
+    /// ```should_fail
+    /// #![feature(array_into_iter_constructors)]
+    /// use std::array::IntoIter;
+    ///
+    /// # // FIXME: use `.into_iter()` once the doc tests are in edition2021
+    /// pub fn get_bytes(b: bool) -> IntoIter<i8, 4> {
+    ///     if b {
+    ///         IntoIter::new([1, 2, 3, 4])
+    ///     } else {
+    ///         IntoIter::new([]) // 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 {
+    ///         IntoIter::new([1, 2, 3, 4])
+    ///     } else {
+    ///         IntoIter::empty()
+    ///     }
+    /// }
+    ///
+    /// assert_eq!(get_bytes(true).collect::<Vec<_>>(), vec![1, 2, 3, 4]);
+    /// assert_eq!(get_bytes(false).collect::<Vec<_>>(), vec![]);
+    /// ```
+    #[unstable(feature = "array_into_iter_constructors", issue = "88888888")]
+    pub fn empty() -> Self {
+        let buffer = MaybeUninit::uninit_array();
+        let initialized = 0..0;
+
+        // SAFETY: We're telling it that none of the elements are initialized,
+        // which is trivially true.  And ∀N: usize, 0 <= N.
+        unsafe { Self::from_raw_parts(buffer, initialized) }
+    }
+
     /// Returns an immutable slice of all elements that have not been yielded
     /// yet.
     #[stable(feature = "array_value_iter", since = "1.51.0")]