use crate::simd::{
    intrinsics, LaneCount, Mask, MaskElement, SimdCast, SimdCastPtr, SimdConstPtr, SimdMutPtr,
    SimdPartialOrd, SupportedLaneCount, Swizzle,
};
use core::convert::{TryFrom, TryInto};

/// 具有 `[T; N]` 形状但 `T` 操作的 SIMD vector。
///
/// `Simd<T, N>` 支持 `T` 以 "elementwise" 方式执行的运算符 (+、* 等)。
/// 它们从左侧和右侧获取每个索引处的元素，执行操作，然后将结果返回到相同大小的 vector 中的相同索引中。
/// 但是，`Simd` 不同于普通迭代和普通数组:
/// - `Simd<T, N>` 在没有 `break` 的情况下单步执行 `N` 操作
/// - `Simd<T, N>` 的对齐方式可以大于 `T`，以获得更好的机械一致性
///
/// 通过始终对 `Simd` 施加这些约束，可以更轻松地将逐元素操作编译为可以在并行中执行的机器指令。
///
/// ```rust
/// # #![feature(portable_simd)]
/// # use core::simd::{Simd};
/// # use core::array;
/// let a: [i32; 4] = [-2, 0, 2, 4];
/// let b = [10, 9, 8, 7];
/// let sum = array::from_fn(|i| a[i] + b[i]);
/// let prod = array::from_fn(|i| a[i] * b[i]);
///
/// // `Simd<T, N>` 实现 `From<[T; N]>`
/// let (v, w) = (Simd::from(a), Simd::from(b));
/// // 这意味着数组实现了 `Into<Simd<T, N>>`。
/// assert_eq!(v + w, sum.into());
/// assert_eq!(v * w, prod.into());
/// ```
///
/// 具有整数元素的 `Simd` 将运算符视为环绕，就好像 `T` 是 [`Wrapping<T>`]。
/// 因此，`Simd` 不实现 `wrapping_add`，因为这是默认行为。
/// 这意味着即使在 "debug" 版本中也不会出现溢出警告。
/// 对于大多数适合 `Simd` 的应用来说，换行就是 "not a bug"，甚至 "debug builds" 也不太可能容忍性能的损失。
/// 如果需要，您可能需要考虑使用显式检查算法。
/// 在整数上除以零仍然会导致 panic，因此如果无法接受，您可能需要考虑使用 `f32` 或 `f64`。
///
/// [`Wrapping<T>`]: core::num::Wrapping
///
/// # Layout
/// `Simd<T, N>` 的布局类似于 `[T; N]` (与 "shapes" 相同)，但对齐程度更高。
/// `[T; N]` 与 `T` 对齐，但 `Simd<T, N>` 将基于 `T` 和 `N` 进行对齐。
/// 因此 [`transmute`] `Simd<T, N>` 到 `[T;
/// N]` 并应优化为 "zero cost"，但反向转换可能需要编译器无法简单删除的副本。
///
/// # ABI "Features"
/// 由于 Rust 的安全保证，`Simd<T, N>` 目前通过内存传递和返回，而不是 SIMD 寄存器，除非作为优化。
/// 建议在接受 `Simd<T, N>` 或返回它的函数上使用 `#[inline]`，但代价是代码生成时间，因为内联使用 SIMD 的函数可以省略大型函数序言或结尾，从而提高速度和代码大小。
///
/// future 中可能会更正对此的需求。
///
/// 使用 `#[inline(always)]` 仍然需要格外小心。
///
/// # 带有不安全 Rust 的安全 SIMD
///
/// 使用 `Simd` 的操作通常是安全的，但有很多理由希望将 SIMD 与 `unsafe` 代码结合使用。
/// 必须注意尊重 `Simd` 和它可能被转换或派生的其他类型之间的差异。
/// 特别是 `Simd<T, N>` 的布局可能类似于 `[T;
/// N]`，并且可能允许一些变换，但对 `[T; N]` 的引用不能与对 `Simd<T, N>` 的引用互换。
/// 因此，在使用 `unsafe` Rust 通过 [raw pointers] 读写 `Simd<T, N>` 时，最好先尝试使用 [`read_unaligned`] 和 [`write_unaligned`]。这是因为:
/// - [`read`] 和 [`write`] 需要完全对齐 (在这种情况下，`Simd<T, N>` 的对齐方式)
/// - `Simd<T, N>` 通常从 [`[T]`](slice) 和其他与 `T` 对齐的类型读取或写入
/// - 组合这些操作违反了 `unsafe` 合同并将程序爆炸成一团**未定义的行为**
/// - 如果看到优化，编译器可以隐式调整布局以使未对齐的读取或写入完全对齐
/// - 如果 "unaligned" 变体在运行时对齐，大多数具有 "aligned" 和 "unaligned" 读写指令的现代处理器不会表现出性能差异
///
/// 更少的义务意味着未对齐的读取和写入不太可能使程序不可靠，并且可能与更严格的替代方案一样快。
/// 在尝试保证对齐时，[`[T]::as_simd`][as_simd] 是将 `[T]` 转换为 `[Simd<T, N>]` 的一个选项，并允许在对齐的 SIMD 主体上进行良好的操作，但在处理标量头部和尾部时可能会花费更多时间。
/// 如果这些还不够，最理想的是在使用 `unsafe` Rust 读写之前，将数据结构设计成已经对齐到 `mem::align_of::<Simd<T, N>>()`。
/// 补偿这些事实的其他方法，如首先将 `Simd` 实体化到数组或从数组中实体化，由 [`Simd::from_array`] 和 [`Simd::from_slice`] 等安全方法处理。
///
/// [`transmute`]: core::mem::transmute
/// [raw pointers]: pointer
/// [`read_unaligned`]: pointer::read_unaligned
/// [`write_unaligned`]: pointer::write_unaligned
/// [`read`]: pointer::read
/// [`write`]: pointer::write
/// [as_simd]: slice::as_simd
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
// NOTE: 以任何方式直接访问内部数组 (例如
// 通过使用 `.0` 字段语法) 或直接构造类型的实例 (即
// `let vector= Simd(array)`) 应该避免，因为它可能在 future 中的 `#[repr(simd)]` 结构体上变得非法。
//
// 在某些情况下，它还会导致 rustc 发出非法的 LLVM IR。
#[repr(simd)]
pub struct Simd<T, const N: usize>([T; N])
where
    LaneCount<N>: SupportedLaneCount,
    T: SimdElement;

impl<T, const N: usize> Simd<T, N>
where
    LaneCount<N>: SupportedLaneCount,
    T: SimdElement,
{
    /// 此 vector 中的元素数。
    pub const LANES: usize = N;

    /// 返回此 SIMD vector 中的元素数。
    ///
    /// # Examples
    ///
    /// ```
    /// # #![feature(portable_simd)]
    /// # use core::simd::u32x4;
    /// let v = u32x4::splat(0);
    /// assert_eq!(v.lanes(), 4);
    /// ```
    pub const fn lanes(&self) -> usize {
        Self::LANES
    }

    /// 创建一个所有元素都设置为给定值的新 SIMD vector。
    ///
    /// # Examples
    ///
    /// ```
    /// # #![feature(portable_simd)]
    /// # use core::simd::u32x4;
    /// let v = u32x4::splat(8);
    /// assert_eq!(v.as_array(), &[8, 8, 8, 8]);
    /// ```
    pub fn splat(value: T) -> Self {
        // 这比 `[value; N]` 更受欢迎，因为它明确地是一个 splat:
        // https://github.com/rust-lang/rust/issues/97804
        struct Splat;
        impl<const N: usize> Swizzle<1, N> for Splat {
            const INDEX: [usize; N] = [0; N];
        }
        Splat::swizzle(Simd::<T, 1>::from([value]))
    }

    /// 返回包含整个 SIMD vector 的数组引用。
    ///
    /// # Examples
    ///
    /// ```
    /// # #![feature(portable_simd)]
    /// # use core::simd::{Simd, u64x4};
    /// let v: u64x4 = Simd::from_array([0, 1, 2, 3]);
    /// assert_eq!(v.as_array(), &[0, 1, 2, 3]);
    /// ```
    pub const fn as_array(&self) -> &[T; N] {
        // SAFETY: `Simd<T, N>` 只是一个过度对齐的 `[T; N]`，末尾可能有填充，因此指向 `&[T; N]` 的指针转换是安全的。
        //
        //
        // NOTE: 这故意不只是使用 `&self.0`，有关详细信息，请参见结构体定义的注释。
        //
        //
        unsafe { &*(self as *const Self as *const [T; N]) }
    }

    /// 返回一个包含整个 SIMD vector 的可变数组引用。
    pub fn as_mut_array(&mut self) -> &mut [T; N] {
        // SAFETY: `Simd<T, N>` 只是一个过度对齐的 `[T; N]`，末尾可能有填充，因此指向 `&mut [T; N]` 的指针转换是安全的。
        //
        //
        // NOTE: 这故意不只是使用 `&mut self.0`，有关详细信息，请参见结构体定义的注释。
        //
        //
        unsafe { &mut *(self as *mut Self as *mut [T; N]) }
    }

    /// 从 `T` 数组加载 vector。
    ///
    /// 此函数是必要的，因为 `repr(simd)` 具有非 2 的幂 vectors 的填充 (在撰写本文时)。
    /// 使用填充，`read_unaligned` 将读取超过 N 个元素的数组的末尾。
    ///
    /// # Safety
    /// 读 `ptr` 一定要安全，就跟读 `<*const [T; N]>::read_unaligned` 一样。
    const unsafe fn load(ptr: *const [T; N]) -> Self {
        // 可能有更简单的方法来编写这个函数，但这应该会导致 LLVM `load <N x T>`
        //

        let mut tmp = core::mem::MaybeUninit::<Self>::uninit();
        // SAFETY: `Simd<T, N>` 始终包含 `T` 类型的 `N` 元素。
        // 它可能有不需要初始化的填充。
        // 读取 `ptr` 的安全性由调用者保证。
        unsafe {
            core::ptr::copy_nonoverlapping(ptr, tmp.as_mut_ptr().cast(), 1);
            tmp.assume_init()
        }
    }

    /// 将 vector 存储到 `T` 数组中。
    ///
    /// 请参见 `load` 以了解为什么需要此功能。
    ///
    /// # Safety
    /// 写入 `ptr` 必须是安全的，就像通过 `<*mut [T; N]>::write_unaligned` 一样。
    const unsafe fn store(self, ptr: *mut [T; N]) {
        // 可能有更简单的方法来编写这个函数，但这应该会导致 LLVM `store <N x T>`
        //

        // 创建临时文件有助于 LLVM 将 memcpy 转换为存储。
        let tmp = self;
        // SAFETY: `Simd<T, N>` 始终包含 `T` 类型的 `N` 元素。
        // 写 `ptr` 的安全性由调用者来保证。
        unsafe { core::ptr::copy_nonoverlapping(tmp.as_array(), ptr, 1) }
    }

    /// 将数组转换为 SIMD vector。
    pub const fn from_array(array: [T; N]) -> Self {
        // SAFETY: `&array` 可安全读取。
        //
        // FIXME: 我们目前使用指针加载而不是 `transmute_copy`，因为 `repr(simd)` 会导致非 2 的幂 vectors 的填充 (因此 vectors 大于数组)。
        //
        //
        // NOTE: 这故意不只是使用 `Self(array)`，有关详细信息，请参见结构体定义的注释。
        //
        unsafe { Self::load(&array) }
    }

    /// 将 SIMD vector 转换为数组。
    pub const fn to_array(self) -> [T; N] {
        let mut tmp = core::mem::MaybeUninit::uninit();
        // SAFETY: 写入 `tmp` 是安全的并对其进行初始化。
        //
        // FIXME: 我们目前使用指针存储而不是 `transmute_copy`，因为 `repr(simd)` 会导致非 2 的幂 vectors 的填充 (因此 vectors 大于数组)。
        //
        //
        // NOTE: 这故意不只是使用 `self.0`，有关详细信息，请参见结构体定义的注释。
        //
        unsafe {
            self.store(tmp.as_mut_ptr());
            tmp.assume_init()
        }
    }

    /// 将切片转换为包含 `slice[..N]` 的 SIMD vector。
    ///
    /// # Panics
    ///
    /// 如果切片的长度小于 vector 的 `Simd::N`，则会出现 panic。
    ///
    /// # Example
    ///
    /// ```
    /// # #![feature(portable_simd)]
    /// # use core::simd::u32x4;
    /// let source = vec![1, 2, 3, 4, 5, 6];
    /// let v = u32x4::from_slice(&source);
    /// assert_eq!(v.as_array(), &[1, 2, 3, 4]);
    /// ```
    #[must_use]
    pub const fn from_slice(slice: &[T]) -> Self {
        assert!(
            slice.len() >= Self::LANES,
            "slice length must be at least the number of elements"
        );
        // SAFETY: 我们刚刚检查了切片是否至少包含 `N` 个元素。
        //
        unsafe { Self::load(slice.as_ptr().cast()) }
    }

    /// 将 SIMD vector 写入切片的第一个 `N` 元素。
    ///
    /// # Panics
    ///
    /// 如果切片的长度小于 vector 的 `Simd::N`，则会出现 panic。
    ///
    /// # Example
    ///
    /// ```
    /// # #![feature(portable_simd)]
    /// # #[cfg(feature = "as_crate")] use core_simd::simd;
    /// # #[cfg(not(feature = "as_crate"))] use core::simd;
    /// # use simd::u32x4;
    /// let mut dest = vec![0; 6];
    /// let v = u32x4::from_array([1, 2, 3, 4]);
    /// v.copy_to_slice(&mut dest);
    /// assert_eq!(&dest, &[1, 2, 3, 4, 0, 0]);
    /// ```
    pub fn copy_to_slice(self, slice: &mut [T]) {
        assert!(
            slice.len() >= Self::LANES,
            "slice length must be at least the number of elements"
        );
        // SAFETY: 我们刚刚检查了切片是否至少包含 `N` 个元素。
        //
        unsafe { self.store(slice.as_mut_ptr().cast()) }
    }

    /// 将 SIMD vector 的元素按元素转换为另一个 SIMD 有效类型。
    ///
    /// 这遵循 Rust 的 `as` 转换的语义，用于在有符号和无符号之间转换整数 (将整数解释为 2s 补码，因此 `-1` 到 `U::MAX` 和 `1 << (U::BITS -1)` 成为 `I::MIN` )，以及从浮点数到整数 (截断或在极限处饱和) 每个元素。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// # #![feature(portable_simd)]
    /// # use core::simd::Simd;
    /// let floats: Simd<f32, 4> = Simd::from_array([1.9, -4.5, f32::INFINITY, f32::NAN]);
    /// let ints = floats.cast::<i32>();
    /// assert_eq!(ints, Simd::from_array([1, -4, i32::MAX, 0]));
    ///
    /// // 形式上是等价的，但 `Simd::cast` 可以优化得更好。
    /// assert_eq!(ints, Simd::from_array(floats.to_array().map(|x| x as i32)));
    ///
    /// // 浮点转换不需要往返。
    /// let floats_again = ints.cast();
    /// assert_ne!(floats, floats_again);
    /// assert_eq!(floats_again, Simd::from_array([1.0, -4.0, 2147483647.0, 0.0]));
    /// ```
    ///
    #[must_use]
    #[inline]
    pub fn cast<U: SimdCast>(self) -> Simd<U, N>
    where
        T: SimdCast,
    {
        // 安全性: 支持的类型由 SimdCast 保证
        unsafe { intrinsics::simd_as(self) }
    }

    /// 将指针的 vector 转换为另一种指针类型。
    #[must_use]
    #[inline]
    pub fn cast_ptr<U>(self) -> Simd<U, N>
    where
        T: SimdCastPtr<U>,
        U: SimdElement,
    {
        // 安全性: 支持的类型由 SimdCastPtr 保证
        unsafe { intrinsics::simd_cast_ptr(self) }
    }

    /// 向零舍入并转换为等宽整数类型，假设该值是有限的并且适合该类型。
    ///
    ///
    /// # Safety
    /// 该值必须：
    ///
    /// * 不是 NaN
    /// * 不是无限的
    /// * 在截断其小数部分后，可以在返回类型中表示
    ///
    /// 如果这些要求不可行或代价高昂，请考虑使用安全函数 [cast]，它会在转换时饱和。
    ///
    /// [cast]: Simd::cast
    ///
    #[inline]
    #[cfg_attr(miri, track_caller)] // 即使没有 panic，这也有助于 Miri 回溯
    pub unsafe fn to_int_unchecked<I>(self) -> Simd<I, N>
    where
        T: core::convert::FloatToInt<I> + SimdCast,
        I: SimdCast,
    {
        // 安全性: 支持的类型由 SimdCast 保证，调用者负责额外的不，变体
        unsafe { intrinsics::simd_cast(self) }
    }

    /// 从 `slice` 中可能不连续的索引读取以构建 SIMD vector。
    /// 如果索引越界，则从 `or` vector 中选择该元素。
    ///
    /// # Examples
    /// ```
    /// # #![feature(portable_simd)]
    /// # use core::simd::Simd;
    /// let vec: Vec<i32> = vec![10, 11, 12, 13, 14, 15, 16, 17, 18];
    /// let idxs = Simd::from_array([9, 3, 0, 5]);  // 注意越界的索引
    /// let alt = Simd::from_array([-5, -4, -3, -2]);
    ///
    /// let result = Simd::gather_or(&vec, idxs, alt);
    /// assert_eq!(result, Simd::from_array([-5, 13, 10, 15]));
    /// ```
    #[must_use]
    #[inline]
    pub fn gather_or(slice: &[T], idxs: Simd<usize, N>, or: Self) -> Self {
        Self::gather_select(slice, Mask::splat(true), idxs, or)
    }

    /// 从 `slice` 中的索引读取以构建 SIMD vector。
    /// 如果索引越界，则元素设置为 `T: Default` 给定的默认值。
    ///
    /// # Examples
    /// ```
    /// # #![feature(portable_simd)]
    /// # use core::simd::Simd;
    /// let vec: Vec<i32> = vec![10, 11, 12, 13, 14, 15, 16, 17, 18];
    /// let idxs = Simd::from_array([9, 3, 0, 5]);  // 注意越界的索引
    ///
    /// let result = Simd::gather_or_default(&vec, idxs);
    /// assert_eq!(result, Simd::from_array([0, 13, 10, 15]));
    /// ```
    #[must_use]
    #[inline]
    pub fn gather_or_default(slice: &[T], idxs: Simd<usize, N>) -> Self
    where
        T: Default,
    {
        Self::gather_or(slice, idxs, Self::splat(T::default()))
    }

    /// 从 `slice` 中的索引读取以构建 SIMD vector。
    /// 掩码 `启用` 所有 `true` 索引并禁用所有 `false` 索引。
    /// 如果索引被禁用或越界，则从 `or` vector 中选择元素。
    ///
    /// # Examples
    /// ```
    /// # #![feature(portable_simd)]
    /// # use core::simd::{Simd, Mask};
    /// let vec: Vec<i32> = vec![10, 11, 12, 13, 14, 15, 16, 17, 18];
    /// let idxs = Simd::from_array([9, 3, 0, 5]); // 包括越界索引
    /// let alt = Simd::from_array([-5, -4, -3, -2]);
    /// let enable = Mask::from_array([true, true, true, false]); // 包括一个屏蔽元素
    ///
    /// let result = Simd::gather_select(&vec, enable, idxs, alt);
    /// assert_eq!(result, Simd::from_array([-5, 13, 10, -2]));
    /// ```
    #[must_use]
    #[inline]
    pub fn gather_select(
        slice: &[T],
        enable: Mask<isize, N>,
        idxs: Simd<usize, N>,
        or: Self,
    ) -> Self {
        let enable: Mask<isize, N> = enable & idxs.simd_lt(Simd::splat(slice.len()));
        // 安全性: 我们屏蔽了越界指数。
        unsafe { Self::gather_select_unchecked(slice, enable, idxs, or) }
    }

    /// 从 `slice` 中的索引读取以构建 SIMD vector。
    /// 掩码 `启用` 所有 `true` 索引并禁用所有 `false` 索引。
    /// 如果禁用索引，则从 `or` vector 中选择元素。
    ///
    /// # Safety
    ///
    /// 使用 `enable`d 越界索引调用这个函数是 *[未定义的行为][undefined behavior]*，即使结果值没有被使用。
    ///
    /// # Examples
    ///
    /// ```
    /// # #![feature(portable_simd)]
    /// # #[cfg(feature = "as_crate")] use core_simd::simd;
    /// # #[cfg(not(feature = "as_crate"))] use core::simd;
    /// # use simd::{Simd, SimdPartialOrd, Mask};
    /// let vec: Vec<i32> = vec![10, 11, 12, 13, 14, 15, 16, 17, 18];
    /// let idxs = Simd::from_array([9, 3, 0, 5]); // 包括越界索引
    /// let alt = Simd::from_array([-5, -4, -3, -2]);
    /// let enable = Mask::from_array([true, true, true, false]); // 包括一个屏蔽元素
    /// // 如果用这个掩码来收集，这是不合理的。让我们解决这个问题。
    /// let enable = enable & idxs.simd_lt(Simd::splat(vec.len()));
    ///
    /// // 越界索引已被屏蔽，因此现在可以安全收集了。
    /// let result = unsafe { Simd::gather_select_unchecked(&vec, enable, idxs, alt) };
    /// assert_eq!(result, Simd::from_array([-5, 13, 10, -2]));
    /// ```
    /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
    #[must_use]
    #[inline]
    #[cfg_attr(miri, track_caller)] // 即使没有 panic，这也有助于 Miri 回溯
    pub unsafe fn gather_select_unchecked(
        slice: &[T],
        enable: Mask<isize, N>,
        idxs: Simd<usize, N>,
        or: Self,
    ) -> Self {
        let base_ptr = Simd::<*const T, N>::splat(slice.as_ptr());
        // Ferris 原谅我，我在这里做了指针运算。
        let ptrs = base_ptr.wrapping_add(idxs);
        // 安全性: 调用者负责确定索引是否可以读取
        unsafe { Self::gather_select_ptr(ptrs, enable, or) }
    }

    /// 从指针逐元素读取到 SIMD vector。
    ///
    /// # Safety
    ///
    /// 每次读取必须满足与 [`core::ptr::read`] 相同的条件。
    ///
    /// # Example
    /// ```
    /// # #![feature(portable_simd)]
    /// # #[cfg(feature = "as_crate")] use core_simd::simd;
    /// # #[cfg(not(feature = "as_crate"))] use core::simd;
    /// # use simd::{Simd, SimdConstPtr};
    /// let values = [6, 2, 4, 9];
    /// let offsets = Simd::from_array([1, 0, 0, 3]);
    /// let source = Simd::splat(values.as_ptr()).wrapping_add(offsets);
    /// let gathered = unsafe { Simd::gather_ptr(source) };
    /// assert_eq!(gathered, Simd::from_array([2, 6, 6, 9]));
    /// ```
    #[must_use]
    #[inline]
    #[cfg_attr(miri, track_caller)] // 即使没有 panic，这也有助于 Miri 回溯
    pub unsafe fn gather_ptr(source: Simd<*const T, N>) -> Self
    where
        T: Default,
    {
        // TODO: 添加一个不使用直通 vector 的内部函数，并删除 T: Default bound Safety: The caller is responsible for upholding all invariants
        //
        unsafe { Self::gather_select_ptr(source, Mask::splat(true), Self::default()) }
    }

    /// 有条件地从指针逐元素读取到 SIMD vector。
    /// 掩码 `启用` 所有 `true` 指针并禁用所有 `false` 指针。
    /// 如果禁用指针，则从 `or` vector 中选择元素，并且不执行读取。
    ///
    /// # Safety
    ///
    /// 启用的元素必须满足与 [`core::ptr::read`] 相同的条件。
    ///
    /// # Example
    ///
    /// ```
    /// # #![feature(portable_simd)]
    /// # #[cfg(feature = "as_crate")] use core_simd::simd;
    /// # #[cfg(not(feature = "as_crate"))] use core::simd;
    /// # use simd::{Mask, Simd, SimdConstPtr};
    /// let values = [6, 2, 4, 9];
    /// let enable = Mask::from_array([true, true, false, true]);
    /// let offsets = Simd::from_array([1, 0, 0, 3]);
    /// let source = Simd::splat(values.as_ptr()).wrapping_add(offsets);
    /// let gathered = unsafe { Simd::gather_select_ptr(source, enable, Simd::splat(0)) };
    /// assert_eq!(gathered, Simd::from_array([2, 6, 0, 9]));
    /// ```
    #[must_use]
    #[inline]
    #[cfg_attr(miri, track_caller)] // 即使没有 panic，这也有助于 Miri 回溯
    pub unsafe fn gather_select_ptr(
        source: Simd<*const T, N>,
        enable: Mask<isize, N>,
        or: Self,
    ) -> Self {
        // 安全性: 调用者负责维护所有不，变体
        unsafe { intrinsics::simd_gather(or, source, enable.to_int()) }
    }

    /// 将 SIMD vector 中的值写入 `slice` 中可能不连续的索引。
    /// 如果索引越界，则写入会被抑制而不会出现 panic。
    /// 如果分散的 vector 中的两个元素将写入同一索引，则只有最后一个元素才能保证实际写入。
    ///
    /// # Examples
    ///
    /// ```
    /// # #![feature(portable_simd)]
    /// # use core::simd::Simd;
    /// let mut vec: Vec<i32> = vec![10, 11, 12, 13, 14, 15, 16, 17, 18];
    /// let idxs = Simd::from_array([9, 3, 0, 0]); // 注意重复索引。
    /// let vals = Simd::from_array([-27, 82, -41, 124]);
    ///
    /// vals.scatter(&mut vec, idxs); // 两次逻辑写入意味着最后获胜。
    /// assert_eq!(vec, vec![124, 11, 12, 82, 14, 15, 16, 17, 18]);
    /// ```
    #[inline]
    pub fn scatter(self, slice: &mut [T], idxs: Simd<usize, N>) {
        self.scatter_select(slice, Mask::splat(true), idxs)
    }

    /// 将值从 SIMD vector 写入 `slice` 中的多个可能不连续的索引。
    /// 掩码 `启用` 所有 `true` 索引并禁用所有 `false` 索引。
    /// 如果启用的索引越界，则写入会被抑制而不会出现 panic。
    /// 如果分散的 vector 中的两个启用元素将写入同一索引，则只有最后一个元素可以保证实际写入。
    ///
    /// # Examples
    ///
    /// ```
    /// # #![feature(portable_simd)]
    /// # #[cfg(feature = "as_crate")] use core_simd::simd;
    /// # #[cfg(not(feature = "as_crate"))] use core::simd;
    /// # use simd::{Simd, Mask};
    /// let mut vec: Vec<i32> = vec![10, 11, 12, 13, 14, 15, 16, 17, 18];
    /// let idxs = Simd::from_array([9, 3, 0, 0]); // 包括越界索引
    /// let vals = Simd::from_array([-27, 82, -41, 124]);
    /// let enable = Mask::from_array([true, true, true, false]); // 包括一个屏蔽元素
    ///
    /// vals.scatter_select(&mut vec, enable, idxs); // 最后一次写入被屏蔽，因此被省略。
    /// assert_eq!(vec, vec![-41, 11, 12, 82, 14, 15, 16, 17, 18]);
    /// ```
    #[inline]
    pub fn scatter_select(self, slice: &mut [T], enable: Mask<isize, N>, idxs: Simd<usize, N>) {
        let enable: Mask<isize, N> = enable & idxs.simd_lt(Simd::splat(slice.len()));
        // 安全性: 我们屏蔽了越界指数。
        unsafe { self.scatter_select_unchecked(slice, enable, idxs) }
    }

    /// 将值从 SIMD vector 写入 `slice` 中的多个可能不连续的索引。
    /// 掩码 `启用` 所有 `true` 索引并禁用所有 `false` 索引。
    /// 如果分散的 vector 中的两个启用元素将写入同一索引，则只有最后一个元素可以保证实际写入。
    ///
    ///
    /// # Safety
    ///
    /// 使用启用的越界索引调用此函数是 *[undefined 行为]*，并可能导致内存损坏。
    ///
    /// # Examples
    ///
    /// ```
    /// # #![feature(portable_simd)]
    /// # #[cfg(feature = "as_crate")] use core_simd::simd;
    /// # #[cfg(not(feature = "as_crate"))] use core::simd;
    /// # use simd::{Simd, SimdPartialOrd, Mask};
    /// let mut vec: Vec<i32> = vec![10, 11, 12, 13, 14, 15, 16, 17, 18];
    /// let idxs = Simd::from_array([9, 3, 0, 0]);
    /// let vals = Simd::from_array([-27, 82, -41, 124]);
    /// let enable = Mask::from_array([true, true, true, false]); // 屏蔽最终索引
    /// // 如果用这个掩码来分散，这是不合理的。让我们解决这个问题。
    /// let enable = enable & idxs.simd_lt(Simd::splat(vec.len()));
    ///
    /// // 我们已经屏蔽了 OOB 索引，所以现在可以安全地分散。
    /// unsafe { vals.scatter_select_unchecked(&mut vec, enable, idxs); }
    /// // 对索引 0 的第二次写入被屏蔽，因此被省略。
    /// assert_eq!(vec, vec![-41, 11, 12, 82, 14, 15, 16, 17, 18]);
    /// ```
    /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
    #[inline]
    #[cfg_attr(miri, track_caller)] // 即使没有 panic，这也有助于 Miri 回溯
    pub unsafe fn scatter_select_unchecked(
        self,
        slice: &mut [T],
        enable: Mask<isize, N>,
        idxs: Simd<usize, N>,
    ) {
        // 安全性: 此块适用于从 &mut 'a [T] 派生的 *mut T，这意味着它在 Rust 的借用模型中很微妙，大约在 2021 年:
        // &mut 'a [T] 断言唯一性，因此派生 &'a [T] 会使活着的 *mut Ts 无效！
        // 尽管这个块在很大程度上是安全的方法，但它必须完全采用这种方式来防止在原始 ptr 处于活动状态时使其无效。
        //
        // 因此，进入此块需要所有要使用的值都已经准备好：
        // 0. 我们要写入的 idxs，用于构造掩码。
        // 1. 启用，这取决于初始 `&'a [T]` 和 idxs。
        // 2. 要分散 (self) 的实际值。
        // 3. &mut [T] 将成为我们的基础 ptr。
        //
        unsafe {
            // 现在进入 ☢️ `*mut T` 区域
            let base_ptr = Simd::<*mut T, N>::splat(slice.as_mut_ptr());
            // Ferris 原谅我，我在这里做了指针运算。
            let ptrs = base_ptr.wrapping_add(idxs);
            // ptr 已被边界屏蔽以防止内存不安全写入 insha'allah
            self.scatter_select_ptr(ptrs, enable);
            // 清除 ☢️ `*mut T` 区域
        }
    }

    /// 按元素将指针写入 SIMD vector。
    ///
    /// # Safety
    ///
    /// 每次写入必须满足与 [`core::ptr::write`] 相同的条件。
    ///
    /// # Example
    /// ```
    /// # #![feature(portable_simd)]
    /// # #[cfg(feature = "as_crate")] use core_simd::simd;
    /// # #[cfg(not(feature = "as_crate"))] use core::simd;
    /// # use simd::{Simd, SimdMutPtr};
    /// let mut values = [0; 4];
    /// let offset = Simd::from_array([3, 2, 1, 0]);
    /// let ptrs = Simd::splat(values.as_mut_ptr()).wrapping_add(offset);
    /// unsafe { Simd::from_array([6, 3, 5, 7]).scatter_ptr(ptrs); }
    /// assert_eq!(values, [7, 5, 3, 6]);
    /// ```
    #[inline]
    #[cfg_attr(miri, track_caller)] // 即使没有 panic，这也有助于 Miri 回溯
    pub unsafe fn scatter_ptr(self, dest: Simd<*mut T, N>) {
        // 安全性: 调用者负责维护所有不，变体
        unsafe { self.scatter_select_ptr(dest, Mask::splat(true)) }
    }

    /// 有条件地将指针逐元素写入 SIMD vector。
    /// 掩码 `启用` 所有 `true` 指针并禁用所有 `false` 指针。
    /// 如果禁用指针，则跳过对其指针的写入。
    ///
    /// # Safety
    ///
    /// 使能指针必须满足与 [`core::ptr::write`] 相同的条件。
    ///
    /// # Example
    /// ```
    /// # #![feature(portable_simd)]
    /// # #[cfg(feature = "as_crate")] use core_simd::simd;
    /// # #[cfg(not(feature = "as_crate"))] use core::simd;
    /// # use simd::{Mask, Simd, SimdMutPtr};
    /// let mut values = [0; 4];
    /// let offset = Simd::from_array([3, 2, 1, 0]);
    /// let ptrs = Simd::splat(values.as_mut_ptr()).wrapping_add(offset);
    /// let enable = Mask::from_array([true, true, false, false]);
    /// unsafe { Simd::from_array([6, 3, 5, 7]).scatter_select_ptr(ptrs, enable); }
    /// assert_eq!(values, [0, 0, 3, 6]);
    /// ```
    #[inline]
    #[cfg_attr(miri, track_caller)] // 即使没有 panic，这也有助于 Miri 回溯
    pub unsafe fn scatter_select_ptr(self, dest: Simd<*mut T, N>, enable: Mask<isize, N>) {
        // 安全性: 调用者负责维护所有不，变体
        unsafe { intrinsics::simd_scatter(self, dest, enable.to_int()) }
    }
}

impl<T, const N: usize> Copy for Simd<T, N>
where
    LaneCount<N>: SupportedLaneCount,
    T: SimdElement,
{
}

impl<T, const N: usize> Clone for Simd<T, N>
where
    LaneCount<N>: SupportedLaneCount,
    T: SimdElement,
{
    fn clone(&self) -> Self {
        *self
    }
}

impl<T, const N: usize> Default for Simd<T, N>
where
    LaneCount<N>: SupportedLaneCount,
    T: SimdElement + Default,
{
    #[inline]
    fn default() -> Self {
        Self::splat(T::default())
    }
}

impl<T, const N: usize> PartialEq for Simd<T, N>
where
    LaneCount<N>: SupportedLaneCount,
    T: SimdElement + PartialEq,
{
    #[inline]
    fn eq(&self, other: &Self) -> bool {
        // 安全性: 所有 SIMD vectors 都是 SimdPartialEq，并且比较会产生有效掩码。
        let mask = unsafe {
            let tfvec: Simd<<T as SimdElement>::Mask, N> = intrinsics::simd_eq(*self, *other);
            Mask::from_int_unchecked(tfvec)
        };

        // 如果按元素比较时所有元素都相等，则两个 vectors 相等
        mask.all()
    }

    #[allow(clippy::partialeq_ne_impl)]
    #[inline]
    fn ne(&self, other: &Self) -> bool {
        // 安全性: 所有 SIMD vectors 都是 SimdPartialEq，并且比较会产生有效掩码。
        let mask = unsafe {
            let tfvec: Simd<<T as SimdElement>::Mask, N> = intrinsics::simd_ne(*self, *other);
            Mask::from_int_unchecked(tfvec)
        };

        // 如果按元素比较时任何元素不相等，则两个 vectors 不相等
        mask.any()
    }
}

impl<T, const N: usize> PartialOrd for Simd<T, N>
where
    LaneCount<N>: SupportedLaneCount,
    T: SimdElement + PartialOrd,
{
    #[inline]
    fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> {
        // TODO 使用 SIMD 等式
        self.to_array().partial_cmp(other.as_ref())
    }
}

impl<T, const N: usize> Eq for Simd<T, N>
where
    LaneCount<N>: SupportedLaneCount,
    T: SimdElement + Eq,
{
}

impl<T, const N: usize> Ord for Simd<T, N>
where
    LaneCount<N>: SupportedLaneCount,
    T: SimdElement + Ord,
{
    #[inline]
    fn cmp(&self, other: &Self) -> core::cmp::Ordering {
        // TODO 使用 SIMD 等式
        self.to_array().cmp(other.as_ref())
    }
}

impl<T, const N: usize> core::hash::Hash for Simd<T, N>
where
    LaneCount<N>: SupportedLaneCount,
    T: SimdElement + core::hash::Hash,
{
    #[inline]
    fn hash<H>(&self, state: &mut H)
    where
        H: core::hash::Hasher,
    {
        self.as_array().hash(state)
    }
}

// 数组引用
impl<T, const N: usize> AsRef<[T; N]> for Simd<T, N>
where
    LaneCount<N>: SupportedLaneCount,
    T: SimdElement,
{
    #[inline]
    fn as_ref(&self) -> &[T; N] {
        self.as_array()
    }
}

impl<T, const N: usize> AsMut<[T; N]> for Simd<T, N>
where
    LaneCount<N>: SupportedLaneCount,
    T: SimdElement,
{
    #[inline]
    fn as_mut(&mut self) -> &mut [T; N] {
        self.as_mut_array()
    }
}

// 切片引用
impl<T, const N: usize> AsRef<[T]> for Simd<T, N>
where
    LaneCount<N>: SupportedLaneCount,
    T: SimdElement,
{
    #[inline]
    fn as_ref(&self) -> &[T] {
        self.as_array()
    }
}

impl<T, const N: usize> AsMut<[T]> for Simd<T, N>
where
    LaneCount<N>: SupportedLaneCount,
    T: SimdElement,
{
    #[inline]
    fn as_mut(&mut self) -> &mut [T] {
        self.as_mut_array()
    }
}

// vector 和 array 的转换
impl<T, const N: usize> From<[T; N]> for Simd<T, N>
where
    LaneCount<N>: SupportedLaneCount,
    T: SimdElement,
{
    fn from(array: [T; N]) -> Self {
        Self::from_array(array)
    }
}

impl<T, const N: usize> From<Simd<T, N>> for [T; N]
where
    LaneCount<N>: SupportedLaneCount,
    T: SimdElement,
{
    fn from(vector: Simd<T, N>) -> Self {
        vector.to_array()
    }
}

impl<T, const N: usize> TryFrom<&[T]> for Simd<T, N>
where
    LaneCount<N>: SupportedLaneCount,
    T: SimdElement,
{
    type Error = core::array::TryFromSliceError;

    fn try_from(slice: &[T]) -> Result<Self, core::array::TryFromSliceError> {
        Ok(Self::from_array(slice.try_into()?))
    }
}

impl<T, const N: usize> TryFrom<&mut [T]> for Simd<T, N>
where
    LaneCount<N>: SupportedLaneCount,
    T: SimdElement,
{
    type Error = core::array::TryFromSliceError;

    fn try_from(slice: &mut [T]) -> Result<Self, core::array::TryFromSliceError> {
        Ok(Self::from_array(slice.try_into()?))
    }
}

mod sealed {
    pub trait Sealed {}
}
use sealed::Sealed;

/// 可用作 SIMD vector 元素的类型的标记 trait。
///
/// # Safety
/// 这个 trait 在实现时断言编译器可以将标记类型作为元素的 `#[repr(simd)]` 结构体单态化。
/// 严格地说，如果 vector 不会被错误编译，则 impl 是有效的。
/// 实际上，如果 vector 无法编译，那么实现它对用户是不友好的，即使允许用户尝试并没有破坏健全性保证。
///
///
pub unsafe trait SimdElement: Sealed + Copy {
    /// 此元素类型对应的掩码元素类型。
    type Mask: MaskElement;
}

impl Sealed for u8 {}

// 安全性: u8 是有效的 SIMD 元素类型，并受此 API 支持
unsafe impl SimdElement for u8 {
    type Mask = i8;
}

impl Sealed for u16 {}

// 安全性: u16 是有效的 SIMD 元素类型，并受此 API 支持
unsafe impl SimdElement for u16 {
    type Mask = i16;
}

impl Sealed for u32 {}

// 安全性: u32 是有效的 SIMD 元素类型，并受此 API 支持
unsafe impl SimdElement for u32 {
    type Mask = i32;
}

impl Sealed for u64 {}

// 安全性: u64 是有效的 SIMD 元素类型，并受此 API 支持
unsafe impl SimdElement for u64 {
    type Mask = i64;
}

impl Sealed for usize {}

// 安全性: usize 是有效的 SIMD 元素类型，并且受此 API 支持
unsafe impl SimdElement for usize {
    type Mask = isize;
}

impl Sealed for i8 {}

// 安全性: i8 是有效的 SIMD 元素类型，并受此 API 支持
unsafe impl SimdElement for i8 {
    type Mask = i8;
}

impl Sealed for i16 {}

// 安全性: i16 是有效的 SIMD 元素类型，并受此 API 支持
unsafe impl SimdElement for i16 {
    type Mask = i16;
}

impl Sealed for i32 {}

// 安全性: i32 是有效的 SIMD 元素类型，并受此 API 支持
unsafe impl SimdElement for i32 {
    type Mask = i32;
}

impl Sealed for i64 {}

// 安全性: i64 是有效的 SIMD 元素类型，并受此 API 支持
unsafe impl SimdElement for i64 {
    type Mask = i64;
}

impl Sealed for isize {}

// 安全性: isize 是有效的 SIMD 元素类型，并且受此 API 支持
unsafe impl SimdElement for isize {
    type Mask = isize;
}

impl Sealed for f32 {}

// 安全性: f32 是有效的 SIMD 元素类型，并受此 API 支持
unsafe impl SimdElement for f32 {
    type Mask = i32;
}

impl Sealed for f64 {}

// 安全性: f64 是有效的 SIMD 元素类型，并受此 API 支持
unsafe impl SimdElement for f64 {
    type Mask = i64;
}

impl<T> Sealed for *const T {}

// 安全性: (thin) const 指针是有效的 SIMD 元素类型，并且受此 API 支持
//
// future 可能支持胖指针。
unsafe impl<T> SimdElement for *const T
where
    T: core::ptr::Pointee<Metadata = ()>,
{
    type Mask = isize;
}

impl<T> Sealed for *mut T {}

// 安全性: (thin) mut 指针是有效的 SIMD 元素类型，并且受此 API 支持
//
// future 可能支持胖指针。
unsafe impl<T> SimdElement for *mut T
where
    T: core::ptr::Pointee<Metadata = ()>,
{
    type Mask = isize;
}