//! 为数组定义 `IntoIter` 拥有的迭代器。

use crate::{
    fmt,
    iter::{self, ExactSizeIterator, FusedIterator, TrustedLen},
    mem::{self, MaybeUninit},
    ops::Range,
    ptr,
};

/// 一个按值的 [array] 迭代器。
#[stable(feature = "array_value_iter", since = "1.51.0")]
pub struct IntoIter<T, const N: usize> {
    /// 这是我们要遍历的数组。
    ///
    /// 索引为 `i` 的元素 (尚未生成 `alive.start <= i < alive.end`) 是有效的数组条目。
    /// 索引为 `i < alive.start` 或 `i >= alive.end` 的元素已经产生，不能再访问了! 那些死元素甚至可能处于完全未初始化的状态!
    ///
    ///
    /// 因此，不变式为:
    /// - `data[alive]` 还活着 (即包含有效元素)
    /// - `data[..alive.start]` 和 `data[alive.end..]` 已死 (即，元素已被读取，不能再触摸! )
    ///
    ///
    ///
    data: [MaybeUninit<T>; N],

    /// `data` 中尚未产生的元素。
    ///
    /// Invariants:
    /// - `alive.start <= alive.end`
    /// - `alive.end <= N`
    alive: Range<usize>,
}

impl<T, const N: usize> IntoIter<T, N> {
    /// 在给定的 `array` 上创建一个新的迭代器。
    ///
    /// *Note*: [`IntoIterator` is implemented for arrays][array-into-iter] 之后，可能在 future 中不推荐使用此方法。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::array;
    ///
    /// for value in array::IntoIter::new([1, 2, 3, 4, 5]) {
    ///     // `value` 的类型在这里是 `i32`，而不是 `&i32`
    ///     let _: i32 = value;
    /// }
    /// ```
    /// [array-into-iter]: https://github.com/rust-lang/rust/pull/65819
    #[stable(feature = "array_value_iter", since = "1.51.0")]
    pub fn new(array: [T; N]) -> Self {
        // SAFETY: 此处的转换实际上是安全的。`MaybeUninit` promise 的文档:
        //
        // > `MaybeUninit<T>` 保证具有相同的大小和对齐方式
        // > 作为 `T`。
        //
        // 该文档甚至显示了从 `MaybeUninit<T>` 数组到 `T` 数组的转换。
        //
        //
        // 这样，该初始化就满足了不变性。
        //

        // FIXME(LukasKalbertodt): 一旦与 const 泛型一起使用，就可以在这里实际使用 `mem::transmute`:
        //     `mem::transmute::<[T; N], [MaybeUninit<T>; N]>(array)`
        //
        // 在此之前，我们可以使用 `mem::transmute_copy` 创建不同类型的按位副本，然后忘记 `array`，这样它就不会被丢弃。
        //
        //
        unsafe {
            let iter = Self { data: mem::transmute_copy(&array), alive: 0..N };
            mem::forget(array);
            iter
        }
    }

    /// 返回尚未屈服的所有元素的不可变切片。
    ///
    #[stable(feature = "array_value_iter", since = "1.51.0")]
    pub fn as_slice(&self) -> &[T] {
        // SAFETY: 我们知道 `alive` 中的所有元素都已正确初始化。
        unsafe {
            let slice = self.data.get_unchecked(self.alive.clone());
            MaybeUninit::slice_assume_init_ref(slice)
        }
    }

    /// 返回所有尚未屈服的元素的可变切片。
    #[stable(feature = "array_value_iter", since = "1.51.0")]
    pub fn as_mut_slice(&mut self) -> &mut [T] {
        // SAFETY: 我们知道 `alive` 中的所有元素都已正确初始化。
        unsafe {
            let slice = self.data.get_unchecked_mut(self.alive.clone());
            MaybeUninit::slice_assume_init_mut(slice)
        }
    }
}

#[stable(feature = "array_value_iter_impls", since = "1.40.0")]
impl<T, const N: usize> Iterator for IntoIter<T, N> {
    type Item = T;
    fn next(&mut self) -> Option<Self::Item> {
        // 从前面获取下一个索引。
        //
        // `alive.start` 增加 1 将保持 `alive` 的不变性。
        // 但是，由于此更改，在短时间内，活动区域不再是 `data[alive]`，而是 `data[idx..alive.end]`。
        //
        self.alive.next().map(|idx| {
            // 从数组中读取元素。
            // SAFETY: `idx` 是数组前 "alive" 区域的索引。
            // 读取此元素意味着 `data[idx]` 现在被视为已失效 (即
            // 请勿触摸)。
            // 由于 `idx` 是活动区域的开始，因此活动区域现在又是 `data[alive]`，恢复了所有不可变变量。
            //
            unsafe { self.data.get_unchecked(idx).assume_init_read() }
        })
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        let len = self.len();
        (len, Some(len))
    }

    fn count(self) -> usize {
        self.len()
    }

    fn last(mut self) -> Option<Self::Item> {
        self.next_back()
    }
}

#[stable(feature = "array_value_iter_impls", since = "1.40.0")]
impl<T, const N: usize> DoubleEndedIterator for IntoIter<T, N> {
    fn next_back(&mut self) -> Option<Self::Item> {
        // 从后面获取下一个索引。
        //
        // `alive.end` 减 1 保持 `alive` 不变。
        // 但是，由于此更改，在短时间内，活动区域不再是 `data[alive]`，而是 `data[alive.start..=idx]`。
        //
        self.alive.next_back().map(|idx| {
            // 从数组中读取元素。
            // SAFETY: `idx` 是数组前 "alive" 区域的索引。
            // 读取此元素意味着 `data[idx]` 现在被视为已失效 (即
            // 请勿触摸)。
            // 由于 `idx` 是活动区域的结尾，因此活动区域现在又是 `data[alive]`，还原了所有不可变变量。
            //
            unsafe { self.data.get_unchecked(idx).assume_init_read() }
        })
    }
}

#[stable(feature = "array_value_iter_impls", since = "1.40.0")]
impl<T, const N: usize> Drop for IntoIter<T, N> {
    fn drop(&mut self) {
        // SAFETY: 这是安全的: `as_mut_slice` 精确地返回尚未移出但仍要丢弃的元素的子切片。
        //
        //
        unsafe { ptr::drop_in_place(self.as_mut_slice()) }
    }
}

#[stable(feature = "array_value_iter_impls", since = "1.40.0")]
impl<T, const N: usize> ExactSizeIterator for IntoIter<T, N> {
    fn len(&self) -> usize {
        // 不会因 `alive.start <= alive.end` 不变而下溢。
        //
        self.alive.end - self.alive.start
    }
    fn is_empty(&self) -> bool {
        self.alive.is_empty()
    }
}

#[stable(feature = "array_value_iter_impls", since = "1.40.0")]
impl<T, const N: usize> FusedIterator for IntoIter<T, N> {}

// 迭代器确实报告了正确的长度。
// "alive" 元素的数量 (仍将产生) 是 `alive` 范围的长度。
// 在 `next` 或 `next_back` 中，此范围的长度减小。
// 在这些方法中，它总是减 1，但前提是要返回 `Some(_)`。
#[stable(feature = "array_value_iter_impls", since = "1.40.0")]
unsafe impl<T, const N: usize> TrustedLen for IntoIter<T, N> {}

#[stable(feature = "array_value_iter_impls", since = "1.40.0")]
impl<T: Clone, const N: usize> Clone for IntoIter<T, N> {
    fn clone(&self) -> Self {
        // 注意，我们实际上并不需要完全匹配相同的有效范围，因此无论 `self` 在哪里，我们都可以克隆到偏移量 0 中。
        //
        let mut new = Self { data: MaybeUninit::uninit_array(), alive: 0..0 };

        // 克隆所有活动元素。
        for (src, dst) in iter::zip(self.as_slice(), &mut new.data) {
            // 将克隆写入新阵列，然后更新其有效范围。
            // 如果克隆发生 panics，我们将正确丢弃前一个项。
            dst.write(src.clone());
            new.alive.end += 1;
        }

        new
    }
}

#[stable(feature = "array_value_iter_impls", since = "1.40.0")]
impl<T: fmt::Debug, const N: usize> fmt::Debug for IntoIter<T, N> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        // 只打印尚未屈服的元素: 我们无法再访问屈服的元素。
        //
        f.debug_tuple("IntoIter").field(&self.as_slice()).finish()
    }
}