//! 处理内存的基本函数。
//!
//! 该模块包含用于查询类型的大小和对齐，初始化和操作内存的函数。
//!

#![stable(feature = "rust1", since = "1.0.0")]

use crate::clone;
use crate::cmp;
use crate::fmt;
use crate::hash;
use crate::intrinsics;
use crate::marker::{Copy, DiscriminantKind, Sized};
use crate::ptr;

mod manually_drop;
#[stable(feature = "manually_drop", since = "1.20.0")]
pub use manually_drop::ManuallyDrop;

mod maybe_uninit;
#[stable(feature = "maybe_uninit", since = "1.36.0")]
pub use maybe_uninit::MaybeUninit;

#[stable(feature = "rust1", since = "1.0.0")]
#[doc(inline)]
pub use crate::intrinsics::transmute;

/// 在不运行其析构函数 **的情况下，获取所有权和 "forgets" 值**。
///
/// 该值管理的任何资源 (例如堆内存或文件句柄) 将永远处于无法访问的状态。但是，它不能保证指向该内存的指针将保持有效。
///
/// * 如果要泄漏内存，请参见 [`Box::leak`]。
/// * 如果要获取内存的裸指针，请参见 [`Box::into_raw`]。
/// * 如果要正确处理某个值，请运行其析构函数，请参见 [`mem::drop`]。
///
/// # Safety
///
/// `forget` 未将其标记为 `unsafe`，因为 Rust 的安全保证不包括析构函数将始终运行的保证。
/// 例如，程序可以使用 [`Rc`][rc] 创建引用循环，或调用 [`process::exit`][exit] 退出而不运行析构函数。
/// 因此，从安全代码允许 `mem::forget` 不会从根本上改变 Rust 的安全保证。
///
/// 也就是说，通常不希望泄漏诸如内存或 I/O 对象之类的资源。
/// 在某些特殊的用例中，对于 FFI 或不安全代码提出了需求，但即使这样，通常还是首选 [`ManuallyDrop`]。
///
/// 因为允许忘记一个值，所以您编写的任何 `unsafe` 代码都必须允许这种可能性。您不能返回值，并且期望调用者一定会运行该值的析构函数。
///
/// [rc]: ../../std/rc/struct.Rc.html
/// [exit]: ../../std/process/fn.exit.html
///
/// # Examples
///
/// `mem::forget` 的规范安全使用是为了避免 `Drop` trait 实现的值的析构函数。例如，这将泄漏 `File`，即
/// 回收变量占用的空间，但不要关闭基础系统资源:
///
/// ```no_run
/// use std::mem;
/// use std::fs::File;
///
/// let file = File::open("foo.txt").unwrap();
/// mem::forget(file);
/// ```
///
/// 当基础资源的所有权先前已转移到 Rust 之外的代码时 (例如，通过将原始文件描述符传输到 C 代码)，这很有用。
///
/// # 与 `ManuallyDrop` 的关系
///
/// 虽然 `mem::forget` 也可以用于转移 *内存* 所有权，但是这样做很容易出错。
/// [`ManuallyDrop`] 应该改用。例如，考虑以下代码:
///
/// ```
/// use std::mem;
///
/// let mut v = vec![65, 122];
/// // 使用 `v` 的内容构建 `String`
/// let s = unsafe { String::from_raw_parts(v.as_mut_ptr(), v.len(), v.capacity()) };
/// // 泄漏 `v`，因为它的内存现在由 `s` 管理
/// mem::forget(v);  // 错误 - v 无效，不得将其传递给函数
/// assert_eq!(s, "Az");
/// // `s` 被隐式丢弃，并且其内存被释放。
/// ```
///
/// 上面的示例有两个问题:
///
/// * 如果在 `String` 的构造与 `mem::forget()` 的调用之间添加了更多代码，则其中的 panic 将导致双重释放，因为 `v` 和 `s` 均处理同一内存。
/// * 调用 `v.as_mut_ptr()` 并将数据所有权传输到 `s` 之后，`v` 值无效。
/// 即使将值仅移动到 `mem::forget` (不会检查它)，某些类型对其值也有严格的要求，以使它们在悬空或不再拥有时无效。
/// 以任何方式使用无效值，包括将它们传递给函数或从函数中返回它们，都构成未定义的行为，并且可能会破坏编译器所做的假设。
///
/// 切换到 `ManuallyDrop` 可以避免两个问题:
///
/// ```
/// use std::mem::ManuallyDrop;
///
/// let v = vec![65, 122];
/// // 在将 `v` 拆解为原始零件之前，请确保它不会丢弃掉!
/////
/// let mut v = ManuallyDrop::new(v);
/// // 现在拆卸 `v`。这些操作不能 panic，因此不会有泄漏。
/// let (ptr, len, cap) = (v.as_mut_ptr(), v.len(), v.capacity());
/// // 最后，构建一个 `String`。
/// let s = unsafe { String::from_raw_parts(ptr, len, cap) };
/// assert_eq!(s, "Az");
/// // `s` 被隐式丢弃，并且其内存被释放。
/// ```
///
/// `ManuallyDrop` 强有力地防止了双重释放，因为在执行其他任何操作之前，我们先禁用了 v 的析构函数。
/// `mem::forget()` 不允许这样做，因为它消耗了其参数，仅在从 `v` 中提取了我们需要的所有内容后，才迫使我们调用它。
/// 即使在 `ManuallyDrop` 的构建与字符串的构建之间引入了 panic (这在所示的代码中不能发生)，也将导致泄漏，而不是双重释放。
/// 换句话说，`ManuallyDrop` 在泄漏的一侧发生错误，而不是在 (两次) 丢弃的一侧发生错误。
///
/// 同样，`ManuallyDrop` 避免了在将所有权转让给 `s` 之后必须使用 "touch" `v` 的情况-完全避免了与 `v` 交互以处置它而不运行其析构函数的最后一步。
///
///
/// [`Box`]: ../../std/boxed/struct.Box.html
/// [`Box::leak`]: ../../std/boxed/struct.Box.html#method.leak
/// [`Box::into_raw`]: ../../std/boxed/struct.Box.html#method.into_raw
/// [`mem::drop`]: drop
/// [ub]: ../../reference/behavior-considered-undefined.html
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
#[inline]
#[rustc_const_stable(feature = "const_forget", since = "1.46.0")]
#[stable(feature = "rust1", since = "1.0.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "mem_forget")]
pub const fn forget<T>(t: T) {
    let _ = ManuallyDrop::new(t);
}

/// 与 [`forget`] 一样，但也接受未定义大小的值。
///
/// 该函数只是 `unsized_locals` 功能稳定后要删除的垫片。
///
#[inline]
#[unstable(feature = "forget_unsized", issue = "none")]
pub fn forget_unsized<T: ?Sized>(t: T) {
    intrinsics::forget(t)
}

/// 返回类型的大小 (以字节为单位)。
///
/// 更具体地说，这是具有该项类型 (包括对齐填充) 的数组中连续元素之间的字节偏移量。
///
/// 因此，对于任何类型的 `T` 和长度 `n`，`[T; n]` 的大小都是 `n * size_of::<T>()`。
///
/// 通常，类型的大小在整个编译过程中不稳定，但是特定类型 (例如基元) 是稳定的。
///
/// 下表提供了基元的大小。
///
/// Type | size_of::\<Type>()
/// ---- | ---------------
/// () | 0 bool | 1 u8 | 1 u16 | 2 u32 | 4 u64 | 8 u128 | 16 i8 | 1 i16 | 2 i32 | 4 i64 | 8 i128 | 16 f32 | 4 f64 | 8 char | 4
///
/// 此外，`usize` 和 `isize` 具有相同的大小。
///
/// `*const T`，`&T`，`Box<T>`，`Option<&T>` 和 `Option<Box<T>>` 类型均具有相同的大小。
/// 如果将 `T` 调整为大小，则所有这些类型的大小均与 `usize` 相同。
///
/// 指针的可变性不会改变其大小。这样，`&T` 和 `&mut T` 具有相同的大小。
/// 对于 `*const T` 和 `* mut T` 同样。
///
/// # `#[repr(C)]` 项的大小
///
/// 项的 `C` 表示具有已定义的布局。
/// 使用此布局，只要所有字段的大小都稳定，则项的大小也将保持稳定。
///
/// ## 结构体的大小
///
/// 对于 `structs`，大小由以下算法确定。
///
/// 对于结构体中按声明顺序排序的每个字段:
///
/// 1. 添加字段的大小。
/// 2. 将当前大小四舍五入到下一个字段的 [alignment] 的最接近倍数。
///
/// 最后，将结构体的大小四舍五入到其 [alignment] 的最接近倍数。
/// 结构体的排列通常是其所有字段中最大的排列; 这可以通过使用 `repr(align(N))` 进行更改。
///
/// 与 `C` 不同，零大小的结构体不会四舍五入为一个字节。
///
/// ## 枚举的大小
///
/// 除判别式外不包含任何数据的枚举的大小与为其编译的平台上的 C 枚举的大小相同。
///
/// ## union 的大小
///
/// union 的大小是其最大字段的大小。
///
/// 与 `C` 不同，零大小的 union 不会被四舍五入到一个字节的大小。
///
/// # Examples
///
/// ```
/// use std::mem;
///
/// // 一些原语
/// assert_eq!(4, mem::size_of::<i32>());
/// assert_eq!(8, mem::size_of::<f64>());
/// assert_eq!(0, mem::size_of::<()>());
///
/// // 一些数组
/// assert_eq!(8, mem::size_of::<[i32; 2]>());
/// assert_eq!(12, mem::size_of::<[i32; 3]>());
/// assert_eq!(0, mem::size_of::<[i32; 0]>());
///
///
/// // 指针大小相等
/// assert_eq!(mem::size_of::<&i32>(), mem::size_of::<*const i32>());
/// assert_eq!(mem::size_of::<&i32>(), mem::size_of::<Box<i32>>());
/// assert_eq!(mem::size_of::<&i32>(), mem::size_of::<Option<&i32>>());
/// assert_eq!(mem::size_of::<Box<i32>>(), mem::size_of::<Option<Box<i32>>>());
/// ```
///
/// 使用 `#[repr(C)]`。
///
/// ```
/// use std::mem;
///
/// #[repr(C)]
/// struct FieldStruct {
///     first: u8,
///     second: u16,
///     third: u8
/// }
///
/// // 第一个字段的大小为 1，因此请在大小上加 1。大小为 1。
/// // 第二个字段的对齐方式为 2，因此在填充大小上加 1。大小为 2。
/// // 第二个字段的大小为 2，因此将大小加 2。大小为 4。
/// // 第三个字段的对齐方式为 1，因此请在填充大小上加上 0。大小为 4。
/// // 第三个字段的大小为 1，因此请在大小上加 1。大小为 5。
/// // 最后，结构体的对齐方式为 2 (因为其字段之间的最大对齐方式为 2)，所以在填充的大小上加 1。
/// // 大小为 6。
/// assert_eq!(6, mem::size_of::<FieldStruct>());
///
/// #[repr(C)]
/// struct TupleStruct(u8, u16, u8);
///
/// // 元组结构体遵循相同的规则。
/// assert_eq!(6, mem::size_of::<TupleStruct>());
///
/// // 请注意，对字段重新排序可以减小大小。
/// // 我们可以通过将 `third` 放在 `second` 之前删除两个填充字节。
/// #[repr(C)]
/// struct FieldStructOptimized {
///     first: u8,
///     third: u8,
///     second: u16
/// }
///
/// assert_eq!(4, mem::size_of::<FieldStructOptimized>());
///
/// // union 的大小是最大字段的大小。
/// #[repr(C)]
/// union ExampleUnion {
///     smaller: u8,
///     larger: u16
/// }
///
/// assert_eq!(2, mem::size_of::<ExampleUnion>());
/// ```
///
/// [alignment]: align_of
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
#[inline(always)]
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_promotable]
#[rustc_const_stable(feature = "const_size_of", since = "1.24.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "mem_size_of")]
pub const fn size_of<T>() -> usize {
    intrinsics::size_of::<T>()
}

/// 返回所指向的值的大小 (以字节为单位)。
///
/// 这通常与 `size_of::<T>()` 相同。
/// 但是，当 `T` 没有静态已知的大小 (例如，切片 [`[T]`][slice] 或 [trait object]) 时，可以使用 `size_of_val` 获得动态已知的大小。
///
///
/// [trait object]: ../../book/ch17-02-trait-objects.html
///
/// # Examples
///
/// ```
/// use std::mem;
///
/// assert_eq!(4, mem::size_of_val(&5i32));
///
/// let x: [u8; 13] = [0; 13];
/// let y: &[u8] = &x;
/// assert_eq!(13, mem::size_of_val(y));
/// ```
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_const_unstable(feature = "const_size_of_val", issue = "46571")]
#[cfg_attr(not(test), rustc_diagnostic_item = "mem_size_of_val")]
pub const fn size_of_val<T: ?Sized>(val: &T) -> usize {
    // SAFETY: `val` 是引用，因此它是有效的裸指针
    unsafe { intrinsics::size_of_val(val) }
}

/// 返回所指向的值的大小 (以字节为单位)。
///
/// 这通常与 `size_of::<T>()` 相同。然而，当 `T`*没有* 静态大小时，例如，[`[T]`][slice] 或 [trait object]，那么 `size_of_val_raw` 可用于获取动态已知大小。
///
/// # Safety
///
/// 仅在满足以下条件时，此函数才可以安全调用:
///
/// - 如果 `T` 是 `Sized`，则调用该函数始终是安全的。
/// - 如果 `T` 的未定义大小的尾部为:
///     - [slice]，则切片尾部的长度必须是初始化的整数，并且 *entire 值*(动态尾部长度 + 静态大小的前缀) 的大小必须适合 `isize`。
///     - [trait object]，则指针的 vtable 部分必须指向通过取消大小调整强制获取的有效 vtable，并且 *entire 值*(动态尾部长度 + 静态大小的前缀) 的大小必须适合 `isize`。
///
///     - (unstable) [extern type]，则此函数始终可以安全调用，但可能会 panic 或以其他方式返回错误的值，因为外部类型的布局未知。
///     这与带有外部类型尾部的类型的引用上的 [`size_of_val`] 行为相同。
///     - 否则，保守地不允许调用此函数。
///
/// [trait object]: ../../book/ch17-02-trait-objects.html
/// [extern type]: ../../unstable-book/language-features/extern-types.html
///
/// # Examples
///
/// ```
/// #![feature(layout_for_ptr)]
/// use std::mem;
///
/// assert_eq!(4, mem::size_of_val(&5i32));
///
/// let x: [u8; 13] = [0; 13];
/// let y: &[u8] = &x;
/// assert_eq!(13, unsafe { mem::size_of_val_raw(y) });
/// ```
///
///
///
///
///
///
///
///
#[inline]
#[unstable(feature = "layout_for_ptr", issue = "69835")]
#[rustc_const_unstable(feature = "const_size_of_val_raw", issue = "46571")]
pub const unsafe fn size_of_val_raw<T: ?Sized>(val: *const T) -> usize {
    // SAFETY: 调用者必须提供有效的裸指针
    unsafe { intrinsics::size_of_val(val) }
}

/// 返回 [ABI] 要求的类型的最小对齐方式。
///
/// `T` 类型的值的每个引用必须是该数字的倍数。
///
/// 这是用于结构字段的对齐方式。它可能小于首选的对齐方式。
///
/// [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface
///
/// # Examples
///
/// ```
/// # #![allow(deprecated)]
/// use std::mem;
///
/// assert_eq!(4, mem::min_align_of::<i32>());
/// ```
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_deprecated(reason = "use `align_of` instead", since = "1.2.0")]
pub fn min_align_of<T>() -> usize {
    intrinsics::min_align_of::<T>()
}

/// 返回 [ABI] 所需的 `val` 指向的值的类型的最小对齐方式。
///
/// `T` 类型的值的每个引用必须是该数字的倍数。
///
/// [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface
///
/// # Examples
///
/// ```
/// # #![allow(deprecated)]
/// use std::mem;
///
/// assert_eq!(4, mem::min_align_of_val(&5i32));
/// ```
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_deprecated(reason = "use `align_of_val` instead", since = "1.2.0")]
pub fn min_align_of_val<T: ?Sized>(val: &T) -> usize {
    // SAFETY: val 是一个引用，因此它是有效的裸指针
    unsafe { intrinsics::min_align_of_val(val) }
}

/// 返回 [ABI] 要求的类型的最小对齐方式。
///
/// `T` 类型的值的每个引用必须是该数字的倍数。
///
/// 这是用于结构字段的对齐方式。它可能小于首选的对齐方式。
///
/// [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface
///
/// # Examples
///
/// ```
/// use std::mem;
///
/// assert_eq!(4, mem::align_of::<i32>());
/// ```
#[inline(always)]
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_promotable]
#[rustc_const_stable(feature = "const_align_of", since = "1.24.0")]
pub const fn align_of<T>() -> usize {
    intrinsics::min_align_of::<T>()
}

/// 返回 [ABI] 所需的 `val` 指向的值的类型的最小对齐方式。
///
/// `T` 类型的值的每个引用必须是该数字的倍数。
///
/// [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface
///
/// # Examples
///
/// ```
/// use std::mem;
///
/// assert_eq!(4, mem::align_of_val(&5i32));
/// ```
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_const_unstable(feature = "const_align_of_val", issue = "46571")]
#[allow(deprecated)]
pub const fn align_of_val<T: ?Sized>(val: &T) -> usize {
    // SAFETY: val 是一个引用，因此它是有效的裸指针
    unsafe { intrinsics::min_align_of_val(val) }
}

/// 返回 [ABI] 所需的 `val` 指向的值的类型的最小对齐方式。
///
/// `T` 类型的值的每个引用必须是该数字的倍数。
///
/// [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface
///
/// # Safety
///
/// 仅在满足以下条件时，此函数才可以安全调用:
///
/// - 如果 `T` 是 `Sized`，则调用该函数始终是安全的。
/// - 如果 `T` 的未定义大小的尾部为:
///     - [slice]，则切片尾部的长度必须是初始化的整数，并且 *entire 值*(动态尾部长度 + 静态大小的前缀) 的大小必须适合 `isize`。
///     - [trait object]，则指针的 vtable 部分必须指向通过取消大小调整强制获取的有效 vtable，并且 *entire 值*(动态尾部长度 + 静态大小的前缀) 的大小必须适合 `isize`。
///
///     - (unstable) [extern type]，则此函数始终可以安全调用，但可能会 panic 或以其他方式返回错误的值，因为外部类型的布局未知。
///     这与带有外部类型尾部的类型的引用上的 [`align_of_val`] 行为相同。
///     - 否则，保守地不允许调用此函数。
///
/// [trait object]: ../../book/ch17-02-trait-objects.html
/// [extern type]: ../../unstable-book/language-features/extern-types.html
///
/// # Examples
///
/// ```
/// #![feature(layout_for_ptr)]
/// use std::mem;
///
/// assert_eq!(4, unsafe { mem::align_of_val_raw(&5i32) });
/// ```
///
///
///
///
///
///
#[inline]
#[unstable(feature = "layout_for_ptr", issue = "69835")]
#[rustc_const_unstable(feature = "const_align_of_val_raw", issue = "46571")]
pub const unsafe fn align_of_val_raw<T: ?Sized>(val: *const T) -> usize {
    // SAFETY: 调用者必须提供有效的裸指针
    unsafe { intrinsics::min_align_of_val(val) }
}

/// 如果丢弃类型为 `T` 的值很重要，则返回 `true`。
///
/// 这纯粹是一个优化提示，可以保守地实现:
/// 对于实际上不需要丢弃的类型，它可能返回 `true`。
/// 因此，始终返回 `true` 将是此函数的有效实现。但是，如果此函数实际返回 `false`，则可以确定丢弃 `T` 没有副作用。
///
/// 需要手动丢弃其数据的诸如集合之类的底层实现，应使用此函数来避免在销毁它们时不必要地丢弃其所有内容。
///
/// 这可能不会对发行版本产生影响 (可以轻松检测并消除没有副作用的循环)，但是对于调试版本而言，这通常是一个大胜利。
///
/// 请注意，[`drop_in_place`] 已经执行了此检查，因此，如果您的工作量可以减少到少量的 [`drop_in_place`] 调用，则无需使用此功能。
/// 特别要注意的是，您可以 [`drop_in_place`] 一个切片，这将对所有值进行一次 needs_drop 检查。
///
/// 因此，像 Vec 这样的类型只是 `drop_in_place(&mut self[..])`，而没有显式使用 `needs_drop`。
/// 另一方面，像 [`HashMap`] 这样的类型必须一次丢弃一个值，并且应使用此 API。
///
/// [`drop_in_place`]: crate::ptr::drop_in_place
/// [`HashMap`]: ../../std/collections/struct.HashMap.html
///
/// # Examples
///
/// 这是一个集合如何利用 `needs_drop` 的示例:
///
/// ```
/// use std::{mem, ptr};
///
/// pub struct MyCollection<T> {
/// #   data: [T; 1],
///     /* ... */
/// }
/// # impl<T> MyCollection<T> {
/// #   fn iter_mut(&mut self) -> &mut [T] { &mut self.data }
/// #   fn free_buffer(&mut self) {}
/// # }
///
/// impl<T> Drop for MyCollection<T> {
///     fn drop(&mut self) {
///         unsafe {
///             // 丢弃数据
///             if mem::needs_drop::<T>() {
///                 for x in self.iter_mut() {
///                     ptr::drop_in_place(x);
///                 }
///             }
///             self.free_buffer();
///         }
///     }
/// }
/// ```
///
///
///
///
///
///
///
#[inline]
#[stable(feature = "needs_drop", since = "1.21.0")]
#[rustc_const_stable(feature = "const_needs_drop", since = "1.36.0")]
#[rustc_diagnostic_item = "needs_drop"]
pub const fn needs_drop<T>() -> bool {
    intrinsics::needs_drop::<T>()
}

/// 返回由全零字节模式表示的 `T` 类型的值。
///
/// 这意味着，例如，`(u8, u16)` 中的填充字节不必为零。
///
/// 不能保证全零字节模式代表某种 `T` 类型的有效值。
/// 例如，对于引用类型 (`&T`，`&mut T`) 和函数指针，全零字节模式不是有效值。
/// 在此类类型上使用 `zeroed` 会立即导致 [未定义的行为][ub]，因为 [Rust 编译器][inv] 假设在它认为已初始化的变量中始终存在有效值。
///
///
/// 与 [`MaybeUninit::zeroed().assume_init()`][zeroed] 具有相同的作用。
/// 有时对 FFI 很有用，但通常应避免使用。
///
/// [zeroed]: MaybeUninit::zeroed
/// [ub]: ../../reference/behavior-considered-undefined.html
/// [inv]: MaybeUninit#initialization-invariant
///
/// # Examples
///
/// 此函数的正确用法: 用零初始化一个整数。
///
/// ```
/// use std::mem;
///
/// let x: i32 = unsafe { mem::zeroed() };
/// assert_eq!(0, x);
/// ```
///
/// 该函数的 *错误* 用法: 用零初始化引用。
///
/// ```rust,no_run
/// # #![allow(invalid_value)]
/// use std::mem;
///
/// let _x: &i32 = unsafe { mem::zeroed() }; // 未定义的行为!
/// let _y: fn() = unsafe { mem::zeroed() }; // 然后再次!
/// ```
///
///
///
#[inline(always)]
#[stable(feature = "rust1", since = "1.0.0")]
#[allow(deprecated_in_future)]
#[allow(deprecated)]
#[rustc_diagnostic_item = "mem_zeroed"]
pub unsafe fn zeroed<T>() -> T {
    // SAFETY: 调用者必须保证全零值对 `T` 有效。
    unsafe {
        intrinsics::assert_zero_valid::<T>();
        MaybeUninit::zeroed().assume_init()
    }
}

/// 假装产生 `T` 类型的值，而实际上什么也不做，从而绕过 Rust 的常规内存初始化检查。
///
/// **不推荐使用此函数。** 请改用 [`MaybeUninit<T>`]。
///
/// 弃用的原因是该函数基本上不能正确使用: 它具有与 [`MaybeUninit::uninit().assume_init()`][uninit] 相同的作用。
///
/// 正如 [`assume_init` 文档][assume_init] 所解释的那样，[Rust 编译器][inv] 假设值已正确初始化。
/// 因此，调用例如
/// `mem::uninitialized::<bool>()` 导致立即返回返回的 `bool` 的不确定行为，该 `bool` 不一定是 `true` 或 `false`。
/// 更糟糕的是，真正的未初始化内存 (如此处返回的内存) 的特殊之处在于，编译器知道它没有固定的值。
/// 这使得在变量中具有未初始化的数据成为不确定的行为，即使该变量具有整数类型也是如此。
/// (请注意，关于未初始化整数的规则尚未最终确定，但是除非被确定，否则建议避免使用它们。)
///
/// [uninit]: MaybeUninit::uninit
/// [assume_init]: MaybeUninit::assume_init
/// [inv]: MaybeUninit#initialization-invariant
///
///
///
///
///
#[inline(always)]
#[rustc_deprecated(since = "1.39.0", reason = "use `mem::MaybeUninit` instead")]
#[stable(feature = "rust1", since = "1.0.0")]
#[allow(deprecated_in_future)]
#[allow(deprecated)]
#[rustc_diagnostic_item = "mem_uninitialized"]
pub unsafe fn uninitialized<T>() -> T {
    // SAFETY: 调用者必须保证对 `T` 有效的单位化值。
    unsafe {
        intrinsics::assert_uninit_valid::<T>();
        MaybeUninit::uninit().assume_init()
    }
}

/// 在两个可变位置交换值，而无需对其中一个进行初始化。
///
/// * 如果要交换默认值或虚拟值，请参见 [`take`]。
/// * 如果要与传递的值交换，返回旧值，请参见 [`replace`]。
///
/// # Examples
///
/// ```
/// use std::mem;
///
/// let mut x = 5;
/// let mut y = 42;
///
/// mem::swap(&mut x, &mut y);
///
/// assert_eq!(42, x);
/// assert_eq!(5, y);
/// ```
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_const_unstable(feature = "const_swap", issue = "83163")]
pub const fn swap<T>(x: &mut T, y: &mut T) {
    // SAFETY: 裸指针是根据安全可变引用创建的，满足 `ptr::swap_nonoverlapping_one` 上的所有约束
    //
    unsafe {
        ptr::swap_nonoverlapping_one(x, y);
    }
}

/// 用默认值 `T` 替换 `dest`，并返回以前的 `dest` 值。
///
/// * 如果要替换两个变量的值，请参见 [`swap`]。
/// * 如果要替换为传递的值而不是默认值，请参见 [`replace`]。
///
/// # Examples
///
/// 一个简单的例子:
///
/// ```
/// use std::mem;
///
/// let mut v: Vec<i32> = vec![1, 2];
///
/// let old_v = mem::take(&mut v);
/// assert_eq!(vec![1, 2], old_v);
/// assert!(v.is_empty());
/// ```
///
/// `take` 允许通过将结构体字段替换为 "empty" 值来获得结构体字段的所有权。
/// 没有 `take`，您可能会遇到以下问题:
///
/// ```compile_fail,E0507
/// struct Buffer<T> { buf: Vec<T> }
///
/// impl<T> Buffer<T> {
///     fn get_and_reset(&mut self) -> Vec<T> {
///         // 错误: 无法移出 & mut-pointer 指针的解引用
///         let buf = self.buf;
///         self.buf = Vec::new();
///         buf
///     }
/// }
/// ```
///
/// 请注意，`T` 不一定实现 [`Clone`]，因此它甚至无法克隆和重置 `self.buf`。
/// 但是 `take` 可以用于取消 `self.buf` 的原始值与 `self` 的关联，从而可以将其返回:
///
///
/// ```
/// use std::mem;
///
/// # struct Buffer<T> { buf: Vec<T> }
/// impl<T> Buffer<T> {
///     fn get_and_reset(&mut self) -> Vec<T> {
///         mem::take(&mut self.buf)
///     }
/// }
///
/// let mut buffer = Buffer { buf: vec![0, 1] };
/// assert_eq!(buffer.buf.len(), 2);
///
/// assert_eq!(buffer.get_and_reset(), vec![0, 1]);
/// assert_eq!(buffer.buf.len(), 0);
/// ```
#[inline]
#[stable(feature = "mem_take", since = "1.40.0")]
pub fn take<T: Default>(dest: &mut T) -> T {
    replace(dest, T::default())
}

/// 将 `src` 移至引用的 `dest`，返回先前的 `dest` 值。
///
/// 这两个值都不会被丢弃。
///
/// * 如果要替换两个变量的值，请参见 [`swap`]。
/// * 如果要替换为默认值，请参见 [`take`]。
///
/// # Examples
///
/// 一个简单的例子:
///
/// ```
/// use std::mem;
///
/// let mut v: Vec<i32> = vec![1, 2];
///
/// let old_v = mem::replace(&mut v, vec![3, 4, 5]);
/// assert_eq!(vec![1, 2], old_v);
/// assert_eq!(vec![3, 4, 5], v);
/// ```
///
/// `replace` 允许通过用另一个值替换结构体字段来使用它。
/// 没有 `replace`，您可能会遇到以下问题:
///
/// ```compile_fail,E0507
/// struct Buffer<T> { buf: Vec<T> }
///
/// impl<T> Buffer<T> {
///     fn replace_index(&mut self, i: usize, v: T) -> T {
///         // 错误: 无法移出 & mut-pointer 指针的解引用
///         let t = self.buf[i];
///         self.buf[i] = v;
///         t
///     }
/// }
/// ```
///
/// 请注意，`T` 不一定实现 [`Clone`]，因此我们甚至无法克隆 `self.buf[i]` 以避免此举。
/// 但是 `replace` 可以用于取消该索引处的原始值与 `self` 的关联，从而可以将其返回:
///
///
/// ```
/// # #![allow(dead_code)]
/// use std::mem;
///
/// # struct Buffer<T> { buf: Vec<T> }
/// impl<T> Buffer<T> {
///     fn replace_index(&mut self, i: usize, v: T) -> T {
///         mem::replace(&mut self.buf[i], v)
///     }
/// }
///
/// let mut buffer = Buffer { buf: vec![0, 1] };
/// assert_eq!(buffer.buf[0], 0);
///
/// assert_eq!(buffer.replace_index(0, 2), 0);
/// assert_eq!(buffer.buf[0], 2);
/// ```
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
#[must_use = "if you don't need the old value, you can just assign the new value directly"]
#[rustc_const_unstable(feature = "const_replace", issue = "83164")]
#[cfg_attr(not(test), rustc_diagnostic_item = "mem_replace")]
pub const fn replace<T>(dest: &mut T, src: T) -> T {
    // SAFETY: 我们从 `dest` 读取，但之后直接将 `src` 写入其中，这样就不会重复旧值。
    // 什么都不会被丢弃掉，也什么都不会 panic。
    //
    unsafe {
        let result = ptr::read(dest);
        ptr::write(dest, src);
        result
    }
}

/// 处理一个值。
///
/// 通过调用 [`Drop`][drop] 的参数实现来实现。
///
/// 这对于实现 `Copy` 的类型实际上不起作用，例如
/// integers.
/// 这样的值被复制并将 _then_ 移到函数中，因此该值在此函数调用之后仍然存在。
///
///
/// 这个功能并不神奇。它的字面定义为
///
/// ```
/// pub fn drop<T>(_x: T) { }
/// ```
///
/// 由于 `_x` 已移入函数，因此它会在函数返回之前自动丢弃。
///
/// [drop]: Drop
///
/// # Examples
///
/// 基本用法:
///
/// ```
/// let v = vec![1, 2, 3];
///
/// drop(v); // 显式丢弃 vector
/// ```
///
/// 由于 [`RefCell`] 在运行时强制执行借用规则，因此 `drop` 可以发布 [`RefCell`] 借用:
///
/// ```
/// use std::cell::RefCell;
///
/// let x = RefCell::new(1);
///
/// let mut mutable_borrow = x.borrow_mut();
/// *mutable_borrow = 1;
///
/// drop(mutable_borrow); // 放弃该插槽上的可变借用
///
/// let borrow = x.borrow();
/// println!("{}", *borrow);
/// ```
///
/// 实现 [`Copy`] 的整数和其他类型不受 `drop` 的影响。
///
/// ```
/// #[derive(Copy, Clone)]
/// struct Foo(u8);
///
/// let x = 1;
/// let y = Foo(2);
/// drop(x); // `x` 的副本已移动并丢弃
/// drop(y); // `y` 的副本已移动并丢弃
///
/// println!("x: {}, y: {}", x, y.0); // 仍然可用
/// ```
///
/// [`RefCell`]: crate::cell::RefCell
///
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "mem_drop")]
pub fn drop<T>(_x: T) {}

/// 将 `src` 解释为具有 `&U` 类型，然后在不移动所包含的值的情况下读取 `src`。
///
/// 通过将 `&T` 转换为 `&U`，然后读取 `&U`，此函数将不安全地假定指针 `src` 对 [`size_of::<U>`][size_of] 字节有效 (除非这样做的正确方式是，即使 `&U` 的对齐要求比 `&T` 严格)。
/// 它还将不安全地创建所包含值的副本，而不是移出 `src`。
///
/// 如果 `T` 和 `U` 具有不同的大小，则不是编译时错误，但是强烈建议仅在 `T` 和 `U` 具有相同的大小时调用此函数。如果 `U` 大于 `T`，则此函数将触发 [未定义的行为][ub]。
///
/// [ub]: ../../reference/behavior-considered-undefined.html
///
/// # Examples
///
/// ```
/// use std::mem;
///
/// #[repr(packed)]
/// struct Foo {
///     bar: u8,
/// }
///
/// let foo_array = [10u8];
///
/// unsafe {
///     // 从 'foo_array' 复制数据并将其视为 'Foo'
///     let mut foo_struct: Foo = mem::transmute_copy(&foo_array);
///     assert_eq!(foo_struct.bar, 10);
///
///     // 修改复制的数据
///     foo_struct.bar = 20;
///     assert_eq!(foo_struct.bar, 20);
/// }
///
/// // 'foo_array' 的内容不应更改
/// assert_eq!(foo_array, [10]);
/// ```
///
///
///
///
///
///
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_const_unstable(feature = "const_transmute_copy", issue = "83165")]
pub const unsafe fn transmute_copy<T, U>(src: &T) -> U {
    // 如果 U 具有更高的对齐要求，则 src 可能无法适当对齐。
    if align_of::<U>() > align_of::<T>() {
        // SAFETY: `src` 是一个引用，它保证对读取有效。
        // 调用者必须保证实际的转换是安全的。
        unsafe { ptr::read_unaligned(src as *const T as *const U) }
    } else {
        // SAFETY: `src` 是一个引用，它保证对读取有效。
        // 我们只是检查 `src as *const U` 是否正确对齐。
        // 调用者必须保证实际的转换是安全的。
        unsafe { ptr::read(src as *const T as *const U) }
    }
}

/// 代表枚举的不透明类型。
///
/// 有关更多信息，请参见此模块中的 [`discriminant`] 函数。
#[stable(feature = "discriminant_value", since = "1.21.0")]
pub struct Discriminant<T>(<T as DiscriminantKind>::Discriminant);

// N.B. 无法导出这些 trait 实现，因为我们不需要 T 的任何界限。

#[stable(feature = "discriminant_value", since = "1.21.0")]
impl<T> Copy for Discriminant<T> {}

#[stable(feature = "discriminant_value", since = "1.21.0")]
impl<T> clone::Clone for Discriminant<T> {
    fn clone(&self) -> Self {
        *self
    }
}

#[stable(feature = "discriminant_value", since = "1.21.0")]
impl<T> cmp::PartialEq for Discriminant<T> {
    fn eq(&self, rhs: &Self) -> bool {
        self.0 == rhs.0
    }
}

#[stable(feature = "discriminant_value", since = "1.21.0")]
impl<T> cmp::Eq for Discriminant<T> {}

#[stable(feature = "discriminant_value", since = "1.21.0")]
impl<T> hash::Hash for Discriminant<T> {
    fn hash<H: hash::Hasher>(&self, state: &mut H) {
        self.0.hash(state);
    }
}

#[stable(feature = "discriminant_value", since = "1.21.0")]
impl<T> fmt::Debug for Discriminant<T> {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.debug_tuple("Discriminant").field(&self.0).finish()
    }
}

/// 返回唯一标识 `v` 中的枚举成员的值。
///
/// 如果 `T` 不是枚举，则调用此函数不会导致未定义的行为，但返回值是未指定的。
///
///
/// # Stability
///
/// 如果枚举定义更改，则枚举成员的判别式可能会更改。
/// 在具有相同编译器的编译之间，对某些成员的判别将不会发生变化。
///
/// # Examples
///
/// 这可以用来比较携带数据的枚举，而忽略实际数据:
///
/// ```
/// use std::mem;
///
/// enum Foo { A(&'static str), B(i32), C(i32) }
///
/// assert_eq!(mem::discriminant(&Foo::A("bar")), mem::discriminant(&Foo::A("baz")));
/// assert_eq!(mem::discriminant(&Foo::B(1)), mem::discriminant(&Foo::B(2)));
/// assert_ne!(mem::discriminant(&Foo::B(3)), mem::discriminant(&Foo::C(3)));
/// ```
///
#[stable(feature = "discriminant_value", since = "1.21.0")]
#[rustc_const_unstable(feature = "const_discriminant", issue = "69821")]
#[cfg_attr(not(test), rustc_diagnostic_item = "mem_discriminant")]
pub const fn discriminant<T>(v: &T) -> Discriminant<T> {
    Discriminant(intrinsics::discriminant_value(v))
}

/// 返回枚举类型 `T` 中的成员数。
///
/// 如果 `T` 不是枚举，则调用此函数不会导致未定义的行为，但返回值是未指定的。
/// 同样，如果 `T` 是成员数大于 `usize::MAX` 的枚举，则未指定返回值。
/// 无人居住的成员将被计算在内。
///
/// # Examples
///
/// ```
/// # #![feature(never_type)]
/// # #![feature(variant_count)]
///
/// use std::mem;
///
/// enum Void {}
/// enum Foo { A(&'static str), B(i32), C(i32) }
///
/// assert_eq!(mem::variant_count::<Void>(), 0);
/// assert_eq!(mem::variant_count::<Foo>(), 3);
///
/// assert_eq!(mem::variant_count::<Option<!>>(), 2);
/// assert_eq!(mem::variant_count::<Result<!, !>>(), 2);
/// ```
#[inline(always)]
#[unstable(feature = "variant_count", issue = "73662")]
#[rustc_const_unstable(feature = "variant_count", issue = "73662")]
pub const fn variant_count<T>() -> usize {
    intrinsics::variant_count::<T>()
}