//! 具有堆已分配内容的连续可增长数组类型，写为 `Vec<T>`。
//!
//! Vectors 有 *O*(1) 索引，摊销 *O*(1) push (到最后) 和 *O*(1) pop (从最后)。
//!
//!
//! Vectors 确保它们分配的字节数永远不会超过 `isize::MAX` 字节。
//!
//! # Examples
//!
//! 您可以使用 [`Vec::new`] 显式创建 [`Vec`]：
//!
//! ```
//! let v: Vec<i32> = Vec::new();
//! ```
//!
//! ...或者使用 [`vec!`] 宏:
//!
//! ```
//! let v: Vec<i32> = vec![];
//!
//! let v = vec![1, 2, 3, 4, 5];
//!
//! let v = vec![0; 10]; // 十个零
//! ```
//!
//! 您可以将 [`push`] 值添加到 vector 的末尾 (这将根据需要增大 vector) ：
//!
//! ```
//! let mut v = vec![1, 2];
//!
//! v.push(3);
//! ```
//!
//! 弹出值的工作方式大致相同：
//!
//! ```
//! let mut v = vec![1, 2];
//!
//! let two = v.pop();
//! ```
//!
//! Vectors 还支持索引 (通过 [`Index`] 和 [`IndexMut`] traits) ：
//!
//! ```
//! let mut v = vec![1, 2, 3];
//! let three = v[2];
//! v[1] = v[1] + 5;
//! ```
//!
//! [`push`]: Vec::push
//!
//!

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

#[cfg(not(no_global_oom_handling))]
use core::cmp;
use core::cmp::Ordering;
use core::fmt;
use core::hash::{Hash, Hasher};
use core::iter;
use core::marker::PhantomData;
use core::mem::{self, ManuallyDrop, MaybeUninit, SizedTypeProperties};
use core::ops::{self, Index, IndexMut, Range, RangeBounds};
use core::ptr::{self, NonNull};
use core::slice::{self, SliceIndex};

use crate::alloc::{Allocator, Global};
use crate::borrow::{Cow, ToOwned};
use crate::boxed::Box;
use crate::collections::TryReserveError;
use crate::raw_vec::RawVec;

#[unstable(feature = "drain_filter", reason = "recently added", issue = "43244")]
pub use self::drain_filter::DrainFilter;

mod drain_filter;

#[cfg(not(no_global_oom_handling))]
#[stable(feature = "vec_splice", since = "1.21.0")]
pub use self::splice::Splice;

#[cfg(not(no_global_oom_handling))]
mod splice;

#[stable(feature = "drain", since = "1.6.0")]
pub use self::drain::Drain;

mod drain;

#[cfg(not(no_global_oom_handling))]
mod cow;

#[cfg(not(no_global_oom_handling))]
pub(crate) use self::in_place_collect::AsVecIntoIter;
#[stable(feature = "rust1", since = "1.0.0")]
pub use self::into_iter::IntoIter;

mod into_iter;

#[cfg(not(no_global_oom_handling))]
use self::is_zero::IsZero;

mod is_zero;

#[cfg(not(no_global_oom_handling))]
mod in_place_collect;

mod partial_eq;

#[cfg(not(no_global_oom_handling))]
use self::spec_from_elem::SpecFromElem;

#[cfg(not(no_global_oom_handling))]
mod spec_from_elem;

#[cfg(not(no_global_oom_handling))]
use self::set_len_on_drop::SetLenOnDrop;

#[cfg(not(no_global_oom_handling))]
mod set_len_on_drop;

#[cfg(not(no_global_oom_handling))]
use self::in_place_drop::{InPlaceDrop, InPlaceDstBufDrop};

#[cfg(not(no_global_oom_handling))]
mod in_place_drop;

#[cfg(not(no_global_oom_handling))]
use self::spec_from_iter_nested::SpecFromIterNested;

#[cfg(not(no_global_oom_handling))]
mod spec_from_iter_nested;

#[cfg(not(no_global_oom_handling))]
use self::spec_from_iter::SpecFromIter;

#[cfg(not(no_global_oom_handling))]
mod spec_from_iter;

#[cfg(not(no_global_oom_handling))]
use self::spec_extend::SpecExtend;

#[cfg(not(no_global_oom_handling))]
mod spec_extend;

/// 一种连续的可增长数组类型，写成 `Vec<T>`，它是 'vector' 的缩写。
///
/// # Examples
///
/// ```
/// let mut vec = Vec::new();
/// vec.push(1);
/// vec.push(2);
///
/// assert_eq!(vec.len(), 2);
/// assert_eq!(vec[0], 1);
///
/// assert_eq!(vec.pop(), Some(2));
/// assert_eq!(vec.len(), 1);
///
/// vec[0] = 7;
/// assert_eq!(vec[0], 7);
///
/// vec.extend([1, 2, 3]);
///
/// for x in &vec {
///     println!("{x}");
/// }
/// assert_eq!(vec, [7, 1, 2, 3]);
/// ```
///
/// [`vec!`] 宏提供方便初始化：
///
/// ```
/// let mut vec1 = vec![1, 2, 3];
/// vec1.push(4);
/// let vec2 = Vec::from([1, 2, 3, 4]);
/// assert_eq!(vec1, vec2);
/// ```
///
/// 它还可以使用给定值初始化 `Vec<T>` 的每个元素。
/// 这可能比在单独的步骤中执行分配和初始化更为有效，尤其是在初始化零的 vector 时：
///
/// ```
/// let vec = vec![0; 5];
/// assert_eq!(vec, [0, 0, 0, 0, 0]);
///
/// // 以下是等效的，但可能会更慢：
/// let mut vec = Vec::with_capacity(5);
/// vec.resize(5, 0);
/// assert_eq!(vec, [0, 0, 0, 0, 0]);
/// ```
///
/// 有关更多信息，请参见 [容量和重新分配](#capacity-and-reallocation)。
///
/// 使用 `Vec<T>` 作为有效的栈：
///
/// ```
/// let mut stack = Vec::new();
///
/// stack.push(1);
/// stack.push(2);
/// stack.push(3);
///
/// while let Some(top) = stack.pop() {
///     // 打印 3、2、1
///     println!("{top}");
/// }
/// ```
///
/// # Indexing
///
/// `Vec` 类型实现了 [`Index`] trait，因此允许按索引访问值。一个例子将更加明确：
///
/// ```
/// let v = vec![0, 2, 4, 6];
/// println!("{}", v[1]); // 它将显示 '2'
/// ```
///
/// 但是要小心：如果您尝试访问 `Vec` 中没有的索引，则您的软件将为 panic! 您不可以做这个：
///
/// ```should_panic
/// let v = vec![0, 2, 4, 6];
/// println!("{}", v[6]); // 它会 panic!
/// ```
///
/// 如果要检查索引是否在 `Vec` 中，请使用 [`get`] 和 [`get_mut`]。
///
/// # Slicing
///
/// `Vec` 可以是可变的。另一方面，切片是只读对象。
/// 要获得 [slice][prim@slice]，请使用 [`&`]。Example:
///
/// ```
/// fn read_slice(slice: &[usize]) {
///     // ...
/// }
///
/// let v = vec![0, 1];
/// read_slice(&v);
///
/// // ... 仅此而已！
/// // 您也可以这样：
/// let u: &[usize] = &v;
/// // 或像这样：
/// let u: &[_] = &v;
/// ```
///
/// 在 Rust 中，当您只想提供读取访问权限时，将切片作为参数而不是 vectors 传递是更常见的。[`String`] 和 [`&str`] 也是如此。
///
/// # 容量和重新分配
///
/// vector 的容量是为将添加到 vector 上的任何 future 元素分配的空间量。请勿将其与 vector 的长度混淆，后者指定 vector 中的实际元素数量。
/// 如果 vector 的长度超过其容量，则其容量将自动增加，但必须重新分配其元素。
///
/// 例如，容量为 10 且长度为 0 的 vector 将是一个空的 vector，具有 10 个以上元素的空间。将 10 个或更少的元素压入 vector 不会改变其容量或引起重新分配。
/// 但是，如果 vector 的长度增加到 11，则必须重新分配，这可能会很慢。因此，建议尽可能使用 [`Vec::with_capacity`] 来指定 vector 希望达到的大小。
///
/// # Guarantees
///
/// 由于其不可思议的基本特性，`Vec` 为其设计提供了很多保证。这样可以确保它在一般情况下的开销尽可能小，并且可以通过不安全的代码以原始方式正确地进行操作。请注意，这些保证是针对不合格的 `Vec<T>`。
/// 如果添加了其他类型参数 (例如，以支持自定义分配器)，则覆盖其默认值可能会更改行为。
///
/// 从根本上讲，`Vec` 始终是 (指针，容量，长度) 三元组。不多也不少。这些字段的顺序是完全不确定的，您应该使用适当的方法来修改它们。
/// 指针永远不会为空，因此此类型是经过空指针优化的。
///
/// 但是，指针实际上可能并不指向分配的内存。
/// 特别是，如果您通过 [`Vec::new`]，[`vec![]`][`vec!`]，[`Vec::with_capacity(0)`][`Vec::with_capacity`] 或通过在空 Vec 上调用 [`shrink_to_fit`] 来构造容量为 0 的 `Vec`，则它将不会分配内存。同样，如果将零大小的类型存储在 `Vec` 内，则不会为它们分配空间。
/// *Note 在这种情况下，`Vec` 可能不会报告 0* 的 [`capacity`]。
/// 当且仅当 <code>[mem::size_of::\<T>]\() * [capacity]\() > 0</code> 时，`Vec` 才会分配。
/// 一般来说，`Vec` 的分配细节非常微妙 -- 如果您打算使用 `Vec` 分配内存并将其用于其他用途 (或者传递给不安全的代码，或者构建您自己的内存支持集合)，请务必使用 `from_raw_parts` 处理此内存以恢复 `Vec`，然后丢弃它来释放此内存。
///
/// 如果一个 `Vec` 已分配了内存，那么它指向的内存在堆上（由分配器定义，Rust 被配置为默认使用），它的指针按顺序指向 [`len`] 个已初始化的连续元素（如果将其强制转换为切片，您会看到什么），然后是 <code>[capacity] - [len]</code> 逻辑上未初始化的连续元素。
///
///
/// 包含元素 `'a'` 和 `'b'` 且容量为 4 的 vector 可以如下所示。顶部是 `Vec` 结构体，它包含一个指向堆中分配头，长度和容量的指针。
/// 底部是堆上的分配，即连续的内存块。
///
/// ```text
///             ptr      len  capacity
///        +--------+--------+--------+
///        | 0x0123 |      2 |      4 |
///        +--------+--------+--------+
///             |
///             v
/// Heap   +--------+--------+--------+--------+
///        |    'a' |    'b' | uninit | uninit |
///        +--------+--------+--------+--------+
/// ```
///
/// - **uninit** 代表未初始化的内存，请参见 [`MaybeUninit`]。
/// - Note: ABI 不稳定，并且 `Vec` 不保证其内存布局 (包括字段顺序)。
///
/// `Vec` 永远不会执行小优化，其中元素实际上存储在栈中，原因有两个：
///
/// * 这将使不安全的代码更难以正确操作 `Vec`。如果仅移动 `Vec` 的内容，它的地址就不会稳定，因此，确定 `Vec` 是否实际分配了内存将更加困难。
///
/// * 这将惩罚一般情况，每次访问都会产生一个额外的分支。
///
/// `Vec` 永远不会自动缩小自己，即使完全为空。这样可以确保不会发生不必要的分配或释放。清空 `Vec`，然后将其填充回相同的 [`len`]，将不会引起对分配器的调用。如果您希望释放未使用的内存，请使用 [`shrink_to_fit`] 或 [`shrink_to`]。
///
/// 如果报告的容量足够，[`push`] 和 [`insert`] 将永远不会 (重新) 分配。如果 <code>[len] == [capacity]</code>，则 [`push`] 和 [`insert`] 将 (重新) 分配。也就是说，报告的容量是完全准确的，可以信赖。如果需要，它甚至可以用来手动释放 `Vec` 分配的内存。
/// 批量插入方法 *可能* 重新分配，即使在没有必要时也是如此。
///
/// `Vec` 不保证在满员时重新分配，或调用 [`reserve`] 时有任何特定的增长策略。当前的策略是基本的，使用非恒定增长因子可能是合乎需要的。无论使用哪种策略，当然都可以保证 *O*(1) 摊销 [`push`]。
///
/// `vec![x; n]`、`vec![a, b, c, d]` 和 [`Vec::with_capacity(n)`][`Vec::with_capacity`] 都将生产完全符合要求容量的 `Vec`。
/// 如果 <code>[len] == [capacity]</code>，(如 [`vec!`] 宏的情况)，则 `Vec<T>` 可以与 [`Box<[T]>`][owned slice] 相互转换，而无需重新分配或移动元素。
///
/// `Vec` 不会专门覆盖从中删除的任何数据，也不会专门保留它。它的未初始化内存是它可以使用的临时空间。通常，它只会执行最有效或最容易实现的任何事情。为了安全起见，请勿依赖删除的数据进行擦除。
/// 即使您丢弃了一个 `Vec`，它的缓冲区也可能会被另一个分配重用。
/// 即使您先将 `Vec` 的内存清零，这可能不会实际发生，因为优化器不认为这是一个必须保留的副作用。
/// 但是，有一种情况我们不会中断：使用 `unsafe` 代码写入多余的容量，然后增加长度以匹配，始终是有效的。
///
/// 当前，`Vec` 不保证删除元素的顺序。
/// 顺序过去已更改，并且可能会再次更改。
///
/// [`get`]: slice::get
/// [`get_mut`]: slice::get_mut
/// [`String`]: crate::string::String
/// [`&str`]: type@str
/// [`shrink_to_fit`]: Vec::shrink_to_fit
/// [`shrink_to`]: Vec::shrink_to
/// [capacity]: Vec::capacity
/// [`capacity`]: Vec::capacity
/// [mem::size_of::\<T>]: core::mem::size_of
/// [len]: Vec::len
/// [`len`]: Vec::len
/// [`push`]: Vec::push
/// [`insert`]: Vec::insert
/// [`reserve`]: Vec::reserve
/// [`MaybeUninit`]: core::mem::MaybeUninit
/// [owned slice]: Box
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "Vec")]
#[rustc_insignificant_dtor]
pub struct Vec<T, #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global> {
    buf: RawVec<T, A>,
    len: usize,
}

////////////////////////////////////////////////////////////////////////////////
// 固有方法
////////////////////////////////////////////////////////////////////////////////

impl<T> Vec<T> {
    /// 创建一个新的空 `Vec<T>`。
    ///
    /// 直到将元素压入 vector 为止，vector 才会分配。
    ///
    /// # Examples
    ///
    /// ```
    /// # #![allow(unused_mut)]
    /// let mut vec: Vec<i32> = Vec::new();
    /// ```
    #[inline]
    #[rustc_const_stable(feature = "const_vec_new", since = "1.39.0")]
    #[stable(feature = "rust1", since = "1.0.0")]
    #[must_use]
    pub const fn new() -> Self {
        Vec { buf: RawVec::NEW, len: 0 }
    }

    /// 创建一个至少具有指定容量的新的空 `Vec<T>`。
    ///
    /// vector 将能够保存至少 `capacity` 个元素而无需重新分配。
    /// 此方法允许分配比 `capacity` 更多的元素。
    /// 如果 `capacity` 为 0，则不会分配 vector。
    ///
    /// 需要注意的是，尽管返回的 vector 具有指定的最小*容量*，但 vector 的*长度*为零。
    ///
    /// 有关长度和容量之间差异的说明，请参见 *[容量和重新分配][Capacity and reallocation]*。
    ///
    /// 如果知道 `Vec` 的确切分配容量很重要，请始终在构建后使用 [`capacity`] 方法。
    ///
    /// 对于 `T` 是零大小类型的 `Vec<T>`，将不会进行分配，容量将始终为 `usize::MAX`。
    ///
    /// [Capacity and reallocation]: #capacity-and-reallocation
    /// [`capacity`]: Vec::capacity
    ///
    /// # Panics
    ///
    /// 如果新容量超过 `isize::MAX` 字节，就会出现 panics。
    ///
    /// # Examples
    ///
    /// ```
    /// let mut vec = Vec::with_capacity(10);
    ///
    /// // vector 不包含任何项，即使它具有更多功能
    /// assert_eq!(vec.len(), 0);
    /// assert!(vec.capacity() >= 10);
    ///
    /// // 这些都是在不重新分配的情况下完成的...
    /// for i in 0..10 {
    ///     vec.push(i);
    /// }
    /// assert_eq!(vec.len(), 10);
    /// assert!(vec.capacity() >= 10);
    ///
    /// // ...但这可能会使 vector 重新分配
    /// vec.push(11);
    /// assert_eq!(vec.len(), 11);
    /// assert!(vec.capacity() >= 11);
    ///
    /// // 零大小类型的 vector 总是会过度分配，因为不需要分配
    /////
    /// let vec_units = Vec::<()>::with_capacity(10);
    /// assert_eq!(vec_units.capacity(), usize::MAX);
    /// ```
    ///
    ///
    ///
    #[cfg(not(no_global_oom_handling))]
    #[inline]
    #[stable(feature = "rust1", since = "1.0.0")]
    #[must_use]
    pub fn with_capacity(capacity: usize) -> Self {
        Self::with_capacity_in(capacity, Global)
    }

    /// 直接从指针、容量和长度创建 `Vec<T>`。
    ///
    /// # Safety
    ///
    /// 这是非常不安全的，因为没有检查的不变量的数量：
    ///
    /// * `ptr` 必须使用全局分配器进行分配，例如通过 [`alloc::alloc`] 函数。
    /// * `T` 需要与分配的 `ptr` 具有相同的对齐方式。
    ///   (具有不太严格的对齐方式的 `T` 是不够的，对齐方式实际上必须等于 [`dealloc`] 的要求，即必须以相同的布局分配和释放内存。)
    ///
    /// * `T` 的大小乘以 `capacity` (以字节为单位的分配大小) 需要与分配指针的大小相同。
    /// (因为与对齐类似，必须使用相同的布局 `size` 来调用 [`dealloc`]。)
    /// * `length` 需要小于或等于 `capacity`。
    /// * 第一个 `length` 值必须是 `T` 类型的正确初始化值。
    /// * `capacity` 需要是分配指针的容量。
    /// * 分配的字节大小不得大于 `isize::MAX`。
    ///   请参见 [`pointer::offset`] 的安全文档。
    ///
    /// 通过 `Vec<T>` 分配的任何 `ptr` 始终支持这些要求。如果支持不，变体，则允许其他分配源。
    ///
    /// 违反这些可能会导致一些问题，比如破坏分配器的内部数据结构。
    /// 例如，从指向长度为 `size_t` 的 C `char` 数组的指针构建 `Vec<u8>` 通常是**不**安全的，只有当数组最初由 `Vec` 或 `String` 分配时，这样做才是安全的。
    /// 从 `Vec<u16>` 及其长度构建一个也不安全，因为分配器关心对齐方式，并且这两种类型具有不同的对齐方式。
    /// 缓冲区以对齐方式 2 (对于 `u16`) 分配，但在将其转换为 `Vec<u8>` 后，它将以对齐方式释放 1.
    /// 为避免这些问题，通常最好使用 [`slice::from_raw_parts`] 来进行铸造或转变。
    ///
    /// `ptr` 的所有权有效地转移到 `Vec<T>`，然后 `Vec<T>` 可以随意释放，重新分配或更改指针所指向的内存的内容。
    /// 调用此函数后，请确保没有其他任何东西使用该指针。
    ///
    /// [`String`]: crate::string::String
    /// [`alloc::alloc`]: crate::alloc::alloc
    /// [`dealloc`]: crate::alloc::GlobalAlloc::dealloc
    ///
    /// # Examples
    ///
    /// ```
    /// use std::ptr;
    /// use std::mem;
    ///
    /// let v = vec![1, 2, 3];
    ///
    // FIXME 在 vec_into_raw_parts 稳定后更新它
    /// // 防止运行 `v` 的析构函数，因此我们可以完全控制分配。
    /////
    /// let mut v = mem::ManuallyDrop::new(v);
    ///
    /// // Pull 有关 `v` 的各种重要信息
    /// let p = v.as_mut_ptr();
    /// let len = v.len();
    /// let cap = v.capacity();
    ///
    /// unsafe {
    ///     // 用 4、5、6 覆盖内存
    ///     for i in 0..len {
    ///         ptr::write(p.add(i), 4 + i);
    ///     }
    ///
    ///     // 将所有内容放回 Vec
    ///     let rebuilt = Vec::from_raw_parts(p, len, cap);
    ///     assert_eq!(rebuilt, [4, 5, 6]);
    /// }
    /// ```
    ///
    /// 使用在别处分配的内存:
    ///
    /// ```rust
    /// #![feature(allocator_api)]
    ///
    /// use std::alloc::{AllocError, Allocator, Global, Layout};
    ///
    /// fn main() {
    ///     let layout = Layout::array::<u32>(16).expect("overflow cannot happen");
    ///
    ///     let vec = unsafe {
    ///         let mem = match Global.allocate(layout) {
    ///             Ok(mem) => mem.cast::<u32>().as_ptr(),
    ///             Err(AllocError) => return,
    ///         };
    ///
    ///         mem.write(1_000_000);
    ///
    ///         Vec::from_raw_parts_in(mem, 1, 16, Global)
    ///     };
    ///
    ///     assert_eq!(vec, &[1_000_000]);
    ///     assert_eq!(vec.capacity(), 16);
    /// }
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[inline]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub unsafe fn from_raw_parts(ptr: *mut T, length: usize, capacity: usize) -> Self {
        unsafe { Self::from_raw_parts_in(ptr, length, capacity, Global) }
    }
}

impl<T, A: Allocator> Vec<T, A> {
    /// 创建一个新的空 `Vec<T, A>`。
    ///
    /// 直到将元素压入 vector 为止，vector 才会分配。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(allocator_api)]
    ///
    /// use std::alloc::System;
    ///
    /// # #[allow(unused_mut)]
    /// let mut vec: Vec<i32, _> = Vec::new_in(System);
    /// ```
    #[inline]
    #[unstable(feature = "allocator_api", issue = "32838")]
    pub const fn new_in(alloc: A) -> Self {
        Vec { buf: RawVec::new_in(alloc), len: 0 }
    }

    /// 使用提供的分配器创建一个至少具有指定容量的新的空 `Vec<T, A>`。
    ///
    /// vector 将能够保存至少 `capacity` 个元素而无需重新分配。
    /// 此方法允许分配比 `capacity` 更多的元素。
    /// 如果 `capacity` 为 0，则不会分配 vector。
    ///
    /// 需要注意的是，尽管返回的 vector 具有指定的最小*容量*，但 vector 的*长度*为零。
    ///
    /// 有关长度和容量之间差异的说明，请参见 *[容量和重新分配][Capacity and reallocation]*。
    ///
    /// 如果知道 `Vec` 的确切分配容量很重要，请始终在构建后使用 [`capacity`] 方法。
    ///
    /// 对于 `T` 是零大小类型的 `Vec<T, A>`，将不会进行分配，容量将始终为 `usize::MAX`。
    ///
    /// [Capacity and reallocation]: #capacity-and-reallocation
    /// [`capacity`]: Vec::capacity
    ///
    /// # Panics
    ///
    /// 如果新容量超过 `isize::MAX` 字节，就会出现 panics。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(allocator_api)]
    ///
    /// use std::alloc::System;
    ///
    /// let mut vec = Vec::with_capacity_in(10, System);
    ///
    /// // vector 不包含任何项，即使它具有更多功能
    /// assert_eq!(vec.len(), 0);
    /// assert!(vec.capacity() >= 10);
    ///
    /// // 这些都是在不重新分配的情况下完成的...
    /// for i in 0..10 {
    ///     vec.push(i);
    /// }
    /// assert_eq!(vec.len(), 10);
    /// assert!(vec.capacity() >= 10);
    ///
    /// // ...但这可能会使 vector 重新分配
    /// vec.push(11);
    /// assert_eq!(vec.len(), 11);
    /// assert!(vec.capacity() >= 11);
    ///
    /// // 零大小类型的 vector 总是会过度分配，因为不需要分配
    /////
    /// let vec_units = Vec::<(), System>::with_capacity_in(10, System);
    /// assert_eq!(vec_units.capacity(), usize::MAX);
    /// ```
    ///
    ///
    ///
    ///
    #[cfg(not(no_global_oom_handling))]
    #[inline]
    #[unstable(feature = "allocator_api", issue = "32838")]
    pub fn with_capacity_in(capacity: usize, alloc: A) -> Self {
        Vec { buf: RawVec::with_capacity_in(capacity, alloc), len: 0 }
    }

    /// 直接从指针、容量、长度和分配器创建 `Vec<T, A>`。
    ///
    /// # Safety
    ///
    /// 这是非常不安全的，因为没有检查的不变量的数量：
    ///
    /// * 通过给定的分配器 `alloc`，`ptr` 必须是 [*currently allocated*]。
    /// * `T` 需要与分配的 `ptr` 具有相同的对齐方式。
    ///   (具有不太严格的对齐方式的 `T` 是不够的，对齐方式实际上必须等于 [`dealloc`] 的要求，即必须以相同的布局分配和释放内存。)
    ///
    /// * `T` 的大小乘以 `capacity` (以字节为单位的分配大小) 需要与分配指针的大小相同。
    /// (因为与对齐类似，必须使用相同的布局 `size` 来调用 [`dealloc`]。)
    /// * `length` 需要小于或等于 `capacity`。
    /// * 第一个 `length` 值必须是 `T` 类型的正确初始化值。
    /// * `capacity` 需要 [*fit*] 分配指针的布局大小。
    /// * 分配的字节大小不得大于 `isize::MAX`。
    ///   请参见 [`pointer::offset`] 的安全文档。
    ///
    /// 通过 `Vec<T, A>` 分配的任何 `ptr` 始终支持这些要求。如果支持不，变体，则允许其他分配源。
    ///
    /// 违反这些可能会导致一些问题，比如破坏分配器的内部数据结构。例如，从指向长度为 `size_t` 的 C `char` 数组的指针构建 `Vec<u8>` 是不安全的。
    /// 从 `Vec<u16>` 及其长度构建一个也不安全，因为分配器关心对齐方式，并且这两种类型具有不同的对齐方式。
    /// 缓冲区以对齐方式 2 (对于 `u16`) 分配，但在将其转换为 `Vec<u8>` 后，它将以对齐方式释放 1.
    ///
    /// `ptr` 的所有权有效地转移到 `Vec<T>`，然后 `Vec<T>` 可以随意释放，重新分配或更改指针所指向的内存的内容。
    /// 调用此函数后，请确保没有其他任何东西使用该指针。
    ///
    /// [`String`]: crate::string::String
    /// [`dealloc`]: crate::alloc::GlobalAlloc::dealloc
    /// [*currently allocated*]: crate::alloc::Allocator#currently-allocated-memory
    /// [*fit*]: crate::alloc::Allocator#memory-fitting
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(allocator_api)]
    ///
    /// use std::alloc::System;
    ///
    /// use std::ptr;
    /// use std::mem;
    ///
    /// let mut v = Vec::with_capacity_in(3, System);
    /// v.push(1);
    /// v.push(2);
    /// v.push(3);
    ///
    // FIXME 在 vec_into_raw_parts 稳定后更新它
    /// // 防止运行 `v` 的析构函数，因此我们可以完全控制分配。
    /////
    /// let mut v = mem::ManuallyDrop::new(v);
    ///
    /// // Pull 有关 `v` 的各种重要信息
    /// let p = v.as_mut_ptr();
    /// let len = v.len();
    /// let cap = v.capacity();
    /// let alloc = v.allocator();
    ///
    /// unsafe {
    ///     // 用 4、5、6 覆盖内存
    ///     for i in 0..len {
    ///         ptr::write(p.add(i), 4 + i);
    ///     }
    ///
    ///     // 将所有内容放回 Vec
    ///     let rebuilt = Vec::from_raw_parts_in(p, len, cap, alloc.clone());
    ///     assert_eq!(rebuilt, [4, 5, 6]);
    /// }
    /// ```
    ///
    /// 使用在别处分配的内存:
    ///
    /// ```rust
    /// use std::alloc::{alloc, Layout};
    ///
    /// fn main() {
    ///     let layout = Layout::array::<u32>(16).expect("overflow cannot happen");
    ///     let vec = unsafe {
    ///         let mem = alloc(layout).cast::<u32>();
    ///         if mem.is_null() {
    ///             return;
    ///         }
    ///
    ///         mem.write(1_000_000);
    ///
    ///         Vec::from_raw_parts(mem, 1, 16)
    ///     };
    ///
    ///     assert_eq!(vec, &[1_000_000]);
    ///     assert_eq!(vec.capacity(), 16);
    /// }
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[inline]
    #[unstable(feature = "allocator_api", issue = "32838")]
    pub unsafe fn from_raw_parts_in(ptr: *mut T, length: usize, capacity: usize, alloc: A) -> Self {
        unsafe { Vec { buf: RawVec::from_raw_parts_in(ptr, capacity, alloc), len: length } }
    }

    /// 将 `Vec<T>` 分解为其原始组件。
    ///
    /// 返回指向底层数据的裸指针，vector 的长度 (以元素为单位) 和数据的已分配容量 (以元素为单位)。
    /// 这些参数与 [`from_raw_parts`] 的参数顺序相同。
    ///
    /// 调用此函数后，调用者负责 `Vec` 先前管理的内存。
    /// 唯一的方法是使用 [`from_raw_parts`] 函数将裸指针，长度和容量转换回 `Vec`，从而允许析构函数执行清除操作。
    ///
    ///
    /// [`from_raw_parts`]: Vec::from_raw_parts
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(vec_into_raw_parts)]
    /// let v: Vec<i32> = vec![-1, 0, 1];
    ///
    /// let (ptr, len, cap) = v.into_raw_parts();
    ///
    /// let rebuilt = unsafe {
    ///     // 现在，我们可以对组件进行更改，例如将裸指针转换为兼容类型。
    /////
    ///     let ptr = ptr as *mut u32;
    ///
    ///     Vec::from_raw_parts(ptr, len, cap)
    /// };
    /// assert_eq!(rebuilt, [4294967295, 0, 1]);
    /// ```
    ///
    ///
    ///
    ///
    #[unstable(feature = "vec_into_raw_parts", reason = "new API", issue = "65816")]
    pub fn into_raw_parts(self) -> (*mut T, usize, usize) {
        let mut me = ManuallyDrop::new(self);
        (me.as_mut_ptr(), me.len(), me.capacity())
    }

    /// 将 `Vec<T>` 分解为其原始组件。
    ///
    /// 返回指向底层数据的裸指针，vector 的长度 (以元素为单位)，数据的已分配容量 (以元素为单位) 以及分配器。
    /// 这些参数与 [`from_raw_parts_in`] 的参数顺序相同。
    ///
    /// 调用此函数后，调用者负责 `Vec` 先前管理的内存。
    /// 唯一的方法是使用 [`from_raw_parts_in`] 函数将裸指针，长度和容量转换回 `Vec`，从而允许析构函数执行清除操作。
    ///
    ///
    /// [`from_raw_parts_in`]: Vec::from_raw_parts_in
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(allocator_api, vec_into_raw_parts)]
    ///
    /// use std::alloc::System;
    ///
    /// let mut v: Vec<i32, System> = Vec::new_in(System);
    /// v.push(-1);
    /// v.push(0);
    /// v.push(1);
    ///
    /// let (ptr, len, cap, alloc) = v.into_raw_parts_with_alloc();
    ///
    /// let rebuilt = unsafe {
    ///     // 现在，我们可以对组件进行更改，例如将裸指针转换为兼容类型。
    /////
    ///     let ptr = ptr as *mut u32;
    ///
    ///     Vec::from_raw_parts_in(ptr, len, cap, alloc)
    /// };
    /// assert_eq!(rebuilt, [4294967295, 0, 1]);
    /// ```
    ///
    ///
    ///
    #[unstable(feature = "allocator_api", issue = "32838")]
    // #[unstable(feature = "vec_into_raw_parts", reason = "new API", issue = "65816")]
    pub fn into_raw_parts_with_alloc(self) -> (*mut T, usize, usize, A) {
        let mut me = ManuallyDrop::new(self);
        let len = me.len();
        let capacity = me.capacity();
        let ptr = me.as_mut_ptr();
        let alloc = unsafe { ptr::read(me.allocator()) };
        (ptr, len, capacity, alloc)
    }

    /// 返回 vector 在不重新分配的情况下可以容纳的元素总数。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// let mut vec: Vec<i32> = Vec::with_capacity(10);
    /// vec.push(42);
    /// assert!(vec.capacity() >= 10);
    /// ```
    #[inline]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn capacity(&self) -> usize {
        self.buf.capacity()
    }

    /// 为给定的 `Vec<T>` 至少保留 `additional` 个要插入的元素保留容量。集合可以保留更多空间来推测性地避免频繁的重新分配。
    ///
    /// 调用 `reserve` 后，容量将大于或等于 `self.len() + additional`。
    /// 如果容量已经足够，则不执行任何操作。
    ///
    /// # Panics
    ///
    /// 如果新容量超过 `isize::MAX` 字节，就会出现 panics。
    ///
    /// # Examples
    ///
    /// ```
    /// let mut vec = vec![1];
    /// vec.reserve(10);
    /// assert!(vec.capacity() >= 11);
    /// ```
    ///
    #[cfg(not(no_global_oom_handling))]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn reserve(&mut self, additional: usize) {
        self.buf.reserve(self.len, additional);
    }

    /// 为要插入给定 `Vec<T>` 的至少 `additional` 更多元素保留最小容量。
    ///
    /// 与 [`reserve`] 不同，这不会故意过度分配以推测性地避免频繁分配。
    /// 调用 `reserve_exact` 后，容量将大于或等于 `self.len() + additional`。
    /// 如果容量已经足够，则不执行任何操作。
    ///
    /// 请注意，分配器可能会给集合提供比其请求更多的空间。
    /// 因此，不能依靠容量来精确地最小化。
    /// 如果预计将来会插入，则最好使用 [`reserve`]。
    ///
    /// [`reserve`]: Vec::reserve
    ///
    /// # Panics
    ///
    /// 如果新容量超过 `isize::MAX` 字节，就会出现 panics。
    ///
    /// # Examples
    ///
    /// ```
    /// let mut vec = vec![1];
    /// vec.reserve_exact(10);
    /// assert!(vec.capacity() >= 11);
    /// ```
    ///
    #[cfg(not(no_global_oom_handling))]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn reserve_exact(&mut self, additional: usize) {
        self.buf.reserve_exact(self.len, additional);
    }

    /// 尝试为给 `Vec<T>` 至少插入 `additional` 个元素保留容量。
    /// 集合可以保留更多空间来推测性地避免频繁的重新分配。
    /// 调用 `try_reserve` 后，如果返回 `Ok(())`，容量将大于等于 `self.len() + additional`。
    ///
    /// 如果容量已经足够，则不执行任何操作。
    /// 即使发生错误，此方法也会保留内容。
    ///
    /// # Errors
    ///
    /// 如果容量溢出，或者分配器报告失败，则返回错误。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::collections::TryReserveError;
    ///
    /// fn process_data(data: &[u32]) -> Result<Vec<u32>, TryReserveError> {
    ///     let mut output = Vec::new();
    ///
    ///     // 预先保留内存，如果不能，则退出
    ///     output.try_reserve(data.len())?;
    ///
    ///     // 现在我们知道在我们复杂的工作中这不能 OOM
    ///     output.extend(data.iter().map(|&val| {
    ///         val * 2 + 5 // 非常复杂
    ///     }));
    ///
    ///     Ok(output)
    /// }
    /// # process_data(&[1, 2, 3]).expect("why is the test harness OOMing on 12 bytes?");
    /// ```
    ///
    #[stable(feature = "try_reserve", since = "1.57.0")]
    pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> {
        self.buf.try_reserve(self.len, additional)
    }

    /// 尝试为要插入给定 `Vec<T>` 的至少 `additional` 元素保留最小容量。
    /// 与 [`try_reserve`] 不同，这不会故意过度分配以推测性地避免频繁分配。
    /// 调用 `try_reserve_exact` 后，如果返回 `Ok(())`，则容量将大于或等于 `self.len() + additional`。
    ///
    /// 如果容量已经足够，则不执行任何操作。
    ///
    /// 请注意，分配器可能会给集合提供比其请求更多的空间。
    /// 因此，不能依靠容量来精确地最小化。
    /// 如果希望将来插入，则首选 [`try_reserve`]。
    ///
    /// [`try_reserve`]: Vec::try_reserve
    ///
    /// # Errors
    ///
    /// 如果容量溢出，或者分配器报告失败，则返回错误。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::collections::TryReserveError;
    ///
    /// fn process_data(data: &[u32]) -> Result<Vec<u32>, TryReserveError> {
    ///     let mut output = Vec::new();
    ///
    ///     // 预先保留内存，如果不能，则退出
    ///     output.try_reserve_exact(data.len())?;
    ///
    ///     // 现在我们知道在我们复杂的工作中这不能 OOM
    ///     output.extend(data.iter().map(|&val| {
    ///         val * 2 + 5 // 非常复杂
    ///     }));
    ///
    ///     Ok(output)
    /// }
    /// # process_data(&[1, 2, 3]).expect("why is the test harness OOMing on 12 bytes?");
    /// ```
    ///
    ///
    #[stable(feature = "try_reserve", since = "1.57.0")]
    pub fn try_reserve_exact(&mut self, additional: usize) -> Result<(), TryReserveError> {
        self.buf.try_reserve_exact(self.len, additional)
    }

    /// 尽可能缩小 vector 的容量。
    ///
    /// 它将降低到尽可能接近的长度，但是分配器仍可以通知 vector，还有空间可以容纳更多元素。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// let mut vec = Vec::with_capacity(10);
    /// vec.extend([1, 2, 3]);
    /// assert!(vec.capacity() >= 10);
    /// vec.shrink_to_fit();
    /// assert!(vec.capacity() >= 3);
    /// ```
    #[cfg(not(no_global_oom_handling))]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn shrink_to_fit(&mut self) {
        // 容量永远不会小于长度，并且当它们相等时没有任何事可做，因此我们可以通过仅以更大的容量进行调用来避免 `RawVec::shrink_to_fit` 中的 panic 情况。
        //
        //
        if self.capacity() > self.len {
            self.buf.shrink_to_fit(self.len);
        }
    }

    /// 将 vector 的容量减小一个下限。
    ///
    /// 容量将至少保持与长度和提供的值一样大。
    ///
    ///
    /// 如果当前容量小于下限，则为无操作。
    ///
    /// # Examples
    ///
    /// ```
    /// let mut vec = Vec::with_capacity(10);
    /// vec.extend([1, 2, 3]);
    /// assert!(vec.capacity() >= 10);
    /// vec.shrink_to(4);
    /// assert!(vec.capacity() >= 4);
    /// vec.shrink_to(0);
    /// assert!(vec.capacity() >= 3);
    /// ```
    #[cfg(not(no_global_oom_handling))]
    #[stable(feature = "shrink_to", since = "1.56.0")]
    pub fn shrink_to(&mut self, min_capacity: usize) {
        if self.capacity() > min_capacity {
            self.buf.shrink_to_fit(cmp::max(self.len, min_capacity));
        }
    }

    /// 将 vector 转换为 [`Box<[T]>`][owned slice]。
    ///
    /// 如果 vector 有多余的容量，它的项将被移动到一个新分配的容量正好合适的缓冲区中。
    ///
    ///
    /// [owned slice]: Box
    ///
    /// # Examples
    ///
    /// ```
    /// let v = vec![1, 2, 3];
    ///
    /// let slice = v.into_boxed_slice();
    /// ```
    ///
    /// 任何多余的容量都将被删除：
    ///
    /// ```
    /// let mut vec = Vec::with_capacity(10);
    /// vec.extend([1, 2, 3]);
    ///
    /// assert!(vec.capacity() >= 10);
    /// let slice = vec.into_boxed_slice();
    /// assert_eq!(slice.into_vec().capacity(), 3);
    /// ```
    #[cfg(not(no_global_oom_handling))]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn into_boxed_slice(mut self) -> Box<[T], A> {
        unsafe {
            self.shrink_to_fit();
            let me = ManuallyDrop::new(self);
            let buf = ptr::read(&me.buf);
            let len = me.len();
            buf.into_box(len).assume_init()
        }
    }

    /// 缩短 vector，保留前 `len` 个元素，并丢弃其他元素。
    ///
    /// 如果 `len` 大于 vector 的当前长度，则无效。
    ///
    /// [`drain`] 方法可以模拟 `truncate`，但是会导致多余的元素被返回而不是丢弃。
    ///
    ///
    /// 请注意，此方法对 vector 的已分配容量没有影响。
    ///
    /// # Examples
    ///
    /// 将五个元素 vector 截断为两个元素：
    ///
    /// ```
    /// let mut vec = vec![1, 2, 3, 4, 5];
    /// vec.truncate(2);
    /// assert_eq!(vec, [1, 2]);
    /// ```
    ///
    /// 当 `len` 大于 vector 的当前长度时，不会发生截断：
    ///
    /// ```
    /// let mut vec = vec![1, 2, 3];
    /// vec.truncate(8);
    /// assert_eq!(vec, [1, 2, 3]);
    /// ```
    ///
    /// 在 `len == 0` 等效于调用 [`clear`] 方法时截断。
    ///
    /// ```
    /// let mut vec = vec![1, 2, 3];
    /// vec.truncate(0);
    /// assert_eq!(vec, []);
    /// ```
    ///
    /// [`clear`]: Vec::clear
    /// [`drain`]: Vec::drain
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn truncate(&mut self, len: usize) {
        // 这是安全的，因为：
        //
        // * 传递给 `drop_in_place` 的切片有效； `len > self.len` 的情况避免了创建无效的切片，并且
        // * vector 的 `len` 会在调用 `drop_in_place` 之前缩小，这样，如果 `drop_in_place` 一次到达 panic，则两次值都不会丢失 (如果两次 panics，则程序将中止)。
        //
        //
        //
        unsafe {
            // Note: 故意是 `>`，而不是 `>=`。
            //       在某些情况下，将其更改为 `>=` 会对性能产生负面影响。
            //       有关更多信息，请参见 #78884。
            if len > self.len {
                return;
            }
            let remaining_len = self.len - len;
            let s = ptr::slice_from_raw_parts_mut(self.as_mut_ptr().add(len), remaining_len);
            self.len = len;
            ptr::drop_in_place(s);
        }
    }

    /// 提取包含整个 vector 的切片。
    ///
    /// 等效于 `&s[..]`。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::io::{self, Write};
    /// let buffer = vec![1, 2, 3, 5, 8];
    /// io::sink().write(buffer.as_slice()).unwrap();
    /// ```
    #[inline]
    #[stable(feature = "vec_as_slice", since = "1.7.0")]
    pub fn as_slice(&self) -> &[T] {
        self
    }

    /// 提取整个 vector 的可变切片。
    ///
    /// 等效于 `&mut s[..]`。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::io::{self, Read};
    /// let mut buffer = vec![0; 3];
    /// io::repeat(0b101).read_exact(buffer.as_mut_slice()).unwrap();
    /// ```
    #[inline]
    #[stable(feature = "vec_as_slice", since = "1.7.0")]
    pub fn as_mut_slice(&mut self) -> &mut [T] {
        self
    }

    /// 返回一个零裸指针到 vector0 的缓冲区，或者如果 Z0 没有分配，则返回一个对大小有效的悬垂裸指针。
    ///
    /// 调用者必须确保 vector 比该函数返回的指针寿命更长，否则它将最终指向垃圾。
    /// 修改 vector 可能会导致重新分配其缓冲区，这还会使指向该缓冲区的任何指针无效。
    ///
    /// 调用者还必须确保指针 (non-transitively) 所指向的内存 (从 `UnsafeCell` 内部除外) 永远不会使用此指针或从其派生的任何指针写入。
    /// 如果需要更改切片的内容，请使用 [`as_mut_ptr`]。
    ///
    /// # Examples
    ///
    /// ```
    /// let x = vec![1, 2, 4];
    /// let x_ptr = x.as_ptr();
    ///
    /// unsafe {
    ///     for i in 0..x.len() {
    ///         assert_eq!(*x_ptr.add(i), 1 << i);
    ///     }
    /// }
    /// ```
    ///
    /// [`as_mut_ptr`]: Vec::as_mut_ptr
    ///
    ///
    ///
    ///
    #[stable(feature = "vec_as_ptr", since = "1.37.0")]
    #[inline]
    pub fn as_ptr(&self) -> *const T {
        // 我们对同名的切片方法进行阴影处理，以避免通过 `deref`，它会产生中间引用。
        //
        self.buf.ptr()
    }

    /// 返回指向 vector 缓冲区的不安全错误指针，或者如果 Z0vector 没有分配，则返回对零大小读取有效的悬垂裸向量。
    ///
    ///
    /// 调用者必须确保 vector 比该函数返回的指针寿命更长，否则它将最终指向垃圾。
    /// 修改 vector 可能会导致重新分配其缓冲区，这还会使指向该缓冲区的任何指针无效。
    ///
    /// # Examples
    ///
    /// ```
    /// // 分配足够大的 vector 以容纳 4 个元素。
    /// let size = 4;
    /// let mut x: Vec<i32> = Vec::with_capacity(size);
    /// let x_ptr = x.as_mut_ptr();
    ///
    /// // 通过裸指针写入初始化元素，然后设置长度。
    /// unsafe {
    ///     for i in 0..size {
    ///         *x_ptr.add(i) = i as i32;
    ///     }
    ///     x.set_len(size);
    /// }
    /// assert_eq!(&*x, &[0, 1, 2, 3]);
    /// ```
    ///
    ///
    #[stable(feature = "vec_as_ptr", since = "1.37.0")]
    #[inline]
    pub fn as_mut_ptr(&mut self) -> *mut T {
        // 我们对同名的切片方法进行阴影处理，以避免通过 `deref_mut`，它会产生中间引用。
        //
        self.buf.ptr()
    }

    /// 返回底层分配器的引用。
    #[unstable(feature = "allocator_api", issue = "32838")]
    #[inline]
    pub fn allocator(&self) -> &A {
        self.buf.allocator()
    }

    /// 将 vector 的长度强制为 `new_len`。
    ///
    /// 这是一个低级操作，不维护该类型的任何正常不变量。
    /// 通常，使用安全操作之一 (例如 [`truncate`]，[`resize`]，[`extend`] 或 [`clear`]) 来更改 vector 的长度。
    ///
    ///
    /// [`truncate`]: Vec::truncate
    /// [`resize`]: Vec::resize
    /// [`extend`]: Extend::extend
    /// [`clear`]: Vec::clear
    ///
    /// # Safety
    ///
    /// - `new_len` 必须小于或等于 [`capacity()`]。
    /// - `old_len..new_len` 上的元素必须初始化。
    ///
    /// [`capacity()`]: Vec::capacity
    ///
    /// # Examples
    ///
    /// 当 vector 用作其他代码的缓冲区时，尤其是在 FFI 上，此方法很有用：
    ///
    /// ```no_run
    /// # #![allow(dead_code)]
    /// # // 这只是 doc 示例的基本框架；
    /// # // 不要将其用作真实库的起点。
    /// # pub struct StreamWrapper { strm: *mut std::ffi::c_void }
    /// # const Z_OK: i32 = 0;
    /// # extern "C" {
    /// #     fn deflateGetDictionary(
    /// #         strm: *mut std::ffi::c_void,
    /// #         dictionary: *mut u8,
    /// #         dictLength: *mut usize,
    /// #     ) -> i32;
    /// # }
    /// # impl StreamWrapper {
    /// pub fn get_dictionary(&self) -> Option<Vec<u8>> {
    ///     // 根据 FFI 方法的文档，32768 字节总是足够的。
    ///     let mut dict = Vec::with_capacity(32_768);
    ///     let mut dict_length = 0;
    ///     // SAFETY: 当 `deflateGetDictionary` 返回 `Z_OK` 时，它认为：
    ///     // 1. `dict_length` 元素已初始化。
    ///     // 2.
    ///     // `dict_length` <= 使 `set_len` 对调用安全的容量 (32_768)。
    ///     unsafe {
    ///         // 使 FFI 调用...
    ///         let r = deflateGetDictionary(self.strm, dict.as_mut_ptr(), &mut dict_length);
    ///         if r == Z_OK {
    ///             // ...并将长度更新为初始化的长度。
    ///             dict.set_len(dict_length);
    ///             Some(dict)
    ///         } else {
    ///             None
    ///         }
    ///     }
    /// }
    /// # }
    /// ```
    ///
    /// 尽管下面的示例是正确的，但由于 `set_len` 调用之前未释放内部 vectors，所以存在内存泄漏：
    ///
    /// ```
    /// let mut vec = vec![vec![1, 0, 0],
    ///                    vec![0, 1, 0],
    ///                    vec![0, 0, 1]];
    /// // SAFETY:
    /// // 1. `old_len..0` 为空，因此不需要初始化任何元素。
    /// // 2. `0 <= capacity` 无论 `capacity` 是什么，它总是保持不变。
    /// unsafe {
    ///     vec.set_len(0);
    /// }
    /// ```
    ///
    /// 通常，在这里，人们将使用 [`clear`] 来正确丢弃内容，因此不会泄漏内存。
    ///
    ///
    ///
    ///
    #[inline]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub unsafe fn set_len(&mut self, new_len: usize) {
        debug_assert!(new_len <= self.capacity());

        self.len = new_len;
    }

    /// 从 vector 中删除一个元素并返回它。
    ///
    /// 删除的元素被 vector 的最后一个元素替换。
    ///
    /// 这不会保留顺序，而是 *O*(1)。
    /// 如果需要保留元素顺序，请改用 [`remove`]。
    ///
    /// [`remove`]: Vec::remove
    ///
    /// # Panics
    ///
    /// 如果 `index` 越界，就会出现 panics。
    ///
    /// # Examples
    ///
    /// ```
    /// let mut v = vec!["foo", "bar", "baz", "qux"];
    ///
    /// assert_eq!(v.swap_remove(1), "bar");
    /// assert_eq!(v, ["foo", "qux", "baz"]);
    ///
    /// assert_eq!(v.swap_remove(0), "foo");
    /// assert_eq!(v, ["baz", "qux"]);
    /// ```
    #[inline]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn swap_remove(&mut self, index: usize) -> T {
        #[cold]
        #[inline(never)]
        fn assert_failed(index: usize, len: usize) -> ! {
            panic!("swap_remove index (is {index}) should be < len (is {len})");
        }

        let len = self.len();
        if index >= len {
            assert_failed(index, len);
        }
        unsafe {
            // 我们用最后一个元素替换 self[index]。
            // 请注意，如果上面的边界检查成功，则必须有最后一个元素 (可以是 self[index] 本身)。
            //
            let value = ptr::read(self.as_ptr().add(index));
            let base_ptr = self.as_mut_ptr();
            ptr::copy(base_ptr.add(len - 1), base_ptr.add(index), 1);
            self.set_len(len - 1);
            value
        }
    }

    /// 在 vector 内的位置 `index` 处插入一个元素，并将其后的所有元素向右移动。
    ///
    ///
    /// # Panics
    ///
    /// 如果为 `index > len`，就会出现 panics。
    ///
    /// # Examples
    ///
    /// ```
    /// let mut vec = vec![1, 2, 3];
    /// vec.insert(1, 4);
    /// assert_eq!(vec, [1, 4, 2, 3]);
    /// vec.insert(4, 5);
    /// assert_eq!(vec, [1, 4, 2, 3, 5]);
    /// ```
    #[cfg(not(no_global_oom_handling))]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn insert(&mut self, index: usize, element: T) {
        #[cold]
        #[inline(never)]
        fn assert_failed(index: usize, len: usize) -> ! {
            panic!("insertion index (is {index}) should be <= len (is {len})");
        }

        let len = self.len();

        // 新元素的空间
        if len == self.buf.capacity() {
            self.reserve(1);
        }

        unsafe {
            // 绝对可靠的地方，可以带来新的值
            //
            {
                let p = self.as_mut_ptr().add(index);
                if index < len {
                    // 转移一切以腾出空间。
                    // (将第 index 个元素复制到两个连续的位置。)
                    ptr::copy(p, p.add(1), len - index);
                } else if index == len {
                    // 没有元素需要移动。
                } else {
                    assert_failed(index, len);
                }
                // 将其写入，覆盖第 index 个元素的第一个副本。
                //
                ptr::write(p, element);
            }
            self.set_len(len + 1);
        }
    }

    /// 删除并返回 vector 中位置 `index` 的元素，将其后的所有元素向左移动。
    ///
    ///
    /// Note: 因为这会转移其余元素，所以它的最坏情况性能为 *O*(*n*)。
    /// 如果不需要保留元素的顺序，请改用 [`swap_remove`]。
    /// 如果您想从 `Vec` 的开头删除元素，请考虑改用 [`VecDeque::pop_front`]。
    ///
    /// [`swap_remove`]: Vec::swap_remove
    /// [`VecDeque::pop_front`]: crate::collections::VecDeque::pop_front
    ///
    /// # Panics
    ///
    /// 如果 `index` 越界，就会出现 panics。
    ///
    /// # Examples
    ///
    /// ```
    /// let mut v = vec![1, 2, 3];
    /// assert_eq!(v.remove(1), 2);
    /// assert_eq!(v, [1, 3]);
    /// ```
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    #[track_caller]
    pub fn remove(&mut self, index: usize) -> T {
        #[cold]
        #[inline(never)]
        #[track_caller]
        fn assert_failed(index: usize, len: usize) -> ! {
            panic!("removal index (is {index}) should be < len (is {len})");
        }

        let len = self.len();
        if index >= len {
            assert_failed(index, len);
        }
        unsafe {
            // infallible
            let ret;
            {
                // 我们要去的地方。
                let ptr = self.as_mut_ptr().add(index);
                // 将其复制出来，不安全地在栈上和 vector 中同时拥有该值的副本。
                //
                ret = ptr::read(ptr);

                // 向下移动所有内容以填充该位置。
                ptr::copy(ptr.add(1), ptr, len - index - 1);
            }
            self.set_len(len - 1);
            ret
        }
    }

    /// 仅保留谓词指定的元素。
    ///
    /// 换句话说，删除所有 `f(&e)` 返回 `false` 的 `e` 元素。
    /// 此方法在原位运行，以原始顺序恰好一次访问每个元素，并保留保留元素的顺序。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// let mut vec = vec![1, 2, 3, 4];
    /// vec.retain(|&x| x % 2 == 0);
    /// assert_eq!(vec, [2, 4]);
    /// ```
    ///
    /// 由于按原始顺序仅对元素进行过一次访问，因此可以使用外部状态来确定要保留哪些元素。
    ///
    /// ```
    /// let mut vec = vec![1, 2, 3, 4, 5];
    /// let keep = [false, true, true, false, true];
    /// let mut iter = keep.iter();
    /// vec.retain(|_| *iter.next().unwrap());
    /// assert_eq!(vec, [2, 3, 5]);
    /// ```
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn retain<F>(&mut self, mut f: F)
    where
        F: FnMut(&T) -> bool,
    {
        self.retain_mut(|elem| f(elem));
    }

    /// 仅保留由谓词指定的元素，并将一个可变引用传递给它。
    ///
    /// 换句话说，删除所有元素 `e`，使得 `f(&mut e)` 返回 `false`。
    /// 此方法在原位运行，以原始顺序恰好一次访问每个元素，并保留保留元素的顺序。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// let mut vec = vec![1, 2, 3, 4];
    /// vec.retain_mut(|x| if *x <= 3 {
    ///     *x += 1;
    ///     true
    /// } else {
    ///     false
    /// });
    /// assert_eq!(vec, [2, 3, 4]);
    /// ```
    #[stable(feature = "vec_retain_mut", since = "1.61.0")]
    pub fn retain_mut<F>(&mut self, mut f: F)
    where
        F: FnMut(&mut T) -> bool,
    {
        let original_len = self.len();
        // 如果不执行丢弃守卫，请避免双重丢弃，因为在此过程中我们可能会产生一些漏洞。
        //
        unsafe { self.set_len(0) };

        // Vec: [Kept, Kept, Hole, Hole, Hole, Hole, Unchecked, Unchecked]
        //      |<-              processed len   ->| ^- next to check
        //                  |<-  deleted cnt     ->|
        //      |<-              original_len                          ->| Kept: Elements which predicate returns true on.
        //
        // Hole: 移动或丢弃的元素插槽。
        // 未检查：未检查的有效元素。
        //
        // 当谓词或元素的 `drop` 发生 panic 时，将调用此丢弃守卫。
        // 它将未经检查的元素移动到覆盖 holes 和 `set_len` 的正确长度。
        // 在谓词和 `drop` 永远不会 panic 的情况下，它将被优化。
        struct BackshiftOnDrop<'a, T, A: Allocator> {
            v: &'a mut Vec<T, A>,
            processed_len: usize,
            deleted_cnt: usize,
            original_len: usize,
        }

        impl<T, A: Allocator> Drop for BackshiftOnDrop<'_, T, A> {
            fn drop(&mut self) {
                if self.deleted_cnt > 0 {
                    // SAFETY: 尾随的未检查项必须有效，因为我们从不碰它们。
                    unsafe {
                        ptr::copy(
                            self.v.as_ptr().add(self.processed_len),
                            self.v.as_mut_ptr().add(self.processed_len - self.deleted_cnt),
                            self.original_len - self.processed_len,
                        );
                    }
                }
                // SAFETY: 填充完 holes 后，所有项都存储在连续的内存中。
                unsafe {
                    self.v.set_len(self.original_len - self.deleted_cnt);
                }
            }
        }

        let mut g = BackshiftOnDrop { v: self, processed_len: 0, deleted_cnt: 0, original_len };

        fn process_loop<F, T, A: Allocator, const DELETED: bool>(
            original_len: usize,
            f: &mut F,
            g: &mut BackshiftOnDrop<'_, T, A>,
        ) where
            F: FnMut(&mut T) -> bool,
        {
            while g.processed_len != original_len {
                // SAFETY: 未经检查的元素必须有效。
                let cur = unsafe { &mut *g.v.as_mut_ptr().add(g.processed_len) };
                if !f(cur) {
                    // 如果 `drop_in_place` 发生 panic，请提前提早避免双重丢弃。
                    g.processed_len += 1;
                    g.deleted_cnt += 1;
                    // SAFETY: 丢弃后，我们再也不会触碰此元素。
                    unsafe { ptr::drop_in_place(cur) };
                    // 我们已经提前了 counter。
                    if DELETED {
                        continue;
                    } else {
                        break;
                    }
                }
                if DELETED {
                    // SAFETY: `deleted_cnt`> 0，因此 hole 插槽不得与当前元素重叠。
                    // 我们使用 copy 进行移动，从此再也不会触碰此元素。
                    unsafe {
                        let hole_slot = g.v.as_mut_ptr().add(g.processed_len - g.deleted_cnt);
                        ptr::copy_nonoverlapping(cur, hole_slot, 1);
                    }
                }
                g.processed_len += 1;
            }
        }

        // 第 1 阶段：没有删除任何内容。
        process_loop::<F, T, A, false>(original_len, &mut f, &mut g);

        // 第 2 阶段：删除了一些元素。
        process_loop::<F, T, A, true>(original_len, &mut f, &mut g);

        // 所有项均已处理。LLVM 可以将其优化为 `set_len`。
        drop(g);
    }

    /// 删除 vector 中除第一个连续元素之外的所有元素，这些元素解析为同一键。
    ///
    ///
    /// 如果对 vector 进行了排序，则将删除所有重复项。
    ///
    /// # Examples
    ///
    /// ```
    /// let mut vec = vec![10, 20, 21, 30, 20];
    ///
    /// vec.dedup_by_key(|i| *i / 10);
    ///
    /// assert_eq!(vec, [10, 20, 30, 20]);
    /// ```
    #[stable(feature = "dedup_by", since = "1.16.0")]
    #[inline]
    pub fn dedup_by_key<F, K>(&mut self, mut key: F)
    where
        F: FnMut(&mut T) -> K,
        K: PartialEq,
    {
        self.dedup_by(|a, b| key(a) == key(b))
    }

    /// 移除 vector 中满足给定相等关系的所有连续元素，但第一个除外。
    ///
    /// `same_bucket` 函数被传递给 vector 中的两个元素，并且必须确定这些元素比较是否相等。
    /// 元素以与它们在切片中的顺序相反的顺序传递，因此，如果 `same_bucket(a, b)` 返回 `true`，则删除 `a`。
    ///
    ///
    /// 如果对 vector 进行了排序，则将删除所有重复项。
    ///
    /// # Examples
    ///
    /// ```
    /// let mut vec = vec!["foo", "bar", "Bar", "baz", "bar"];
    ///
    /// vec.dedup_by(|a, b| a.eq_ignore_ascii_case(b));
    ///
    /// assert_eq!(vec, ["foo", "bar", "baz", "bar"]);
    /// ```
    ///
    #[stable(feature = "dedup_by", since = "1.16.0")]
    pub fn dedup_by<F>(&mut self, mut same_bucket: F)
    where
        F: FnMut(&mut T, &mut T) -> bool,
    {
        let len = self.len();
        if len <= 1 {
            return;
        }

        /* INVARIANT: vec.len() > read >= write > write-1 >= 0 */
        struct FillGapOnDrop<'a, T, A: core::alloc::Allocator> {
            /* Offset of the element we want to check if it is duplicate */
            read: usize,

            /* Offset of the place where we want to place the non-duplicate
             * when we find it. */
            write: usize,

            /* The Vec that would need correction if `same_bucket` panicked */
            vec: &'a mut Vec<T, A>,
        }

        impl<'a, T, A: core::alloc::Allocator> Drop for FillGapOnDrop<'a, T, A> {
            fn drop(&mut self) {
                /* This code gets executed when `same_bucket` panics */

                /* SAFETY: invariant guarantees that `read - write`
                 * and `len - read` never overflow and that the copy is always
                 * in-bounds. */
                unsafe {
                    let ptr = self.vec.as_mut_ptr();
                    let len = self.vec.len();

                    /* How many items were left when `same_bucket` panicked.
                     * Basically vec[read..].len() */
                    let items_left = len.wrapping_sub(self.read);

                    /* Pointer to first item in vec[write..write+items_left] slice */
                    let dropped_ptr = ptr.add(self.write);
                    /* Pointer to first item in vec[read..] slice */
                    let valid_ptr = ptr.add(self.read);

                    /* Copy `vec[read..]` to `vec[write..write+items_left]`.
                     * The slices can overlap, so `copy_nonoverlapping` cannot be used */
                    ptr::copy(valid_ptr, dropped_ptr, items_left);

                    /* How many items have been already dropped
                     * Basically vec[read..write].len() */
                    let dropped = self.read.wrapping_sub(self.write);

                    self.vec.set_len(len - dropped);
                }
            }
        }

        let mut gap = FillGapOnDrop { read: 1, write: 1, vec: self };
        let ptr = gap.vec.as_mut_ptr();

        /* Drop items while going through Vec, it should be more efficient than
         * doing slice partition_dedup + truncate */

        /* SAFETY: Because of the invariant, read_ptr, prev_ptr and write_ptr
         * are always in-bounds and read_ptr never aliases prev_ptr */
        unsafe {
            while gap.read < len {
                let read_ptr = ptr.add(gap.read);
                let prev_ptr = ptr.add(gap.write.wrapping_sub(1));

                if same_bucket(&mut *read_ptr, &mut *prev_ptr) {
                    // 现在增加 `gap.read` 因为丢弃可能 panic。
                    gap.read += 1;
                    /* We have found duplicate, drop it in-place */
                    ptr::drop_in_place(read_ptr);
                } else {
                    let write_ptr = ptr.add(gap.write);

                    /* Because `read_ptr` can be equal to `write_ptr`, we either
                     * have to use `copy` or conditional `copy_nonoverlapping`.
                     * Looks like the first option is faster. */
                    ptr::copy(read_ptr, write_ptr, 1);

                    /* We have filled that place, so go further */
                    gap.write += 1;
                    gap.read += 1;
                }
            }

            /* Technically we could let `gap` clean up with its Drop, but
             * when `same_bucket` is guaranteed to not panic, this bloats a little
             * the codegen, so we just do it manually */
            gap.vec.set_len(gap.write);
            mem::forget(gap);
        }
    }

    /// 将元素追加到集合的后面。
    ///
    /// # Panics
    ///
    /// 如果新容量超过 `isize::MAX` 字节，就会出现 panics。
    ///
    /// # Examples
    ///
    /// ```
    /// let mut vec = vec![1, 2];
    /// vec.push(3);
    /// assert_eq!(vec, [1, 2, 3]);
    /// ```
    #[cfg(not(no_global_oom_handling))]
    #[inline]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn push(&mut self, value: T) {
        // 如果我们要分配 > isize::MAX 字节，或者如果零大小的类型的长度增量溢出，则将为 panic 或中止。
        //
        if self.len == self.buf.capacity() {
            self.buf.reserve_for_push(self.len);
        }
        unsafe {
            let end = self.as_mut_ptr().add(self.len);
            ptr::write(end, value);
            self.len += 1;
        }
    }

    /// 如果有足够的备用容量，则，追加，一个元素，否则该元素返回错误。
    ///
    ///
    /// 与 [`push`] 不同，此方法在容量不足时不会重新分配。
    /// 调用者应使用 [`reserve`] 或 [`try_reserve`] 以确保有足够的容量。
    ///
    /// [`push`]: Vec::push
    /// [`reserve`]: Vec::reserve
    /// [`try_reserve`]: Vec::try_reserve
    ///
    /// # Examples
    ///
    /// [`FromIterator`] 的手动、无 panic 替代品:
    ///
    /// ```
    /// #![feature(vec_push_within_capacity)]
    ///
    /// use std::collections::TryReserveError;
    /// fn from_iter_fallible<T>(iter: impl Iterator<Item=T>) -> Result<Vec<T>, TryReserveError> {
    ///     let mut vec = Vec::new();
    ///     for value in iter {
    ///         if let Err(value) = vec.push_within_capacity(value) {
    ///             vec.try_reserve(1)?;
    ///             // 这不会失败，上一行要么返回要么添加了至少 1 个空闲槽
    ///             let _ = vec.push_within_capacity(value);
    ///         }
    ///     }
    ///     Ok(vec)
    /// }
    /// assert_eq!(from_iter_fallible(0..100), Ok(Vec::from_iter(0..100)));
    /// ```
    #[inline]
    #[unstable(feature = "vec_push_within_capacity", issue = "100486")]
    pub fn push_within_capacity(&mut self, value: T) -> Result<(), T> {
        if self.len == self.buf.capacity() {
            return Err(value);
        }
        unsafe {
            let end = self.as_mut_ptr().add(self.len);
            ptr::write(end, value);
            self.len += 1;
        }
        Ok(())
    }

    /// 从 vector 中删除最后一个元素并返回它; 如果它为空，则返回 [`None`]。
    ///
    /// 如果您想弹出第一个元素，请考虑改用 [`VecDeque::pop_front`]。
    ///
    ///
    /// [`VecDeque::pop_front`]: crate::collections::VecDeque::pop_front
    ///
    /// # Examples
    ///
    /// ```
    /// let mut vec = vec![1, 2, 3];
    /// assert_eq!(vec.pop(), Some(3));
    /// assert_eq!(vec, [1, 2]);
    /// ```
    ///
    #[inline]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn pop(&mut self) -> Option<T> {
        if self.len == 0 {
            None
        } else {
            unsafe {
                self.len -= 1;
                Some(ptr::read(self.as_ptr().add(self.len())))
            }
        }
    }

    /// 将 `other` 的所有元素移到 `self`，将 `other` 留空。
    ///
    /// # Panics
    ///
    /// 如果新容量超过 `isize::MAX` 字节，就会出现 panics。
    ///
    /// # Examples
    ///
    /// ```
    /// let mut vec = vec![1, 2, 3];
    /// let mut vec2 = vec![4, 5, 6];
    /// vec.append(&mut vec2);
    /// assert_eq!(vec, [1, 2, 3, 4, 5, 6]);
    /// assert_eq!(vec2, []);
    /// ```
    #[cfg(not(no_global_oom_handling))]
    #[inline]
    #[stable(feature = "append", since = "1.4.0")]
    pub fn append(&mut self, other: &mut Self) {
        unsafe {
            self.append_elements(other.as_slice() as _);
            other.set_len(0);
        }
    }

    /// 将其他缓冲区中的元素追加到 `self` 中。
    #[cfg(not(no_global_oom_handling))]
    #[inline]
    unsafe fn append_elements(&mut self, other: *const [T]) {
        let count = unsafe { (*other).len() };
        self.reserve(count);
        let len = self.len();
        unsafe { ptr::copy_nonoverlapping(other as *const T, self.as_mut_ptr().add(len), count) };
        self.len += count;
    }

    /// 从 vector 批量删除指定范围，并以迭代器的形式返回所有移除的元素。如果迭代器在被完全消耗之前被丢弃，它会丢弃剩余的已删除元素。
    ///
    /// 返回的迭代器在 vector 上保留一个可变借用以优化其实现。
    ///
    /// # Panics
    ///
    /// 如果起点大于终点或终点大于 vector 的长度，就会出现 panics。
    ///
    /// # Leaking
    ///
    /// 如果返回的迭代器离开作用域没有被丢弃 (例如由于 [`mem::forget`])，则 vector 可能会任意丢失和泄漏元素，包括范围之外的元素。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// let mut v = vec![1, 2, 3];
    /// let u: Vec<_> = v.drain(1..).collect();
    /// assert_eq!(v, &[1]);
    /// assert_eq!(u, &[2, 3]);
    ///
    /// // 全范围清除 vector，就像 `clear()` 一样
    /// v.drain(..);
    /// assert_eq!(v, &[]);
    /// ```
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "drain", since = "1.6.0")]
    pub fn drain<R>(&mut self, range: R) -> Drain<'_, T, A>
    where
        R: RangeBounds<usize>,
    {
        // 内存安全
        //
        // 首次创建 Drain 时，它会缩短源 vector 的长度，以确保如果 Drain 的析构函数从不运行，则根本无法访问未初始化或移出的元素。
        //
        //
        // Drain 将 ptr::read 取出要删除的值。
        // 完成后，将 vec 的剩余尾部复制回以覆盖 hole，并将 vector 的长度恢复为新的长度。
        //
        //
        //
        let len = self.len();
        let Range { start, end } = slice::range(range, ..len);

        unsafe {
            // 设置 self.vec 长度开始，以防万一 Drain 泄漏
            self.set_len(start);
            let range_slice = slice::from_raw_parts(self.as_ptr().add(start), end - start);
            Drain {
                tail_start: end,
                tail_len: len - end,
                iter: range_slice.iter(),
                vec: NonNull::from(self),
            }
        }
    }

    /// 清除 vector，删除所有值。
    ///
    /// 请注意，此方法对 vector 的已分配容量没有影响。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// let mut v = vec![1, 2, 3];
    ///
    /// v.clear();
    ///
    /// assert!(v.is_empty());
    /// ```
    #[inline]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn clear(&mut self) {
        let elems: *mut [T] = self.as_mut_slice();

        // SAFETY:
        // - `elems` 直接来自 `as_mut_slice`，因此是有效的。
        // - 在调用 `drop_in_place` 之前设置 `self.len` 意味着，如果一个元素的 `Drop` impl 出现 panic，vector 的 `Drop` impl 将什么都不做 (泄漏其余元素) 而不是丢弃两次。
        //
        //
        //
        unsafe {
            self.len = 0;
            ptr::drop_in_place(elems);
        }
    }

    /// 返回 vector 中的元素数，也称为 'length'。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// let a = vec![1, 2, 3];
    /// assert_eq!(a.len(), 3);
    /// ```
    #[inline]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn len(&self) -> usize {
        self.len
    }

    /// 如果 vector 不包含任何元素，则返回 `true`。
    ///
    /// # Examples
    ///
    /// ```
    /// let mut v = Vec::new();
    /// assert!(v.is_empty());
    ///
    /// v.push(1);
    /// assert!(!v.is_empty());
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn is_empty(&self) -> bool {
        self.len() == 0
    }

    /// 在给定的索引处将集合拆分为两个。
    ///
    /// 返回一个新分配的 vector，其中包含 `[at, len)` 范围内的元素。
    /// 调用之后，将保留原始 vector，其中包含元素 `[0, at)`，而先前的容量不变。
    ///
    ///
    /// # Panics
    ///
    /// 如果为 `at > len`，就会出现 panics。
    ///
    /// # Examples
    ///
    /// ```
    /// let mut vec = vec![1, 2, 3];
    /// let vec2 = vec.split_off(1);
    /// assert_eq!(vec, [1]);
    /// assert_eq!(vec2, [2, 3]);
    /// ```
    #[cfg(not(no_global_oom_handling))]
    #[inline]
    #[must_use = "use `.truncate()` if you don't need the other half"]
    #[stable(feature = "split_off", since = "1.4.0")]
    pub fn split_off(&mut self, at: usize) -> Self
    where
        A: Clone,
    {
        #[cold]
        #[inline(never)]
        fn assert_failed(at: usize, len: usize) -> ! {
            panic!("`at` split index (is {at}) should be <= len (is {len})");
        }

        if at > self.len() {
            assert_failed(at, self.len());
        }

        if at == 0 {
            // 新的 vector 可以接管原始缓冲区并避免复制
            return mem::replace(
                self,
                Vec::with_capacity_in(self.capacity(), self.allocator().clone()),
            );
        }

        let other_len = self.len - at;
        let mut other = Vec::with_capacity_in(other_len, self.allocator().clone());

        // 不安全地 `set_len` 并将项复制到 `other`。
        unsafe {
            self.set_len(at);
            other.set_len(other_len);

            ptr::copy_nonoverlapping(self.as_ptr().add(at), other.as_mut_ptr(), other.len());
        }
        other
    }

    /// 在适当位置调整 `Vec` 的大小，以使 `len` 等于 `new_len`。
    ///
    /// 如果 `new_len` 大于 `len`，则将 `Vec` 扩展该差值，并在每个额外的插槽中填充调用闭包 `f` 的结果。
    ///
    /// `f` 的返回值将按照生成顺序返回到 `Vec`。
    ///
    /// 如果 `new_len` 小于 `len`，则将 `Vec` 截断。
    ///
    /// 此方法使用闭包在每次推送时创建新值。如果您希望给定值 [`Clone`]，请使用 [`Vec::resize`]。
    /// 如果要使用 [`Default`] trait 生成值，则可以传递 [`Default::default`] 作为第二个参数。
    ///
    /// # Examples
    ///
    /// ```
    /// let mut vec = vec![1, 2, 3];
    /// vec.resize_with(5, Default::default);
    /// assert_eq!(vec, [1, 2, 3, 0, 0]);
    ///
    /// let mut vec = vec![];
    /// let mut p = 1;
    /// vec.resize_with(4, || { p *= 2; p });
    /// assert_eq!(vec, [2, 4, 8, 16]);
    /// ```
    ///
    ///
    ///
    #[cfg(not(no_global_oom_handling))]
    #[stable(feature = "vec_resize_with", since = "1.33.0")]
    pub fn resize_with<F>(&mut self, new_len: usize, f: F)
    where
        F: FnMut() -> T,
    {
        let len = self.len();
        if new_len > len {
            self.extend_trusted(iter::repeat_with(f).take(new_len - len));
        } else {
            self.truncate(new_len);
        }
    }

    /// 消耗并泄漏 `Vec`，返回对内容的可变引用，`&'a mut [T]`。请注意，类型 `T` 必须超过所选的生命周期 `'a`。
    /// 如果类型仅具有静态引用，或者根本没有静态引用，则可以将其选择为 `'static`。
    ///
    /// 从 Rust 1.57 开始，此方法不会重新分配或收缩 `Vec`，因此泄漏的分配可能包括不属于返回切片的未使用的容量。
    ///
    ///
    /// 该函数主要用于在程序的剩余生命期内保留的数据。丢弃返回的引用将导致内存泄漏。
    ///
    /// # Examples
    ///
    /// 简单用法：
    ///
    /// ```
    /// let x = vec![1, 2, 3];
    /// let static_ref: &'static mut [usize] = x.leak();
    /// static_ref[0] += 1;
    /// assert_eq!(static_ref, &[2, 2, 3]);
    /// ```
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "vec_leak", since = "1.47.0")]
    #[inline]
    pub fn leak<'a>(self) -> &'a mut [T]
    where
        A: 'a,
    {
        let mut me = ManuallyDrop::new(self);
        unsafe { slice::from_raw_parts_mut(me.as_mut_ptr(), me.len) }
    }

    /// 以 `MaybeUninit<T>` 的切片形式返回 vector 的剩余备用容量。
    ///
    /// 返回的切片可用于用数据填充 vector (例如
    /// (通过从文件读取) 来标记数据，然后再使用 [`set_len`] 方法将其标记为已初始化。
    ///
    ///
    /// [`set_len`]: Vec::set_len
    ///
    /// # Examples
    ///
    /// ```
    /// // 分配足够大的 vector 以容纳 10 个元素。
    /// let mut v = Vec::with_capacity(10);
    ///
    /// // 填写前 3 个元素。
    /// let uninit = v.spare_capacity_mut();
    /// uninit[0].write(0);
    /// uninit[1].write(1);
    /// uninit[2].write(2);
    ///
    /// // 将 vector 的前 3 个元素标记为已初始化。
    /// unsafe {
    ///     v.set_len(3);
    /// }
    ///
    /// assert_eq!(&v, &[0, 1, 2]);
    /// ```
    ///
    #[stable(feature = "vec_spare_capacity", since = "1.60.0")]
    #[inline]
    pub fn spare_capacity_mut(&mut self) -> &mut [MaybeUninit<T>] {
        // Note:
        // 不能使用 `split_at_spare_mut` 来实现此方法，以防止指向缓冲区的指针无效。
        //
        unsafe {
            slice::from_raw_parts_mut(
                self.as_mut_ptr().add(self.len) as *mut MaybeUninit<T>,
                self.buf.capacity() - self.len,
            )
        }
    }

    /// 返回 vector 内容作为 `T` 的切片，以及 vector 的剩余备用容量作为 `MaybeUninit<T>` 的切片。
    ///
    /// 返回的备用容量切片可用于在将数据标记为使用 [`set_len`] 方法初始化的数据之前 (例如，通过从文件读取) 将数据填充到 vector 中。
    ///
    /// [`set_len`]: Vec::set_len
    ///
    /// 请注意，这是一个剧烈的 API，出于优化目的，应谨慎使用。
    /// 如果需要将数据追加到 `Vec`，则可以根据实际需要使用 [`push`]，[`extend`]，[`extend_from_slice`]，[`extend_from_within`]，[`insert`]，[`append`]，[`resize`] 或 [`resize_with`]。
    ///
    ///
    /// [`push`]: Vec::push
    /// [`extend`]: Vec::extend
    /// [`extend_from_slice`]: Vec::extend_from_slice
    /// [`extend_from_within`]: Vec::extend_from_within
    /// [`insert`]: Vec::insert
    /// [`append`]: Vec::append
    /// [`resize`]: Vec::resize
    /// [`resize_with`]: Vec::resize_with
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(vec_split_at_spare)]
    ///
    /// let mut v = vec![1, 1, 2];
    ///
    /// // 保留足够大的空间来容纳 10 个元素。
    /// v.reserve(10);
    ///
    /// let (init, uninit) = v.split_at_spare_mut();
    /// let sum = init.iter().copied().sum::<u32>();
    ///
    /// // 填写接下来的 4 个元素。
    /// uninit[0].write(sum);
    /// uninit[1].write(sum * 2);
    /// uninit[2].write(sum * 3);
    /// uninit[3].write(sum * 4);
    ///
    /// // 将 vector 的 4 个元素标记为已初始化。
    /// unsafe {
    ///     let len = v.len();
    ///     v.set_len(len + 4);
    /// }
    ///
    /// assert_eq!(&v, &[1, 1, 2, 4, 8, 12, 16]);
    /// ```
    ///
    ///
    ///
    ///
    ///
    #[unstable(feature = "vec_split_at_spare", issue = "81944")]
    #[inline]
    pub fn split_at_spare_mut(&mut self) -> (&mut [T], &mut [MaybeUninit<T>]) {
        // SAFETY:
        // - len 被忽略，因此永远不变
        let (init, spare, _) = unsafe { self.split_at_spare_mut_with_len() };
        (init, spare)
    }

    /// 安全性：更改返回的.2 (&mut usize) 与调用 `.set_len(_)` 相同。
    ///
    /// 此方法提供对 `extend_from_within` 中所有 vec 部分的唯一访问权。
    unsafe fn split_at_spare_mut_with_len(
        &mut self,
    ) -> (&mut [T], &mut [MaybeUninit<T>], &mut usize) {
        let ptr = self.as_mut_ptr();
        // SAFETY:
        // - `ptr` 保证对 `self.len` 元素有效
        // - 但分配扩展到了 `self.buf.capacity()` 元素，可能未初始化
        //
        let spare_ptr = unsafe { ptr.add(self.len) };
        let spare_ptr = spare_ptr.cast::<MaybeUninit<T>>();
        let spare_len = self.buf.capacity() - self.len;

        // SAFETY:
        // - `ptr` 保证对 `self.len` 元素有效
        // - `spare_ptr` 指向缓冲区后的一个元素，因此它不会与 `initialized` 重叠
        unsafe {
            let initialized = slice::from_raw_parts_mut(ptr, self.len);
            let spare = slice::from_raw_parts_mut(spare_ptr, spare_len);

            (initialized, spare, &mut self.len)
        }
    }
}

impl<T: Clone, A: Allocator> Vec<T, A> {
    /// 在适当位置调整 `Vec` 的大小，以使 `len` 等于 `new_len`。
    ///
    /// 如果 `new_len` 大于 `len`，则 `Vec` 会扩展此差值，每个额外的插槽都将用 `value` 填充。
    ///
    /// 如果 `new_len` 小于 `len`，则将 `Vec` 截断。
    ///
    /// 为了能够克隆传递的值，此方法需要 `T` 实现 [`Clone`]。
    /// 如果需要更大的灵活性 (或希望依靠 [`Default`] 而不是 [`Clone`])，请使用 [`Vec::resize_with`]。
    /// 如果您只需要调整到更小的尺寸，请使用 [`Vec::truncate`]。
    ///
    /// # Examples
    ///
    /// ```
    /// let mut vec = vec!["hello"];
    /// vec.resize(3, "world");
    /// assert_eq!(vec, ["hello", "world", "world"]);
    ///
    /// let mut vec = vec![1, 2, 3, 4];
    /// vec.resize(2, 0);
    /// assert_eq!(vec, [1, 2]);
    /// ```
    ///
    ///
    #[cfg(not(no_global_oom_handling))]
    #[stable(feature = "vec_resize", since = "1.5.0")]
    pub fn resize(&mut self, new_len: usize, value: T) {
        let len = self.len();

        if new_len > len {
            self.extend_with(new_len - len, ExtendElement(value))
        } else {
            self.truncate(new_len);
        }
    }

    /// 克隆并将切片中的所有元素追加到 `Vec`。
    ///
    /// 遍历切片 `other`，克隆每个元素，然后将其追加到此 `Vec`。
    /// `other` 切片是按顺序遍历的。
    ///
    /// 请注意，此函数与 [`extend`] 相同，只不过它专门用于切片。
    ///
    /// 如果并且当 Rust 得到专门化时，此函数可能会被弃用 (但仍然可用)。
    ///
    /// # Examples
    ///
    /// ```
    /// let mut vec = vec![1];
    /// vec.extend_from_slice(&[2, 3, 4]);
    /// assert_eq!(vec, [1, 2, 3, 4]);
    /// ```
    ///
    /// [`extend`]: Vec::extend
    ///
    #[cfg(not(no_global_oom_handling))]
    #[stable(feature = "vec_extend_from_slice", since = "1.6.0")]
    pub fn extend_from_slice(&mut self, other: &[T]) {
        self.spec_extend(other.iter())
    }

    /// 将元素从 `src` 复制到 vector 的末尾。
    ///
    /// # Panics
    ///
    /// 如果起点大于终点或终点大于 vector 的长度，就会出现 panics。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// let mut vec = vec![0, 1, 2, 3, 4];
    ///
    /// vec.extend_from_within(2..);
    /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4]);
    ///
    /// vec.extend_from_within(..2);
    /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1]);
    ///
    /// vec.extend_from_within(4..8);
    /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1, 4, 2, 3, 4]);
    /// ```
    #[cfg(not(no_global_oom_handling))]
    #[stable(feature = "vec_extend_from_within", since = "1.53.0")]
    pub fn extend_from_within<R>(&mut self, src: R)
    where
        R: RangeBounds<usize>,
    {
        let range = slice::range(src, ..self.len());
        self.reserve(range.len());

        // SAFETY:
        // - `slice::range` 保证给定范围对索引自身有效
        unsafe {
            self.spec_extend_from_within(range);
        }
    }
}

impl<T, A: Allocator, const N: usize> Vec<[T; N], A> {
    /// 取 `Vec<[T; N]>` 并将其展平为 `Vec<T>`。
    ///
    /// # Panics
    ///
    /// 如果生成的 vector 的长度会溢出 `usize`，则会出现 panic。
    ///
    /// 这仅在展平零大小类型数组的 vector 时才有可能，因此在实践中往往无关紧要。
    /// 如果是 `size_of::<T>() > 0`，这将永远不会 panic。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(slice_flatten)]
    ///
    /// let mut vec = vec![[1, 2, 3], [4, 5, 6], [7, 8, 9]];
    /// assert_eq!(vec.pop(), Some([7, 8, 9]));
    ///
    /// let mut flattened = vec.into_flattened();
    /// assert_eq!(flattened.pop(), Some(6));
    /// ```
    ///
    #[unstable(feature = "slice_flatten", issue = "95629")]
    pub fn into_flattened(self) -> Vec<T, A> {
        let (ptr, len, cap, alloc) = self.into_raw_parts_with_alloc();
        let (new_len, new_cap) = if T::IS_ZST {
            (len.checked_mul(N).expect("vec len overflow"), usize::MAX)
        } else {
            // SAFETY:
            // - `cap * N` 不能溢出，因为分配已经在地址空间中。
            // - 每个 `[T; N]` 都有 `N` 个有效元素，因此分配中有 `len * N` 个有效元素。
            //
            //
            unsafe { (len.unchecked_mul(N), cap.unchecked_mul(N)) }
        };
        // SAFETY:
        // - `ptr` 由 `self` 分配
        // - `ptr` 对齐良好，因为 `[T; N]` 与 `T` 具有相同的对齐方式。
        // - `new_cap` 指的是与 `cap` 相同大小的分配，因为 `new_cap * size_of::<T>()` == `cap * size_of::<[T; N]>()`
        //
        // - `len` <= `cap`，所以 `len * N` <= `cap * N`。
        unsafe { Vec::<T, A>::from_raw_parts_in(ptr.cast(), new_len, new_cap, alloc) }
    }
}

// 这段代码概括了 `extend_with_{element,default}`。
trait ExtendWith<T> {
    fn next(&mut self) -> T;
    fn last(self) -> T;
}

struct ExtendElement<T>(T);
impl<T: Clone> ExtendWith<T> for ExtendElement<T> {
    fn next(&mut self) -> T {
        self.0.clone()
    }
    fn last(self) -> T {
        self.0
    }
}

impl<T, A: Allocator> Vec<T, A> {
    #[cfg(not(no_global_oom_handling))]
    /// 使用给定的生成器将 vector 扩展 `n` 值。
    fn extend_with<E: ExtendWith<T>>(&mut self, n: usize, mut value: E) {
        self.reserve(n);

        unsafe {
            let mut ptr = self.as_mut_ptr().add(self.len());
            // 使用 SetLenOnDrop 来解决编译器可能无法通过 `ptr` 到 self.set_len() 不使用别名实现存储的错误。
            //
            //
            let mut local_len = SetLenOnDrop::new(&mut self.len);

            // 写下除最后一个元素外的所有元素
            for _ in 1..n {
                ptr::write(ptr, value.next());
                ptr = ptr.add(1);
                // 在 next() panics 的情况下，增加每一步的长度
                local_len.increment_len(1);
            }

            if n > 0 {
                // 我们可以直接编写最后一个元素，而无需不必要地克隆
                ptr::write(ptr, value.last());
                local_len.increment_len(1);
            }

            // len 由作用域守卫设置
        }
    }
}

impl<T: PartialEq, A: Allocator> Vec<T, A> {
    /// 根据 [`PartialEq`] trait 的实现，删除 vector 中连续的重复元素。
    ///
    ///
    /// 如果对 vector 进行了排序，则将删除所有重复项。
    ///
    /// # Examples
    ///
    /// ```
    /// let mut vec = vec![1, 2, 2, 3, 2];
    ///
    /// vec.dedup();
    ///
    /// assert_eq!(vec, [1, 2, 3, 2]);
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn dedup(&mut self) {
        self.dedup_by(|a, b| a == b)
    }
}

////////////////////////////////////////////////////////////////////////////////
// 内部方法和函数
////////////////////////////////////////////////////////////////////////////////

#[doc(hidden)]
#[cfg(not(no_global_oom_handling))]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn from_elem<T: Clone>(elem: T, n: usize) -> Vec<T> {
    <T as SpecFromElem>::from_elem(elem, n, Global)
}

#[doc(hidden)]
#[cfg(not(no_global_oom_handling))]
#[unstable(feature = "allocator_api", issue = "32838")]
pub fn from_elem_in<T: Clone, A: Allocator>(elem: T, n: usize, alloc: A) -> Vec<T, A> {
    <T as SpecFromElem>::from_elem(elem, n, alloc)
}

trait ExtendFromWithinSpec {
    /// # Safety
    ///
    /// - `src` 必须是有效的索引
    /// - `self.capacity() - self.len()` 必须是 `>= src.len()`
    unsafe fn spec_extend_from_within(&mut self, src: Range<usize>);
}

impl<T: Clone, A: Allocator> ExtendFromWithinSpec for Vec<T, A> {
    default unsafe fn spec_extend_from_within(&mut self, src: Range<usize>) {
        // SAFETY:
        // - len 仅在初始化元素后才增加
        let (this, spare, len) = unsafe { self.split_at_spare_mut_with_len() };

        // SAFETY:
        // - 调用者保证 src 是一个有效的索引
        let to_clone = unsafe { this.get_unchecked(src) };

        iter::zip(to_clone, spare)
            .map(|(src, dst)| dst.write(src.clone()))
            // Note:
            // - Element 刚刚用 `MaybeUninit::write` 初始化，所以可以增加 len
            // - 在每个元素之后增加 len 以防止泄漏 (请参见 issue #82533)
            .for_each(|_| *len += 1);
    }
}

impl<T: Copy, A: Allocator> ExtendFromWithinSpec for Vec<T, A> {
    unsafe fn spec_extend_from_within(&mut self, src: Range<usize>) {
        let count = src.len();
        {
            let (init, spare) = self.split_at_spare_mut();

            // SAFETY:
            // - 调用者保证 `src` 是一个有效的索引
            let source = unsafe { init.get_unchecked(src) };

            // SAFETY:
            // - 这两个指针都是从唯一的 (`&mut [_]`) 创建的，因此它们是有效的并且不会重叠。
            //
            // - 元素是 :Copy 所以可以复制它们，而不用对原始值做任何事情
            // - `count` 等于 `source` 的 len，因此来源对 `count` 读取有效
            // - `.reserve(count)` 保证 `spare.len() >= count` 所以备用对 `count` 写有效
            //
            //
            //
            unsafe { ptr::copy_nonoverlapping(source.as_ptr(), spare.as_mut_ptr() as _, count) };
        }

        // SAFETY:
        // - 元素刚刚由 `copy_nonoverlapping` 初始化
        self.len += count;
    }
}

////////////////////////////////////////////////////////////////////////////////
// Vec 的常见 trait 实现
////////////////////////////////////////////////////////////////////////////////

#[stable(feature = "rust1", since = "1.0.0")]
impl<T, A: Allocator> ops::Deref for Vec<T, A> {
    type Target = [T];

    #[inline]
    fn deref(&self) -> &[T] {
        unsafe { slice::from_raw_parts(self.as_ptr(), self.len) }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T, A: Allocator> ops::DerefMut for Vec<T, A> {
    #[inline]
    fn deref_mut(&mut self) -> &mut [T] {
        unsafe { slice::from_raw_parts_mut(self.as_mut_ptr(), self.len) }
    }
}

#[cfg(not(no_global_oom_handling))]
#[stable(feature = "rust1", since = "1.0.0")]
impl<T: Clone, A: Allocator + Clone> Clone for Vec<T, A> {
    #[cfg(not(test))]
    fn clone(&self) -> Self {
        let alloc = self.allocator().clone();
        <[T]>::to_vec_in(&**self, alloc)
    }

    // HACK(japaric): 对于 cfg(test)，此方法定义所需的固有 `[T]::to_vec` 方法不可用。
    // 而是使用仅适用于 cfg(test) 的 `slice::to_vec` 函数
    // NB 有关更多信息，请参见 slice.rs 中的 slice::hack 模块
    //
    #[cfg(test)]
    fn clone(&self) -> Self {
        let alloc = self.allocator().clone();
        crate::slice::to_vec(&**self, alloc)
    }

    fn clone_from(&mut self, other: &Self) {
        crate::slice::SpecCloneIntoVec::clone_into(other.as_slice(), self);
    }
}

/// 根据 `core::borrow::Borrow` 实现的要求，vector 的哈希值与相应的 3 的哈希值相同。
///
///
/// ```
/// use std::hash::BuildHasher;
///
/// let b = std::collections::hash_map::RandomState::new();
/// let v: Vec<u8> = vec![0xa8, 0x3c, 0x09];
/// let s: &[u8] = &[0xa8, 0x3c, 0x09];
/// assert_eq!(b.hash_one(v), b.hash_one(s));
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
impl<T: Hash, A: Allocator> Hash for Vec<T, A> {
    #[inline]
    fn hash<H: Hasher>(&self, state: &mut H) {
        Hash::hash(&**self, state)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_on_unimplemented(
    message = "vector indices are of type `usize` or ranges of `usize`",
    label = "vector indices are of type `usize` or ranges of `usize`"
)]
impl<T, I: SliceIndex<[T]>, A: Allocator> Index<I> for Vec<T, A> {
    type Output = I::Output;

    #[inline]
    fn index(&self, index: I) -> &Self::Output {
        Index::index(&**self, index)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_on_unimplemented(
    message = "vector indices are of type `usize` or ranges of `usize`",
    label = "vector indices are of type `usize` or ranges of `usize`"
)]
impl<T, I: SliceIndex<[T]>, A: Allocator> IndexMut<I> for Vec<T, A> {
    #[inline]
    fn index_mut(&mut self, index: I) -> &mut Self::Output {
        IndexMut::index_mut(&mut **self, index)
    }
}

#[cfg(not(no_global_oom_handling))]
#[stable(feature = "rust1", since = "1.0.0")]
impl<T> FromIterator<T> for Vec<T> {
    #[inline]
    fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Vec<T> {
        <Self as SpecFromIter<T, I::IntoIter>>::from_iter(iter.into_iter())
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T, A: Allocator> IntoIterator for Vec<T, A> {
    type Item = T;
    type IntoIter = IntoIter<T, A>;

    /// 创建一个消耗迭代器，即一个将每个值移出 vector (从开始到结束) 的迭代器。
    /// 调用此后不能使用 vector。
    ///
    /// # Examples
    ///
    /// ```
    /// let v = vec!["a".to_string(), "b".to_string()];
    /// let mut v_iter = v.into_iter();
    ///
    /// let first_element: Option<String> = v_iter.next();
    ///
    /// assert_eq!(first_element, Some("a".to_string()));
    /// assert_eq!(v_iter.next(), Some("b".to_string()));
    /// assert_eq!(v_iter.next(), None);
    /// ```
    ///
    #[inline]
    fn into_iter(self) -> Self::IntoIter {
        unsafe {
            let mut me = ManuallyDrop::new(self);
            let alloc = ManuallyDrop::new(ptr::read(me.allocator()));
            let begin = me.as_mut_ptr();
            let end = if T::IS_ZST {
                begin.wrapping_byte_add(me.len())
            } else {
                begin.add(me.len()) as *const T
            };
            let cap = me.buf.capacity();
            IntoIter {
                buf: NonNull::new_unchecked(begin),
                phantom: PhantomData,
                cap,
                alloc,
                ptr: begin,
                end,
            }
        }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<'a, T, A: Allocator> IntoIterator for &'a Vec<T, A> {
    type Item = &'a T;
    type IntoIter = slice::Iter<'a, T>;

    fn into_iter(self) -> Self::IntoIter {
        self.iter()
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<'a, T, A: Allocator> IntoIterator for &'a mut Vec<T, A> {
    type Item = &'a mut T;
    type IntoIter = slice::IterMut<'a, T>;

    fn into_iter(self) -> Self::IntoIter {
        self.iter_mut()
    }
}

#[cfg(not(no_global_oom_handling))]
#[stable(feature = "rust1", since = "1.0.0")]
impl<T, A: Allocator> Extend<T> for Vec<T, A> {
    #[inline]
    fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I) {
        <Self as SpecExtend<T, I::IntoIter>>::spec_extend(self, iter.into_iter())
    }

    #[inline]
    fn extend_one(&mut self, item: T) {
        self.push(item);
    }

    #[inline]
    fn extend_reserve(&mut self, additional: usize) {
        self.reserve(additional);
    }
}

impl<T, A: Allocator> Vec<T, A> {
    // 各种 SpecFrom/SpecExtend 实现在没有进一步优化要应用时将委派给它们的叶子方法
    //
    #[cfg(not(no_global_oom_handling))]
    fn extend_desugared<I: Iterator<Item = T>>(&mut self, mut iterator: I) {
        // 通用迭代器就是这种情况。
        //
        // 这个功能应该是 moral 上的等价物：
        //
        //      对于迭代器中的项 {
        //          self.push(item);
        //      }
        while let Some(element) = iterator.next() {
            let len = self.len();
            if len == self.capacity() {
                let (lower, _) = iterator.size_hint();
                self.reserve(lower.saturating_add(1));
            }
            unsafe {
                ptr::write(self.as_mut_ptr().add(len), element);
                // 由于 next() 执行可以 panic 的用户代码，我们必须在每一步之后增加长度。
                //
                // NB 不会溢出，因为我们不得不分配地址空间
                self.set_len(len + 1);
            }
        }
    }

    // `TrustedLen` 迭代器的特定扩展，由专业化和解析专业化使编译变慢的内部位置调用
    //
    #[cfg(not(no_global_oom_handling))]
    fn extend_trusted(&mut self, iterator: impl iter::TrustedLen<Item = T>) {
        let (low, high) = iterator.size_hint();
        if let Some(additional) = high {
            debug_assert_eq!(
                low,
                additional,
                "TrustedLen iterator's size hint is not exact: {:?}",
                (low, high)
            );
            self.reserve(additional);
            unsafe {
                let ptr = self.as_mut_ptr();
                let mut local_len = SetLenOnDrop::new(&mut self.len);
                iterator.for_each(move |element| {
                    ptr::write(ptr.add(local_len.current_len()), element);
                    // 由于循环执行的用户代码可能会导致 panic，因此我们必须更新每一步的长度以正确扔弃我们编写的内容。
                    //
                    // NB 不会溢出，因为我们不得不分配地址空间
                    local_len.increment_len(1);
                });
            }
        } else {
            // 每个 TrustedLen 契约的 `None` 上限意味着迭代器长度确实超过 usize::MAX，无论如何最终都会导致容量溢出。
            //
            // 由于另一个分支已经 panics 急切地 (通过 `reserve()`) 我们在这里做同样的事情。
            // 这避免了额外的 codegen 用于回退代码路径，最终 panic 无论如何。
            //
            panic!("capacity overflow");
        }
    }

    /// 创建一个拼接迭代器，用给定的 `replace_with` 迭代器替换 vector 中的指定范围，并生成已删除的项。
    ///
    /// `replace_with` 不需要与 `range` 的长度相同。
    ///
    /// 即使直到最后才消耗迭代器，`range` 也会被删除。
    ///
    /// 如果 `Splice` 值泄漏，则未指定从 vector 中删除了多少个元素。
    ///
    /// 输入迭代器 `replace_with` 只有在 `Splice` 值被丢弃时才会被消耗。
    ///
    /// 如果满足以下条件，则为最佳选择：
    ///
    /// * 尾部 (`range` 之后的 vector 中的元素) 为空，
    /// * 或 `replace_with` 产生的元素少于或等于 'range' 的长度
    /// * 或其 `size_hint()` 的下界是正确的。
    ///
    /// 否则，将分配一个临时的 vector 并将尾部移动两次。
    ///
    /// # Panics
    ///
    /// 如果起点大于终点或终点大于 vector 的长度，就会出现 panics。
    ///
    /// # Examples
    ///
    /// ```
    /// let mut v = vec![1, 2, 3, 4];
    /// let new = [7, 8, 9];
    /// let u: Vec<_> = v.splice(1..3, new).collect();
    /// assert_eq!(v, &[1, 7, 8, 9, 4]);
    /// assert_eq!(u, &[2, 3]);
    /// ```
    ///
    ///
    #[cfg(not(no_global_oom_handling))]
    #[inline]
    #[stable(feature = "vec_splice", since = "1.21.0")]
    pub fn splice<R, I>(&mut self, range: R, replace_with: I) -> Splice<'_, I::IntoIter, A>
    where
        R: RangeBounds<usize>,
        I: IntoIterator<Item = T>,
    {
        Splice { drain: self.drain(range), replace_with: replace_with.into_iter() }
    }

    /// 创建一个迭代器，该迭代器使用闭包确定是否应删除元素。
    ///
    /// 如果闭包返回 true，则删除并生成元素。
    /// 如果闭包返回 false，则该元素将保留在 vector 中，并且不会由迭代器产生。
    ///
    /// 使用此方法等效于以下代码：
    ///
    /// ```
    /// # let some_predicate = |x: &mut i32| { *x == 2 || *x == 3 || *x == 6 };
    /// # let mut vec = vec![1, 2, 3, 4, 5, 6];
    /// let mut i = 0;
    /// while i < vec.len() {
    ///     if some_predicate(&mut vec[i]) {
    ///         let val = vec.remove(i);
    ///         // 您的代码在这里
    ///     } else {
    ///         i += 1;
    ///     }
    /// }
    ///
    /// # assert_eq!(vec, vec![1, 4, 5]);
    /// ```
    ///
    /// 但是 `drain_filter` 更易于使用。
    /// `drain_filter` 也更高效，因为它可以批量回移数组的元素。
    ///
    /// 请注意，`drain_filter` 还允许您改变过滤器闭包中的每个元素，无论您选择保留还是删除它。
    ///
    ///
    /// # Examples
    ///
    /// 将数组拆分为偶数和几率，重新使用原始分配：
    ///
    /// ```
    /// #![feature(drain_filter)]
    /// let mut numbers = vec![1, 2, 3, 4, 5, 6, 8, 9, 11, 13, 14, 15];
    ///
    /// let evens = numbers.drain_filter(|x| *x % 2 == 0).collect::<Vec<_>>();
    /// let odds = numbers;
    ///
    /// assert_eq!(evens, vec![2, 4, 6, 8, 14]);
    /// assert_eq!(odds, vec![1, 3, 5, 9, 11, 13, 15]);
    /// ```
    ///
    #[unstable(feature = "drain_filter", reason = "recently added", issue = "43244")]
    pub fn drain_filter<F>(&mut self, filter: F) -> DrainFilter<'_, T, F, A>
    where
        F: FnMut(&mut T) -> bool,
    {
        let old_len = self.len();

        // 防止我们泄漏 (泄漏放大)
        unsafe {
            self.set_len(0);
        }

        DrainFilter { vec: self, idx: 0, del: 0, old_len, pred: filter, panic_flag: false }
    }
}

/// 扩展将引用中的元素复制到 Vec 之前的实现。
///
/// 此实现专用于切片迭代器，它使用 [`copy_from_slice`] 一次追加整个切片。
///
///
/// [`copy_from_slice`]: slice::copy_from_slice
#[cfg(not(no_global_oom_handling))]
#[stable(feature = "extend_ref", since = "1.2.0")]
impl<'a, T: Copy + 'a, A: Allocator + 'a> Extend<&'a T> for Vec<T, A> {
    fn extend<I: IntoIterator<Item = &'a T>>(&mut self, iter: I) {
        self.spec_extend(iter.into_iter())
    }

    #[inline]
    fn extend_one(&mut self, &item: &'a T) {
        self.push(item);
    }

    #[inline]
    fn extend_reserve(&mut self, additional: usize) {
        self.reserve(additional);
    }
}

/// 实现 vectors、[lexicographically](Ord#lexicographical-comparison) 的比较。
#[stable(feature = "rust1", since = "1.0.0")]
impl<T: PartialOrd, A: Allocator> PartialOrd for Vec<T, A> {
    #[inline]
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        PartialOrd::partial_cmp(&**self, &**other)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: Eq, A: Allocator> Eq for Vec<T, A> {}

/// 实现 vectors、[lexicographically](Ord#lexicographical-comparison) 的排序。
#[stable(feature = "rust1", since = "1.0.0")]
impl<T: Ord, A: Allocator> Ord for Vec<T, A> {
    #[inline]
    fn cmp(&self, other: &Self) -> Ordering {
        Ord::cmp(&**self, &**other)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
unsafe impl<#[may_dangle] T, A: Allocator> Drop for Vec<T, A> {
    fn drop(&mut self) {
        unsafe {
            // 对 [T] 使用 drop，使用原始切片将 vector 的元素称为最弱必要类型；
            //
            // 在某些情况下可以避免有效性问题
            ptr::drop_in_place(ptr::slice_from_raw_parts_mut(self.as_mut_ptr(), self.len))
        }
        // RawVec 处理重新分配
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T> Default for Vec<T> {
    /// 创建一个空的 `Vec<T>`。
    ///
    /// 直到将元素压入 vector 为止，vector 才会分配。
    fn default() -> Vec<T> {
        Vec::new()
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: fmt::Debug, A: Allocator> fmt::Debug for Vec<T, A> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Debug::fmt(&**self, f)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T, A: Allocator> AsRef<Vec<T, A>> for Vec<T, A> {
    fn as_ref(&self) -> &Vec<T, A> {
        self
    }
}

#[stable(feature = "vec_as_mut", since = "1.5.0")]
impl<T, A: Allocator> AsMut<Vec<T, A>> for Vec<T, A> {
    fn as_mut(&mut self) -> &mut Vec<T, A> {
        self
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<T, A: Allocator> AsRef<[T]> for Vec<T, A> {
    fn as_ref(&self) -> &[T] {
        self
    }
}

#[stable(feature = "vec_as_mut", since = "1.5.0")]
impl<T, A: Allocator> AsMut<[T]> for Vec<T, A> {
    fn as_mut(&mut self) -> &mut [T] {
        self
    }
}

#[cfg(not(no_global_oom_handling))]
#[stable(feature = "rust1", since = "1.0.0")]
impl<T: Clone> From<&[T]> for Vec<T> {
    /// 分配一个 `Vec<T>` 并通过克隆 `s` 的项来填充它。
    ///
    /// # Examples
    ///
    /// ```
    /// assert_eq!(Vec::from(&[1, 2, 3][..]), vec![1, 2, 3]);
    /// ```
    #[cfg(not(test))]
    fn from(s: &[T]) -> Vec<T> {
        s.to_vec()
    }
    #[cfg(test)]
    fn from(s: &[T]) -> Vec<T> {
        crate::slice::to_vec(s, Global)
    }
}

#[cfg(not(no_global_oom_handling))]
#[stable(feature = "vec_from_mut", since = "1.19.0")]
impl<T: Clone> From<&mut [T]> for Vec<T> {
    /// 分配一个 `Vec<T>` 并通过克隆 `s` 的项来填充它。
    ///
    /// # Examples
    ///
    /// ```
    /// assert_eq!(Vec::from(&mut [1, 2, 3][..]), vec![1, 2, 3]);
    /// ```
    #[cfg(not(test))]
    fn from(s: &mut [T]) -> Vec<T> {
        s.to_vec()
    }
    #[cfg(test)]
    fn from(s: &mut [T]) -> Vec<T> {
        crate::slice::to_vec(s, Global)
    }
}

#[cfg(not(no_global_oom_handling))]
#[stable(feature = "vec_from_array", since = "1.44.0")]
impl<T, const N: usize> From<[T; N]> for Vec<T> {
    /// 分配一个 `Vec<T>` 并将 `s` 的项移到其中。
    ///
    /// # Examples
    ///
    /// ```
    /// assert_eq!(Vec::from([1, 2, 3]), vec![1, 2, 3]);
    /// ```
    #[cfg(not(test))]
    fn from(s: [T; N]) -> Vec<T> {
        <[T]>::into_vec(Box::new(s))
    }

    #[cfg(test)]
    fn from(s: [T; N]) -> Vec<T> {
        crate::slice::into_vec(Box::new(s))
    }
}

#[stable(feature = "vec_from_cow_slice", since = "1.14.0")]
impl<'a, T> From<Cow<'a, [T]>> for Vec<T>
where
    [T]: ToOwned<Owned = Vec<T>>,
{
    /// 将写时克隆切片转换为 vector。
    ///
    /// 如果 `s` 已经拥有 `Vec<T>`，则直接返回。
    /// 如果 `s` 是借用了一个切片，将通过克隆 `s` 的项来分配和填充一个新的 `Vec`。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// # use std::borrow::Cow;
    /// let o: Cow<'_, [i32]> = Cow::Owned(vec![1, 2, 3]);
    /// let b: Cow<'_, [i32]> = Cow::Borrowed(&[1, 2, 3]);
    /// assert_eq!(Vec::from(o), Vec::from(b));
    /// ```
    fn from(s: Cow<'a, [T]>) -> Vec<T> {
        s.into_owned()
    }
}

// note: test 拉入 std，导致此处出错
#[cfg(not(test))]
#[stable(feature = "vec_from_box", since = "1.18.0")]
impl<T, A: Allocator> From<Box<[T], A>> for Vec<T, A> {
    /// 通过转移现有堆分配的所有权，将 boxed 切片转换为 vector。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// let b: Box<[i32]> = vec![1, 2, 3].into_boxed_slice();
    /// assert_eq!(Vec::from(b), vec![1, 2, 3]);
    /// ```
    fn from(s: Box<[T], A>) -> Self {
        s.into_vec()
    }
}

// note: test 拉入 std，导致此处出错
#[cfg(not(no_global_oom_handling))]
#[cfg(not(test))]
#[stable(feature = "box_from_vec", since = "1.20.0")]
impl<T, A: Allocator> From<Vec<T, A>> for Box<[T], A> {
    /// 将 vector 转换为 boxed。
    ///
    /// 如果 `v` 有多余的容量，它的项将被移动到新分配的缓冲区中，缓冲区的容量恰好是正确的。
    ///
    /// # Examples
    ///
    /// ```
    /// assert_eq!(Box::from(vec![1, 2, 3]), vec![1, 2, 3].into_boxed_slice());
    /// ```
    ///
    /// 任何多余的容量都将被删除：
    ///
    /// ```
    /// let mut vec = Vec::with_capacity(10);
    /// vec.extend([1, 2, 3]);
    ///
    /// assert_eq!(Box::from(vec), vec![1, 2, 3].into_boxed_slice());
    /// ```
    fn from(v: Vec<T, A>) -> Self {
        v.into_boxed_slice()
    }
}

#[cfg(not(no_global_oom_handling))]
#[stable(feature = "rust1", since = "1.0.0")]
impl From<&str> for Vec<u8> {
    /// 分配一个 `Vec<u8>` 并用 UTF-8 字符串填充它。
    ///
    /// # Examples
    ///
    /// ```
    /// assert_eq!(Vec::from("123"), vec![b'1', b'2', b'3']);
    /// ```
    fn from(s: &str) -> Vec<u8> {
        From::from(s.as_bytes())
    }
}

#[stable(feature = "array_try_from_vec", since = "1.48.0")]
impl<T, A: Allocator, const N: usize> TryFrom<Vec<T, A>> for [T; N] {
    type Error = Vec<T, A>;

    /// 如果 `Vec<T>` 的大小与请求的数组的大小完全匹配，则以数组的形式获取 `Vec<T>` 的全部内容。
    ///
    /// # Examples
    ///
    /// ```
    /// assert_eq!(vec![1, 2, 3].try_into(), Ok([1, 2, 3]));
    /// assert_eq!(<Vec<i32>>::new().try_into(), Ok([]));
    /// ```
    ///
    /// 如果长度不匹配，则输入以 `Err` 返回：
    ///
    /// ```
    /// let r: Result<[i32; 4], _> = (0..10).collect::<Vec<_>>().try_into();
    /// assert_eq!(r, Err(vec![0, 1, 2, 3, 4, 5, 6, 7, 8, 9]));
    /// ```
    ///
    /// 如果只需要获得 `Vec<T>` 的前缀就可以了，您可以先调用 [`.truncate(N)`](Vec::truncate)。
    ///
    /// ```
    /// let mut v = String::from("hello world").into_bytes();
    /// v.sort();
    /// v.truncate(2);
    /// let [a, b]: [_; 2] = v.try_into().unwrap();
    /// assert_eq!(a, b' ');
    /// assert_eq!(b, b'd');
    /// ```
    fn try_from(mut vec: Vec<T, A>) -> Result<[T; N], Vec<T, A>> {
        if vec.len() != N {
            return Err(vec);
        }

        // SAFETY: `.set_len(0)` 始终是声音。
        unsafe { vec.set_len(0) };

        // SAFETY: `Vec` 的指针始终正确对齐，并且数组所需的对齐与项相同。
        //
        // 我们之前检查过我们有足够的物品。
        // 由于 `set_len` 告诉 `Vec` 也不要丢弃它们，因此该项不会被双重丢弃。
        //
        let array = unsafe { ptr::read(vec.as_ptr() as *const [T; N]) };
        Ok(array)
    }
}