//! 创建 `&[T]` 和 `&mut [T]` 的 free 函数。

use crate::array;
use crate::intrinsics::{
    assert_unsafe_precondition, is_aligned_and_not_null, is_valid_allocation_size,
};
use crate::ops::Range;
use crate::ptr;

/// 根据指针和长度形成切片。
///
/// `len` 参数是 **元素** 的数量，而不是字节数。
///
/// # Safety
///
/// 如果违反以下任一条件，则行为是未定义的：
///
/// * 对于 `len * mem::size_of::<T>()` 多个字节的读取，`data` 必须是 [valid]，并且必须正确对齐。这尤其意味着：
///
///     * 该切片的整个存储范围必须包含在一个分配的对象中！
///       切片永远不能跨越多个分配的对象。请参见 [下文](#incorrect-usage) 了解一个没有考虑到这一点的错误示例。
///     * 即使对于零长度切片，`data` 也必须非空且对齐。
///     这样做的一个原因是，枚举布局优化可能依赖于对齐的引用 (包括任何长度的切片) 和非空值，以将它们与其他数据区分开。
///     您可以使用 [`NonNull::dangling()`] 获得可用作零长度切片的 `data` 的指针。
///
/// * `data` 必须指向 `len` 类型的 `T` 类型的连续正确初始化值。
///
/// * 返回的切片引用的内存在生命周期 `'a` 期间不得更改，除非在 `UnsafeCell` 内部。
///
/// * 切片的总大小 `len * mem::size_of::<T>()` 必须不大于 `isize::MAX`。
///   请参见 [`pointer::offset`] 的安全文档。
///
/// # Caveat
///
/// 从使用中可以推断出返回切片的生命周期。
/// 为防止意外滥用，建议将生命周期与生命周期中任何安全的来源联系起来，例如通过提供一个辅助函数，获取切片的宿主值的生命周期，或通过明确的注解法。
///
///
/// # Examples
///
/// ```
/// use std::slice;
///
/// // 显示单个元素的切片
/// let x = 42;
/// let ptr = &x as *const _;
/// let slice = unsafe { slice::from_raw_parts(ptr, 1) };
/// assert_eq!(slice[0], 42);
/// ```
///
/// ### 用法不正确
///
/// 下面的 `join_slices` 函数是不健全的 ⚠️
///
/// ```rust,no_run
/// use std::slice;
///
/// fn join_slices<'a, T>(fst: &'a [T], snd: &'a [T]) -> &'a [T] {
///     let fst_end = fst.as_ptr().wrapping_add(fst.len());
///     let snd_start = snd.as_ptr();
///     assert_eq!(fst_end, snd_start, "Slices must be contiguous!");
///     unsafe {
///         // 上面的断言确保 `fst` 和 `snd` 是连续的，但是它们仍可能包含在 _different allocated objects_ 中，在这种情况下，创建此切片是未定义的行为。
/////
/////
///         slice::from_raw_parts(fst.as_ptr(), fst.len() + snd.len())
///     }
/// }
///
/// fn main() {
///     // `a` 和 `b` 是不同的分配对象...
///     let a = 42;
///     let b = 27;
///     // ... 尽管如此，它仍然可以在内存中连续布局: | 一个 | b |
///     let _ = join_slices(slice::from_ref(&a), slice::from_ref(&b)); // UB
/// }
/// ```
///
/// [valid]: ptr#safety
/// [`NonNull::dangling()`]: ptr::NonNull::dangling
///
///
///
///
///
///
///
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_const_stable(feature = "const_slice_from_raw_parts", since = "1.64.0")]
#[must_use]
pub const unsafe fn from_raw_parts<'a, T>(data: *const T, len: usize) -> &'a [T] {
    // SAFETY: 调用者必须遵守 `from_raw_parts` 的安全保证。
    unsafe {
        assert_unsafe_precondition!(
            "slice::from_raw_parts requires the pointer to be aligned and non-null, and the total size of the slice not to exceed `isize::MAX`",
            [T](data: *const T, len: usize) => is_aligned_and_not_null(data)
                && is_valid_allocation_size::<T>(len)
        );
        &*ptr::slice_from_raw_parts(data, len)
    }
}

/// 执行与 [`from_raw_parts`] 相同的功能，除了返回可变切片。
///
/// # Safety
///
/// 如果违反以下任一条件，则行为是未定义的：
///
/// * 对于 `len * mem::size_of::<T>()` 多个字节的读取和写入，`data` 必须是 [valid]，并且必须正确对齐。这尤其意味着：
///
///     * 该切片的整个存储范围必须包含在一个分配的对象中！
///       切片永远不能跨越多个分配的对象。
///     * 即使对于零长度切片，`data` 也必须非空且对齐。
///     这样做的一个原因是，枚举布局优化可能依赖于对齐的引用 (包括任何长度的切片) 和非空值，以将它们与其他数据区分开。
///
///     您可以使用 [`NonNull::dangling()`] 获得可用作零长度切片的 `data` 的指针。
///
/// * `data` 必须指向 `len` 类型的 `T` 类型的连续正确初始化值。
///
/// * 在生命周期 `'a` 的持续时间内，不得通过任何其他指针 (不是从返回值派生) 访问返回的切片引用的内存。
///   读取和写入访问均被禁止。
///
/// * 切片的总大小 `len * mem::size_of::<T>()` 必须不大于 `isize::MAX`。
///   请参见 [`pointer::offset`] 的安全文档。
///
/// [valid]: ptr#safety
/// [`NonNull::dangling()`]: ptr::NonNull::dangling
///
///
///
///
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_const_unstable(feature = "const_slice_from_raw_parts_mut", issue = "67456")]
#[must_use]
pub const unsafe fn from_raw_parts_mut<'a, T>(data: *mut T, len: usize) -> &'a mut [T] {
    // SAFETY: 调用者必须遵守 `from_raw_parts_mut` 的安全保证。
    unsafe {
        assert_unsafe_precondition!(
            "slice::from_raw_parts_mut requires the pointer to be aligned and non-null, and the total size of the slice not to exceed `isize::MAX`",
            [T](data: *mut T, len: usize) => is_aligned_and_not_null(data)
                && is_valid_allocation_size::<T>(len)
        );
        &mut *ptr::slice_from_raw_parts_mut(data, len)
    }
}

/// 将引用转换为 T 转换为长度为 1 的切片 (不进行复制)。
#[stable(feature = "from_ref", since = "1.28.0")]
#[rustc_const_stable(feature = "const_slice_from_ref_shared", since = "1.63.0")]
#[must_use]
pub const fn from_ref<T>(s: &T) -> &[T] {
    array::from_ref(s)
}

/// 将引用转换为 T 转换为长度为 1 的切片 (不进行复制)。
#[stable(feature = "from_ref", since = "1.28.0")]
#[rustc_const_unstable(feature = "const_slice_from_ref", issue = "90206")]
#[must_use]
pub const fn from_mut<T>(s: &mut T) -> &mut [T] {
    array::from_mut(s)
}

/// 从指针范围形成一个切片。
///
/// 此函数对于与外部接口进行交互很有用，该外部接口使用两个指针来引用内存中的一系列元素，这在 C++ 中很常见。
///
/// # Safety
///
/// 如果违反以下任一条件，则行为是未定义的：
///
/// * 范围的 `start` 指针必须是 [valid] 并正确对齐指向切片的第一个元素的指针。
///
/// * `end` 指针必须是 [valid] 且正确对齐的指针，指向*一个过去*最后一个元素，这样从末尾到起始指针的偏移量就是切片的长度。
///
/// * 范围必须包含 `N` 类型 `T` 的连续正确初始化值:
///
///     * 该切片的整个存储范围必须包含在一个分配的对象中！
///       切片永远不能跨越多个分配的对象。
///
/// * 返回的切片引用的内存在生命周期 `'a` 期间不得更改，除非在 `UnsafeCell` 内部。
///
/// * 范围的总长度不得大于 `isize::MAX`。
///   请参见 [`pointer::offset`] 的安全文档。
///
/// 请注意，从 [`slice::as_ptr_range`] 创建的范围满足这些要求。
///
/// # Panics
///
/// 如果 `T` 是一个零大小的类型 (“ZST”)，这个函数就会出现 panic。
///
/// # Caveat
///
/// 从使用中可以推断出返回切片的生命周期。
/// 为防止意外滥用，建议将生命周期与生命周期中任何安全的来源联系起来，例如通过提供一个辅助函数，获取切片的宿主值的生命周期，或通过明确的注解法。
///
///
/// # Examples
///
/// ```
/// #![feature(slice_from_ptr_range)]
///
/// use core::slice;
///
/// let x = [1, 2, 3];
/// let range = x.as_ptr_range();
///
/// unsafe {
///     assert_eq!(slice::from_ptr_range(range), &x);
/// }
/// ```
///
/// [valid]: ptr#safety
///
///
///
///
///
///
///
///
#[unstable(feature = "slice_from_ptr_range", issue = "89792")]
#[rustc_const_unstable(feature = "const_slice_from_ptr_range", issue = "89792")]
pub const unsafe fn from_ptr_range<'a, T>(range: Range<*const T>) -> &'a [T] {
    // SAFETY: 调用者必须维护 `from_ptr_range` 的安全保证。
    unsafe { from_raw_parts(range.start, range.end.sub_ptr(range.start)) }
}

/// 从指针范围形成一个分割切片。
///
/// 这与 [`from_ptr_range`] 的功能相同，只是返回了一个不合法的切片。
///
/// 此函数对于与外部接口进行交互很有用，该外部接口使用两个指针来引用内存中的一系列元素，这在 C++ 中很常见。
///
/// # Safety
///
/// 如果违反以下任一条件，则行为是未定义的：
///
/// * 范围的 `start` 指针必须是 [valid] 并正确对齐指向切片的第一个元素的指针。
///
/// * `end` 指针必须是 [valid] 且正确对齐的指针，指向*一个过去*最后一个元素，这样从末尾到起始指针的偏移量就是切片的长度。
///
/// * 范围必须包含 `N` 类型 `T` 的连续正确初始化值:
///
///     * 该切片的整个存储范围必须包含在一个分配的对象中！
///       切片永远不能跨越多个分配的对象。
///
/// * 在生命周期 `'a` 的持续时间内，不得通过任何其他指针 (不是从返回值派生) 访问返回的切片引用的内存。
///   读取和写入访问均被禁止。
///
/// * 范围的总长度不得大于 `isize::MAX`。
///   请参见 [`pointer::offset`] 的安全文档。
///
/// 请注意，从 [`slice::as_mut_ptr_range`] 创建的范围满足这些要求。
///
/// # Panics
///
/// 如果 `T` 是一个零大小的类型 (“ZST”)，这个函数就会出现 panic。
///
/// # Caveat
///
/// 从使用中可以推断出返回切片的生命周期。
/// 为防止意外滥用，建议将生命周期与生命周期中任何安全的来源联系起来，例如通过提供一个辅助函数，获取切片的宿主值的生命周期，或通过明确的注解法。
///
///
/// # Examples
///
/// ```
/// #![feature(slice_from_ptr_range)]
///
/// use core::slice;
///
/// let mut x = [1, 2, 3];
/// let range = x.as_mut_ptr_range();
///
/// unsafe {
///     assert_eq!(slice::from_mut_ptr_range(range), &mut [1, 2, 3]);
/// }
/// ```
///
/// [valid]: ptr#safety
///
///
///
///
///
///
///
///
///
#[unstable(feature = "slice_from_ptr_range", issue = "89792")]
#[rustc_const_unstable(feature = "const_slice_from_mut_ptr_range", issue = "89792")]
pub const unsafe fn from_mut_ptr_range<'a, T>(range: Range<*mut T>) -> &'a mut [T] {
    // SAFETY: 调用者必须维护 `from_mut_ptr_range` 的安全保证。
    unsafe { from_raw_parts_mut(range.start, range.end.sub_ptr(range.start)) }
}