use crate::vec::Vec;
use core::borrow::Borrow;
use core::cmp::Ordering;
use core::fmt::{self, Debug};
use core::hash::{Hash, Hasher};
use core::iter::FusedIterator;
use core::marker::PhantomData;
use core::mem::{self, ManuallyDrop};
use core::ops::{Bound, Index, RangeBounds};
use core::ptr;

use crate::alloc::{Allocator, Global};

use super::borrow::DormantMutRef;
use super::dedup_sorted_iter::DedupSortedIter;
use super::navigate::{LazyLeafRange, LeafRange};
use super::node::{self, marker, ForceResult::*, Handle, NodeRef, Root};
use super::search::{SearchBound, SearchResult::*};
use super::set_val::SetValZST;

mod entry;

#[stable(feature = "rust1", since = "1.0.0")]
pub use entry::{Entry, OccupiedEntry, OccupiedError, VacantEntry};

use Entry::*;

/// 非根节点中的最小元素数。
/// 在方法期间，我们可能会暂时减少元素数量。
pub(super) const MIN_LEN: usize = node::MIN_LEN_AFTER_SPLIT;

// `BTreeMap` 中的树是 `node` 模块中具有其他不变量的树：
// - 键必须按升序显示 (根据键的类型)。
// - 每个非叶子节点至少包含 1 个元素 (至少有 2 个子节点)。
// - 每个非根节点至少包含 MIN_LEN 个元素。
//
// 空的 map 表示不存在根节点或根节点为空叶子。
//

/// 基于 [B-Tree] 的有序 map。
///
/// B 树表示缓存效率与实际最小化搜索中执行的工作量之间的根本折衷。从理论上讲，二元搜索树 (BST) 是排序的 map 的最佳选择，因为完全平衡的 BST 执行查找元素 (log<sub>2</sub>n) 所需的理论上最小的比较量。
/// 但是，实际上，完成此操作的方式对于现代计算机体系结构而言效率非常低。
/// 特别是，每个元素都存储在其自己的单独堆分配节点中。
/// 这意味着每个插入都会触发堆分配，并且每个比较都应该是缓存未命中。
/// 由于这些在实践中都是非常昂贵的事情，我们至少不得不重新考虑 BST 策略。
///
/// 相反，B 树使每个节点在连续数组中包含 B-1 到 2B-1 元素。通过这样做，我们将分配数量减少了 B 倍，并提高了搜索中的缓存效率。但是，这确实意味着平均而言，搜索将不得不进行更多的比较。
/// 比较的精确数量取决于所使用的节点搜索策略。为了获得最佳的缓存效率，可以线性搜索节点。为了进行最佳比较，可以使用二进制搜索来搜索节点。作为一种折衷方案，我们还可以执行线性搜索，最初只检查每个 i<sup>th</sup> 元素的某个选择 i.
///
/// 当前，我们的实现仅执行简单的线性搜索。这在比较便宜的元素的小节点上提供了出色的性能。但是，未来我们将进一步探索基于 B 的选择以及可能的其他因素来选择最佳搜索策略。使用线性搜索，搜索随机元素预计会进行 B * log(n) 次比较，这通常比 BST 差。
///
/// 但是，实际上，性能非常好。
///
/// 以某种方式修改键是一种逻辑错误，即，当键在 map 中时，由 [`Ord`] trait 决定的键相对于任何其他键的顺序都会改变。通常只有通过 [`Cell`]，[`RefCell`]，二进制状态，I/O 或不安全代码才能实现此操作。
/// 此类逻辑错误导致的行为未指定，但会封装到观察到逻辑错误的 `BTreeMap` 中，并且不会导致未定义的行为。这可能包括 panics、不正确的结果、中止、内存泄漏和未中止。
///
/// 从函数获得的迭代器 (例如 [`BTreeMap::iter`]、[`BTreeMap::values`] 或 [`BTreeMap::keys`]) 按键顺序生成它们的项，并且每个返回的项采用最坏情况对数和摊销特性时间。
///
/// [B-Tree]: https://en.wikipedia.org/wiki/B-tree
/// [`Cell`]: core::cell::Cell
/// [`RefCell`]: core::cell::RefCell
///
/// # Examples
///
/// ```
/// use std::collections::BTreeMap;
///
/// // 通过类型推断，我们可以省略显式类型签名 (在本示例中为 `BTreeMap<&str, &str>`)。
/////
/// let mut movie_reviews = BTreeMap::new();
///
/// // 回顾一些电影。
/// movie_reviews.insert("Office Space",       "Deals with real issues in the workplace.");
/// movie_reviews.insert("Pulp Fiction",       "Masterpiece.");
/// movie_reviews.insert("The Godfather",      "Very enjoyable.");
/// movie_reviews.insert("The Blues Brothers", "Eye lyked it a lot.");
///
/// // 检查一个特定的。
/// if !movie_reviews.contains_key("Les Misérables") {
///     println!("We've got {} reviews, but Les Misérables ain't one.",
///              movie_reviews.len());
/// }
///
/// // 糟糕，此评论有很多拼写错误，让我们删除它。
/// movie_reviews.remove("The Blues Brothers");
///
/// // 查找与某些键关联的值。
/// let to_find = ["Up!", "Office Space"];
/// for movie in &to_find {
///     match movie_reviews.get(movie) {
///        Some(review) => println!("{movie}: {review}"),
///        None => println!("{movie} is unreviewed.")
///     }
/// }
///
/// // 查找某个键的值 (如果找不到该键，就会出现 panic)。
/// println!("Movie review: {}", movie_reviews["Office Space"]);
///
/// // 迭代所有内容。
/// for (movie, review) in &movie_reviews {
///     println!("{movie}: \"{review}\"");
/// }
/// ```
///
/// 可以从数组初始化具有已知项列表的 `BTreeMap`：
///
/// ```
/// use std::collections::BTreeMap;
///
/// let solar_distance = BTreeMap::from([
///     ("Mercury", 0.4),
///     ("Venus", 0.7),
///     ("Earth", 1.0),
///     ("Mars", 1.5),
/// ]);
/// ```
///
/// `BTreeMap` 实现了一个 [`Entry API`]，它允许获取、设置、更新和删除键及其值的复杂方法：
///
/// [`Entry API`]: BTreeMap::entry
///
/// ```
/// use std::collections::BTreeMap;
///
/// // 通过类型推断，我们可以省略显式类型签名 (在本示例中为 `BTreeMap<&str, u8>`)。
/////
/// let mut player_stats = BTreeMap::new();
///
/// fn random_stat_buff() -> u8 {
///     // 实际上可以在这里返回一些随机值 - 现在让我们返回一些固定值
/////
///     42
/// }
///
/// // 仅在键不存在时才插入
/// player_stats.entry("health").or_insert(100);
///
/// // 仅当一个键不存在时，才使用提供新值的函数插入该键
/////
/// player_stats.entry("defence").or_insert_with(random_stat_buff);
///
/// // 更新键，以防止键可能未被设置
/// let stat = player_stats.entry("attack").or_insert(100);
/// *stat += random_stat_buff();
///
/// // 使用就地可变的在插入之前修改条目
/// player_stats.entry("mana").and_modify(|mana| *mana += 200).or_insert(100);
/// ```
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "BTreeMap")]
#[rustc_insignificant_dtor]
pub struct BTreeMap<
    K,
    V,
    #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator + Clone = Global,
> {
    root: Option<Root<K, V>>,
    length: usize,
    /// `ManuallyDrop` 控制丢弃顺序 (需要在所有节点之后丢弃)
    pub(super) alloc: ManuallyDrop<A>,
    // 对于 dropck; `Box` 避免使 `Unpin` impl 比以前更严格
    _marker: PhantomData<crate::boxed::Box<(K, V)>>,
}

#[stable(feature = "btree_drop", since = "1.7.0")]
unsafe impl<#[may_dangle] K, #[may_dangle] V, A: Allocator + Clone> Drop for BTreeMap<K, V, A> {
    fn drop(&mut self) {
        drop(unsafe { ptr::read(self) }.into_iter())
    }
}

// FIXME: 此实现是 "wrong"，但更改它将是一个重大更改。
// (自 Rust 1.50 以来，自动 `UnwindSafe` 实现的边界一直是这样的。) 也许我们仍然可以通过火山口运行来修复它，或者如果 `UnwindSafe` traits 已被弃用，或者在 future 中解除 (不再导致硬错误)。
//
//
#[stable(feature = "btree_unwindsafe", since = "1.64.0")]
impl<K, V, A: Allocator + Clone> core::panic::UnwindSafe for BTreeMap<K, V, A>
where
    A: core::panic::UnwindSafe,
    K: core::panic::RefUnwindSafe,
    V: core::panic::RefUnwindSafe,
{
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<K: Clone, V: Clone, A: Allocator + Clone> Clone for BTreeMap<K, V, A> {
    fn clone(&self) -> BTreeMap<K, V, A> {
        fn clone_subtree<'a, K: Clone, V: Clone, A: Allocator + Clone>(
            node: NodeRef<marker::Immut<'a>, K, V, marker::LeafOrInternal>,
            alloc: A,
        ) -> BTreeMap<K, V, A>
        where
            K: 'a,
            V: 'a,
        {
            match node.force() {
                Leaf(leaf) => {
                    let mut out_tree = BTreeMap {
                        root: Some(Root::new(alloc.clone())),
                        length: 0,
                        alloc: ManuallyDrop::new(alloc),
                        _marker: PhantomData,
                    };

                    {
                        let root = out_tree.root.as_mut().unwrap(); // 拆包成功，因为我们刚刚包装了
                        let mut out_node = match root.borrow_mut().force() {
                            Leaf(leaf) => leaf,
                            Internal(_) => unreachable!(),
                        };

                        let mut in_edge = leaf.first_edge();
                        while let Ok(kv) = in_edge.right_kv() {
                            let (k, v) = kv.into_kv();
                            in_edge = kv.right_edge();

                            out_node.push(k.clone(), v.clone());
                            out_tree.length += 1;
                        }
                    }

                    out_tree
                }
                Internal(internal) => {
                    let mut out_tree =
                        clone_subtree(internal.first_edge().descend(), alloc.clone());

                    {
                        let out_root = out_tree.root.as_mut().unwrap();
                        let mut out_node = out_root.push_internal_level(alloc.clone());
                        let mut in_edge = internal.first_edge();
                        while let Ok(kv) = in_edge.right_kv() {
                            let (k, v) = kv.into_kv();
                            in_edge = kv.right_edge();

                            let k = (*k).clone();
                            let v = (*v).clone();
                            let subtree = clone_subtree(in_edge.descend(), alloc.clone());

                            // 我们无法直接解构子树，因为 BTreeMap 实现了 Drop
                            //
                            let (subroot, sublength) = unsafe {
                                let subtree = ManuallyDrop::new(subtree);
                                let root = ptr::read(&subtree.root);
                                let length = subtree.length;
                                (root, length)
                            };

                            out_node.push(
                                k,
                                v,
                                subroot.unwrap_or_else(|| Root::new(alloc.clone())),
                            );
                            out_tree.length += 1 + sublength;
                        }
                    }

                    out_tree
                }
            }
        }

        if self.is_empty() {
            BTreeMap::new_in((*self.alloc).clone())
        } else {
            clone_subtree(self.root.as_ref().unwrap().reborrow(), (*self.alloc).clone()) // 拆包成功，因为不为空
        }
    }
}

impl<K, Q: ?Sized, A: Allocator + Clone> super::Recover<Q> for BTreeMap<K, SetValZST, A>
where
    K: Borrow<Q> + Ord,
    Q: Ord,
{
    type Key = K;

    fn get(&self, key: &Q) -> Option<&K> {
        let root_node = self.root.as_ref()?.reborrow();
        match root_node.search_tree(key) {
            Found(handle) => Some(handle.into_kv().0),
            GoDown(_) => None,
        }
    }

    fn take(&mut self, key: &Q) -> Option<K> {
        let (map, dormant_map) = DormantMutRef::new(self);
        let root_node = map.root.as_mut()?.borrow_mut();
        match root_node.search_tree(key) {
            Found(handle) => Some(
                OccupiedEntry {
                    handle,
                    dormant_map,
                    alloc: (*map.alloc).clone(),
                    _marker: PhantomData,
                }
                .remove_kv()
                .0,
            ),
            GoDown(_) => None,
        }
    }

    fn replace(&mut self, key: K) -> Option<K> {
        let (map, dormant_map) = DormantMutRef::new(self);
        let root_node =
            map.root.get_or_insert_with(|| Root::new((*map.alloc).clone())).borrow_mut();
        match root_node.search_tree::<K>(&key) {
            Found(mut kv) => Some(mem::replace(kv.key_mut(), key)),
            GoDown(handle) => {
                VacantEntry {
                    key,
                    handle: Some(handle),
                    dormant_map,
                    alloc: (*map.alloc).clone(),
                    _marker: PhantomData,
                }
                .insert(SetValZST::default());
                None
            }
        }
    }
}

/// `BTreeMap` 条目上的迭代器。
///
/// 该 `struct` 是通过 [`BTreeMap`] 上的 [`iter`] 方法创建的。
/// 有关更多信息，请参见其文档。
///
/// [`iter`]: BTreeMap::iter
#[must_use = "iterators are lazy and do nothing unless consumed"]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Iter<'a, K: 'a, V: 'a> {
    range: LazyLeafRange<marker::Immut<'a>, K, V>,
    length: usize,
}

#[stable(feature = "collection_debug", since = "1.17.0")]
impl<K: fmt::Debug, V: fmt::Debug> fmt::Debug for Iter<'_, K, V> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_list().entries(self.clone()).finish()
    }
}

#[stable(feature = "default_iters", since = "1.70.0")]
impl<'a, K: 'a, V: 'a> Default for Iter<'a, K, V> {
    /// 创建一个空的 `btree_map::Iter`。
    ///
    /// ```
    /// # use std::collections::btree_map;
    /// let iter: btree_map::Iter<'_, u8, u8> = Default::default();
    /// assert_eq!(iter.len(), 0);
    /// ```
    fn default() -> Self {
        Iter { range: Default::default(), length: 0 }
    }
}

/// `BTreeMap` 条目上的可变迭代器。
///
/// 该 `struct` 是通过 [`BTreeMap`] 上的 [`iter_mut`] 方法创建的。
/// 有关更多信息，请参见其文档。
///
/// [`iter_mut`]: BTreeMap::iter_mut
#[stable(feature = "rust1", since = "1.0.0")]
pub struct IterMut<'a, K: 'a, V: 'a> {
    range: LazyLeafRange<marker::ValMut<'a>, K, V>,
    length: usize,

    // 在 `K` 和 `V` 中保持不变
    _marker: PhantomData<&'a mut (K, V)>,
}

#[must_use = "iterators are lazy and do nothing unless consumed"]
#[stable(feature = "collection_debug", since = "1.17.0")]
impl<K: fmt::Debug, V: fmt::Debug> fmt::Debug for IterMut<'_, K, V> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let range = Iter { range: self.range.reborrow(), length: self.length };
        f.debug_list().entries(range).finish()
    }
}

#[stable(feature = "default_iters", since = "1.70.0")]
impl<'a, K: 'a, V: 'a> Default for IterMut<'a, K, V> {
    /// 创建一个空的 `btree_map::IterMut`。
    ///
    /// ```
    /// # use std::collections::btree_map;
    /// let iter: btree_map::IterMut<'_, u8, u8> = Default::default();
    /// assert_eq!(iter.len(), 0);
    /// ```
    fn default() -> Self {
        IterMut { range: Default::default(), length: 0, _marker: PhantomData {} }
    }
}

/// `BTreeMap` 条目上的所有者迭代器。
///
/// 这个 `struct` 是通过 [`BTreeMap`] 上的 [`into_iter`] 方法创建的 (由 [`IntoIterator`] trait 提供)。
/// 有关更多信息，请参见其文档。
///
/// [`into_iter`]: IntoIterator::into_iter
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_insignificant_dtor]
pub struct IntoIter<
    K,
    V,
    #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator + Clone = Global,
> {
    range: LazyLeafRange<marker::Dying, K, V>,
    length: usize,
    /// BTreeMap 将比 IntoIter 活得长，所以我们不关心 `alloc` 的丢弃顺序。
    alloc: A,
}

impl<K, V, A: Allocator + Clone> IntoIter<K, V, A> {
    /// 返回其余项上的迭代器。
    #[inline]
    pub(super) fn iter(&self) -> Iter<'_, K, V> {
        Iter { range: self.range.reborrow(), length: self.length }
    }
}

#[stable(feature = "collection_debug", since = "1.17.0")]
impl<K: Debug, V: Debug, A: Allocator + Clone> Debug for IntoIter<K, V, A> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_list().entries(self.iter()).finish()
    }
}

#[stable(feature = "default_iters", since = "1.70.0")]
impl<K, V, A> Default for IntoIter<K, V, A>
where
    A: Allocator + Default + Clone,
{
    /// 创建一个空的 `btree_map::IntoIter`。
    ///
    /// ```
    /// # use std::collections::btree_map;
    /// let iter: btree_map::IntoIter<u8, u8> = Default::default();
    /// assert_eq!(iter.len(), 0);
    /// ```
    fn default() -> Self {
        IntoIter { range: Default::default(), length: 0, alloc: Default::default() }
    }
}

/// `BTreeMap` 上的键的迭代器。
///
/// 该 `struct` 是通过 [`BTreeMap`] 上的 [`keys`] 方法创建的。
/// 有关更多信息，请参见其文档。
///
/// [`keys`]: BTreeMap::keys
#[must_use = "iterators are lazy and do nothing unless consumed"]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Keys<'a, K, V> {
    inner: Iter<'a, K, V>,
}

#[stable(feature = "collection_debug", since = "1.17.0")]
impl<K: fmt::Debug, V> fmt::Debug for Keys<'_, K, V> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_list().entries(self.clone()).finish()
    }
}

/// `BTreeMap` 值的迭代器。
///
/// 该 `struct` 是通过 [`BTreeMap`] 上的 [`values`] 方法创建的。
/// 有关更多信息，请参见其文档。
///
/// [`values`]: BTreeMap::values
#[must_use = "iterators are lazy and do nothing unless consumed"]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Values<'a, K, V> {
    inner: Iter<'a, K, V>,
}

#[stable(feature = "collection_debug", since = "1.17.0")]
impl<K, V: fmt::Debug> fmt::Debug for Values<'_, K, V> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_list().entries(self.clone()).finish()
    }
}

/// `BTreeMap` 的值上的可变迭代器。
///
/// 该 `struct` 是通过 [`BTreeMap`] 上的 [`values_mut`] 方法创建的。
/// 有关更多信息，请参见其文档。
///
/// [`values_mut`]: BTreeMap::values_mut
#[must_use = "iterators are lazy and do nothing unless consumed"]
#[stable(feature = "map_values_mut", since = "1.10.0")]
pub struct ValuesMut<'a, K, V> {
    inner: IterMut<'a, K, V>,
}

#[stable(feature = "map_values_mut", since = "1.10.0")]
impl<K, V: fmt::Debug> fmt::Debug for ValuesMut<'_, K, V> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_list().entries(self.inner.iter().map(|(_, val)| val)).finish()
    }
}

/// `BTreeMap` 的键上的拥有的迭代器。
///
/// 该 `struct` 是通过 [`BTreeMap`] 上的 [`into_keys`] 方法创建的。
/// 有关更多信息，请参见其文档。
///
/// [`into_keys`]: BTreeMap::into_keys
#[must_use = "iterators are lazy and do nothing unless consumed"]
#[stable(feature = "map_into_keys_values", since = "1.54.0")]
pub struct IntoKeys<K, V, A: Allocator + Clone = Global> {
    inner: IntoIter<K, V, A>,
}

#[stable(feature = "map_into_keys_values", since = "1.54.0")]
impl<K: fmt::Debug, V, A: Allocator + Clone> fmt::Debug for IntoKeys<K, V, A> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_list().entries(self.inner.iter().map(|(key, _)| key)).finish()
    }
}

/// `BTreeMap` 的值上的拥有的迭代器。
///
/// 该 `struct` 是通过 [`BTreeMap`] 上的 [`into_values`] 方法创建的。
/// 有关更多信息，请参见其文档。
///
/// [`into_values`]: BTreeMap::into_values
#[must_use = "iterators are lazy and do nothing unless consumed"]
#[stable(feature = "map_into_keys_values", since = "1.54.0")]
pub struct IntoValues<
    K,
    V,
    #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator + Clone = Global,
> {
    inner: IntoIter<K, V, A>,
}

#[stable(feature = "map_into_keys_values", since = "1.54.0")]
impl<K, V: fmt::Debug, A: Allocator + Clone> fmt::Debug for IntoValues<K, V, A> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_list().entries(self.inner.iter().map(|(_, val)| val)).finish()
    }
}

/// `BTreeMap` 中条目子范围的迭代器。
///
/// 该 `struct` 是通过 [`BTreeMap`] 上的 [`range`] 方法创建的。
/// 有关更多信息，请参见其文档。
///
/// [`range`]: BTreeMap::range
#[must_use = "iterators are lazy and do nothing unless consumed"]
#[stable(feature = "btree_range", since = "1.17.0")]
pub struct Range<'a, K: 'a, V: 'a> {
    inner: LeafRange<marker::Immut<'a>, K, V>,
}

#[stable(feature = "collection_debug", since = "1.17.0")]
impl<K: fmt::Debug, V: fmt::Debug> fmt::Debug for Range<'_, K, V> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_list().entries(self.clone()).finish()
    }
}

/// `BTreeMap` 中条目子范围上的可变迭代器。
///
/// 该 `struct` 是通过 [`BTreeMap`] 上的 [`range_mut`] 方法创建的。
/// 有关更多信息，请参见其文档。
///
/// [`range_mut`]: BTreeMap::range_mut
#[must_use = "iterators are lazy and do nothing unless consumed"]
#[stable(feature = "btree_range", since = "1.17.0")]
pub struct RangeMut<'a, K: 'a, V: 'a> {
    inner: LeafRange<marker::ValMut<'a>, K, V>,

    // 在 `K` 和 `V` 中保持不变
    _marker: PhantomData<&'a mut (K, V)>,
}

#[stable(feature = "collection_debug", since = "1.17.0")]
impl<K: fmt::Debug, V: fmt::Debug> fmt::Debug for RangeMut<'_, K, V> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let range = Range { inner: self.inner.reborrow() };
        f.debug_list().entries(range).finish()
    }
}

impl<K, V> BTreeMap<K, V> {
    /// 创建一个新的空 `BTreeMap`。
    ///
    /// 不会自行分配任何内容。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut map = BTreeMap::new();
    ///
    /// // 条目现在可以插入到空的 map 中
    /// map.insert(1, "a");
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[rustc_const_stable(feature = "const_btree_new", since = "1.66.0")]
    #[must_use]
    pub const fn new() -> BTreeMap<K, V> {
        BTreeMap { root: None, length: 0, alloc: ManuallyDrop::new(Global), _marker: PhantomData }
    }
}

impl<K, V, A: Allocator + Clone> BTreeMap<K, V, A> {
    /// 清除 map，删除所有元素。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut a = BTreeMap::new();
    /// a.insert(1, "a");
    /// a.clear();
    /// assert!(a.is_empty());
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn clear(&mut self) {
        // 避免移动分配器
        drop(BTreeMap {
            root: mem::replace(&mut self.root, None),
            length: mem::replace(&mut self.length, 0),
            alloc: self.alloc.clone(),
            _marker: PhantomData,
        });
    }

    /// 创建一个新的空 BTreeMap 并为 B 提供合理的选择。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// # #![feature(allocator_api)]
    /// # #![feature(btreemap_alloc)]
    /// use std::collections::BTreeMap;
    /// use std::alloc::Global;
    ///
    /// let mut map = BTreeMap::new_in(Global);
    ///
    /// // 条目现在可以插入到空的 map 中
    /// map.insert(1, "a");
    /// ```
    #[unstable(feature = "btreemap_alloc", issue = "32838")]
    pub fn new_in(alloc: A) -> BTreeMap<K, V, A> {
        BTreeMap { root: None, length: 0, alloc: ManuallyDrop::new(alloc), _marker: PhantomData }
    }
}

impl<K, V, A: Allocator + Clone> BTreeMap<K, V, A> {
    /// 返回与键对应的值的引用。
    ///
    /// 键可以是 map 的键类型的任何借用形式，但是借用形式上的顺序必须与键类型上的顺序匹配。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut map = BTreeMap::new();
    /// map.insert(1, "a");
    /// assert_eq!(map.get(&1), Some(&"a"));
    /// assert_eq!(map.get(&2), None);
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn get<Q: ?Sized>(&self, key: &Q) -> Option<&V>
    where
        K: Borrow<Q> + Ord,
        Q: Ord,
    {
        let root_node = self.root.as_ref()?.reborrow();
        match root_node.search_tree(key) {
            Found(handle) => Some(handle.into_kv().1),
            GoDown(_) => None,
        }
    }

    /// 返回与提供的键相对应的键值对。
    ///
    /// 提供的键可以是 map 的键类型的任何借用形式，但是借用形式上的顺序必须与键类型上的顺序匹配。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut map = BTreeMap::new();
    /// map.insert(1, "a");
    /// assert_eq!(map.get_key_value(&1), Some((&1, &"a")));
    /// assert_eq!(map.get_key_value(&2), None);
    /// ```
    #[stable(feature = "map_get_key_value", since = "1.40.0")]
    pub fn get_key_value<Q: ?Sized>(&self, k: &Q) -> Option<(&K, &V)>
    where
        K: Borrow<Q> + Ord,
        Q: Ord,
    {
        let root_node = self.root.as_ref()?.reborrow();
        match root_node.search_tree(k) {
            Found(handle) => Some(handle.into_kv()),
            GoDown(_) => None,
        }
    }

    /// 返回 map 中的第一个键值对。
    /// 该对中的键是 map 中的最小键。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut map = BTreeMap::new();
    /// assert_eq!(map.first_key_value(), None);
    /// map.insert(1, "b");
    /// map.insert(2, "a");
    /// assert_eq!(map.first_key_value(), Some((&1, &"b")));
    /// ```
    #[stable(feature = "map_first_last", since = "1.66.0")]
    pub fn first_key_value(&self) -> Option<(&K, &V)>
    where
        K: Ord,
    {
        let root_node = self.root.as_ref()?.reborrow();
        root_node.first_leaf_edge().right_kv().ok().map(Handle::into_kv)
    }

    /// 返回 map 中的第一个条目以进行就地操作。
    /// 此项的键是 map 中的最小键。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut map = BTreeMap::new();
    /// map.insert(1, "a");
    /// map.insert(2, "b");
    /// if let Some(mut entry) = map.first_entry() {
    ///     if *entry.key() > 0 {
    ///         entry.insert("first");
    ///     }
    /// }
    /// assert_eq!(*map.get(&1).unwrap(), "first");
    /// assert_eq!(*map.get(&2).unwrap(), "b");
    /// ```
    #[stable(feature = "map_first_last", since = "1.66.0")]
    pub fn first_entry(&mut self) -> Option<OccupiedEntry<'_, K, V, A>>
    where
        K: Ord,
    {
        let (map, dormant_map) = DormantMutRef::new(self);
        let root_node = map.root.as_mut()?.borrow_mut();
        let kv = root_node.first_leaf_edge().right_kv().ok()?;
        Some(OccupiedEntry {
            handle: kv.forget_node_type(),
            dormant_map,
            alloc: (*map.alloc).clone(),
            _marker: PhantomData,
        })
    }

    /// 删除并返回 map 中的第一个元素。
    /// 该元素的键是 map 中的最小键。
    ///
    /// # Examples
    ///
    /// Draining 元素以升序排列，同时每次迭代均保持可用的 map。
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut map = BTreeMap::new();
    /// map.insert(1, "a");
    /// map.insert(2, "b");
    /// while let Some((key, _val)) = map.pop_first() {
    ///     assert!(map.iter().all(|(k, _v)| *k > key));
    /// }
    /// assert!(map.is_empty());
    /// ```
    #[stable(feature = "map_first_last", since = "1.66.0")]
    pub fn pop_first(&mut self) -> Option<(K, V)>
    where
        K: Ord,
    {
        self.first_entry().map(|entry| entry.remove_entry())
    }

    /// 返回 map 中的最后一个键值对。
    /// 该对中的键是 map 中的最大键。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut map = BTreeMap::new();
    /// map.insert(1, "b");
    /// map.insert(2, "a");
    /// assert_eq!(map.last_key_value(), Some((&2, &"a")));
    /// ```
    #[stable(feature = "map_first_last", since = "1.66.0")]
    pub fn last_key_value(&self) -> Option<(&K, &V)>
    where
        K: Ord,
    {
        let root_node = self.root.as_ref()?.reborrow();
        root_node.last_leaf_edge().left_kv().ok().map(Handle::into_kv)
    }

    /// 返回 map 中的最后一项以进行就地操作。
    /// 此项的键是 map 中的最大键。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut map = BTreeMap::new();
    /// map.insert(1, "a");
    /// map.insert(2, "b");
    /// if let Some(mut entry) = map.last_entry() {
    ///     if *entry.key() > 0 {
    ///         entry.insert("last");
    ///     }
    /// }
    /// assert_eq!(*map.get(&1).unwrap(), "a");
    /// assert_eq!(*map.get(&2).unwrap(), "last");
    /// ```
    #[stable(feature = "map_first_last", since = "1.66.0")]
    pub fn last_entry(&mut self) -> Option<OccupiedEntry<'_, K, V, A>>
    where
        K: Ord,
    {
        let (map, dormant_map) = DormantMutRef::new(self);
        let root_node = map.root.as_mut()?.borrow_mut();
        let kv = root_node.last_leaf_edge().left_kv().ok()?;
        Some(OccupiedEntry {
            handle: kv.forget_node_type(),
            dormant_map,
            alloc: (*map.alloc).clone(),
            _marker: PhantomData,
        })
    }

    /// 删除并返回 map 中的最后一个元素。
    /// 该元素的键是 map 中的最大键。
    ///
    /// # Examples
    ///
    /// Draining 元素以降序排列，同时每次迭代均保留一个可用的 map。
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut map = BTreeMap::new();
    /// map.insert(1, "a");
    /// map.insert(2, "b");
    /// while let Some((key, _val)) = map.pop_last() {
    ///     assert!(map.iter().all(|(k, _v)| *k < key));
    /// }
    /// assert!(map.is_empty());
    /// ```
    #[stable(feature = "map_first_last", since = "1.66.0")]
    pub fn pop_last(&mut self) -> Option<(K, V)>
    where
        K: Ord,
    {
        self.last_entry().map(|entry| entry.remove_entry())
    }

    /// 如果 map 包含指定键的值，则返回 `true`。
    ///
    /// 键可以是 map 的键类型的任何借用形式，但是借用形式上的顺序必须与键类型上的顺序匹配。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut map = BTreeMap::new();
    /// map.insert(1, "a");
    /// assert_eq!(map.contains_key(&1), true);
    /// assert_eq!(map.contains_key(&2), false);
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn contains_key<Q: ?Sized>(&self, key: &Q) -> bool
    where
        K: Borrow<Q> + Ord,
        Q: Ord,
    {
        self.get(key).is_some()
    }

    /// 返回与键对应的值的可变引用。
    ///
    /// 键可以是 map 的键类型的任何借用形式，但是借用形式上的顺序必须与键类型上的顺序匹配。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut map = BTreeMap::new();
    /// map.insert(1, "a");
    /// if let Some(x) = map.get_mut(&1) {
    ///     *x = "b";
    /// }
    /// assert_eq!(map[&1], "b");
    /// ```
    // 有关实现说明，请参见 `get`，这基本上是复制粘贴，并添加了 mut
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn get_mut<Q: ?Sized>(&mut self, key: &Q) -> Option<&mut V>
    where
        K: Borrow<Q> + Ord,
        Q: Ord,
    {
        let root_node = self.root.as_mut()?.borrow_mut();
        match root_node.search_tree(key) {
            Found(handle) => Some(handle.into_val_mut()),
            GoDown(_) => None,
        }
    }

    /// 将键值对插入 map。
    ///
    /// 如果 map 不存在此键，则返回 `None`。
    ///
    /// 如果 map 确实存在此键，则更新值，并返回旧值。
    /// 但是，键不会更新。对于不能相同的 `==` 类型来说，这一点很重要。
    ///
    /// 有关更多信息，请参见 [模块级文档][module-level documentation]。
    ///
    /// [module-level documentation]: index.html#insert-and-complex-keys
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut map = BTreeMap::new();
    /// assert_eq!(map.insert(37, "a"), None);
    /// assert_eq!(map.is_empty(), false);
    ///
    /// map.insert(37, "b");
    /// assert_eq!(map.insert(37, "c"), Some("b"));
    /// assert_eq!(map[&37], "c");
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn insert(&mut self, key: K, value: V) -> Option<V>
    where
        K: Ord,
    {
        match self.entry(key) {
            Occupied(mut entry) => Some(entry.insert(value)),
            Vacant(entry) => {
                entry.insert(value);
                None
            }
        }
    }

    /// 尝试将键值对插入到 map 中，并向条目中的值返回变量引用。
    ///
    /// 如果 map 已经存在此键，则不进行任何更新，并返回包含占用项和值的错误。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// #![feature(map_try_insert)]
    ///
    /// use std::collections::BTreeMap;
    ///
    /// let mut map = BTreeMap::new();
    /// assert_eq!(map.try_insert(37, "a").unwrap(), &"a");
    ///
    /// let err = map.try_insert(37, "b").unwrap_err();
    /// assert_eq!(err.entry.key(), &37);
    /// assert_eq!(err.entry.get(), &"a");
    /// assert_eq!(err.value, "b");
    /// ```
    ///
    #[unstable(feature = "map_try_insert", issue = "82766")]
    pub fn try_insert(&mut self, key: K, value: V) -> Result<&mut V, OccupiedError<'_, K, V, A>>
    where
        K: Ord,
    {
        match self.entry(key) {
            Occupied(entry) => Err(OccupiedError { entry, value }),
            Vacant(entry) => Ok(entry.insert(value)),
        }
    }

    /// 从 map 中删除一个键，如果该键以前在 map 中，则返回该键的值。
    ///
    /// 键可以是 map 的键类型的任何借用形式，但是借用形式上的顺序必须与键类型上的顺序匹配。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut map = BTreeMap::new();
    /// map.insert(1, "a");
    /// assert_eq!(map.remove(&1), Some("a"));
    /// assert_eq!(map.remove(&1), None);
    /// ```
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn remove<Q: ?Sized>(&mut self, key: &Q) -> Option<V>
    where
        K: Borrow<Q> + Ord,
        Q: Ord,
    {
        self.remove_entry(key).map(|(_, v)| v)
    }

    /// 从 map 中删除一个键，如果该键以前在 map 中，则返回存储的键和值。
    ///
    /// 键可以是 map 的键类型的任何借用形式，但是借用形式上的顺序必须与键类型上的顺序匹配。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut map = BTreeMap::new();
    /// map.insert(1, "a");
    /// assert_eq!(map.remove_entry(&1), Some((1, "a")));
    /// assert_eq!(map.remove_entry(&1), None);
    /// ```
    ///
    #[stable(feature = "btreemap_remove_entry", since = "1.45.0")]
    pub fn remove_entry<Q: ?Sized>(&mut self, key: &Q) -> Option<(K, V)>
    where
        K: Borrow<Q> + Ord,
        Q: Ord,
    {
        let (map, dormant_map) = DormantMutRef::new(self);
        let root_node = map.root.as_mut()?.borrow_mut();
        match root_node.search_tree(key) {
            Found(handle) => Some(
                OccupiedEntry {
                    handle,
                    dormant_map,
                    alloc: (*map.alloc).clone(),
                    _marker: PhantomData,
                }
                .remove_entry(),
            ),
            GoDown(_) => None,
        }
    }

    /// 仅保留谓词指定的元素。
    ///
    /// 换句话说，删除所有 `f(&k, &mut v)` 返回 `false` 的 `(k, v)` 对。
    /// 元素按升序键顺序访问。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut map: BTreeMap<i32, i32> = (0..8).map(|x| (x, x*10)).collect();
    /// // 仅保留带有偶数键的元素。
    /// map.retain(|&k, _| k % 2 == 0);
    /// assert!(map.into_iter().eq(vec![(0, 0), (2, 20), (4, 40), (6, 60)]));
    /// ```
    #[inline]
    #[stable(feature = "btree_retain", since = "1.53.0")]
    pub fn retain<F>(&mut self, mut f: F)
    where
        K: Ord,
        F: FnMut(&K, &mut V) -> bool,
    {
        self.drain_filter(|k, v| !f(k, v));
    }

    /// 将所有元素从 `other` 移动到 `self`，使 `other` 为空。
    ///
    /// 如果 `other` 中的键已经存在于 `self` 中，则 `self` 中的相应值将被 `other` 中的相应值覆盖。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut a = BTreeMap::new();
    /// a.insert(1, "a");
    /// a.insert(2, "b");
    /// a.insert(3, "c"); // Note: 密钥 (3) 也出现在 b.
    ///
    /// let mut b = BTreeMap::new();
    /// b.insert(3, "d"); // Note: 密钥 (3) 也出现在 a.
    /// b.insert(4, "e");
    /// b.insert(5, "f");
    ///
    /// a.append(&mut b);
    ///
    /// assert_eq!(a.len(), 5);
    /// assert_eq!(b.len(), 0);
    ///
    /// assert_eq!(a[&1], "a");
    /// assert_eq!(a[&2], "b");
    /// assert_eq!(a[&3], "d"); // Note: "c" 已被覆盖。
    /// assert_eq!(a[&4], "e");
    /// assert_eq!(a[&5], "f");
    /// ```
    #[stable(feature = "btree_append", since = "1.11.0")]
    pub fn append(&mut self, other: &mut Self)
    where
        K: Ord,
        A: Clone,
    {
        // 我们必须附加任何东西吗？
        if other.is_empty() {
            return;
        }

        // 如果 `self` 为空，我们可以交换 `self` 和 `other`。
        if self.is_empty() {
            mem::swap(self, other);
            return;
        }

        let self_iter = mem::replace(self, Self::new_in((*self.alloc).clone())).into_iter();
        let other_iter = mem::replace(other, Self::new_in((*self.alloc).clone())).into_iter();
        let root = self.root.get_or_insert_with(|| Root::new((*self.alloc).clone()));
        root.append_from_sorted_iters(
            self_iter,
            other_iter,
            &mut self.length,
            (*self.alloc).clone(),
        )
    }

    /// 在 map 中的子元素范围上创建一个双端迭代器。
    /// 最简单的方法是使用范围语法 `min..max`，因此 `range(min..max)` 将产生从最小 (inclusive) 到最大 (exclusive) 的元素。
    /// 也可以将范围输入为 `(Bound<T>, Bound<T>)`，例如 `range((Excluded(4), Included(10)))` 将产生一个左排他的，范围从 4 到 10。
    ///
    ///
    /// # Panics
    ///
    /// 如果范围 `start > end`，就会出现 panics。
    /// 如果范围 `start == end` 和两个边界均为 `Excluded`，就会出现 panics。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// use std::collections::BTreeMap;
    /// use std::ops::Bound::Included;
    ///
    /// let mut map = BTreeMap::new();
    /// map.insert(3, "a");
    /// map.insert(5, "b");
    /// map.insert(8, "c");
    /// for (&key, &value) in map.range((Included(&4), Included(&8))) {
    ///     println!("{key}: {value}");
    /// }
    /// assert_eq!(Some((&5, &"b")), map.range(4..).next());
    /// ```
    ///
    ///
    #[stable(feature = "btree_range", since = "1.17.0")]
    pub fn range<T: ?Sized, R>(&self, range: R) -> Range<'_, K, V>
    where
        T: Ord,
        K: Borrow<T> + Ord,
        R: RangeBounds<T>,
    {
        if let Some(root) = &self.root {
            Range { inner: root.reborrow().range_search(range) }
        } else {
            Range { inner: LeafRange::none() }
        }
    }

    /// 在 map 中的子元素范围上创建一个可变的双端迭代器。
    /// 最简单的方法是使用范围语法 `min..max`，因此 `range(min..max)` 将产生从最小 (inclusive) 到最大 (exclusive) 的元素。
    /// 也可以将范围输入为 `(Bound<T>, Bound<T>)`，例如 `range((Excluded(4), Included(10)))` 将产生一个左排他的，范围从 4 到 10。
    ///
    ///
    /// # Panics
    ///
    /// 如果范围 `start > end`，就会出现 panics。
    /// 如果范围 `start == end` 和两个边界均为 `Excluded`，就会出现 panics。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut map: BTreeMap<&str, i32> =
    ///     [("Alice", 0), ("Bob", 0), ("Carol", 0), ("Cheryl", 0)].into();
    /// for (_, balance) in map.range_mut("B".."Cheryl") {
    ///     *balance += 100;
    /// }
    /// for (name, balance) in &map {
    ///     println!("{name} => {balance}");
    /// }
    /// ```
    ///
    ///
    #[stable(feature = "btree_range", since = "1.17.0")]
    pub fn range_mut<T: ?Sized, R>(&mut self, range: R) -> RangeMut<'_, K, V>
    where
        T: Ord,
        K: Borrow<T> + Ord,
        R: RangeBounds<T>,
    {
        if let Some(root) = &mut self.root {
            RangeMut { inner: root.borrow_valmut().range_search(range), _marker: PhantomData }
        } else {
            RangeMut { inner: LeafRange::none(), _marker: PhantomData }
        }
    }

    /// 在 map 中获取给定键的对应项，以进行就地操作。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut count: BTreeMap<&str, usize> = BTreeMap::new();
    ///
    /// // 计算 vec 中字母出现的次数
    /// for x in ["a", "b", "a", "c", "a", "b"] {
    ///     count.entry(x).and_modify(|curr| *curr += 1).or_insert(1);
    /// }
    ///
    /// assert_eq!(count["a"], 3);
    /// assert_eq!(count["b"], 2);
    /// assert_eq!(count["c"], 1);
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn entry(&mut self, key: K) -> Entry<'_, K, V, A>
    where
        K: Ord,
    {
        let (map, dormant_map) = DormantMutRef::new(self);
        match map.root {
            None => Vacant(VacantEntry {
                key,
                handle: None,
                dormant_map,
                alloc: (*map.alloc).clone(),
                _marker: PhantomData,
            }),
            Some(ref mut root) => match root.borrow_mut().search_tree(&key) {
                Found(handle) => Occupied(OccupiedEntry {
                    handle,
                    dormant_map,
                    alloc: (*map.alloc).clone(),
                    _marker: PhantomData,
                }),
                GoDown(handle) => Vacant(VacantEntry {
                    key,
                    handle: Some(handle),
                    dormant_map,
                    alloc: (*map.alloc).clone(),
                    _marker: PhantomData,
                }),
            },
        }
    }

    /// 在给定的键处将集合拆分为两个。
    /// 返回给定键之后的所有内容，包括键。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut a = BTreeMap::new();
    /// a.insert(1, "a");
    /// a.insert(2, "b");
    /// a.insert(3, "c");
    /// a.insert(17, "d");
    /// a.insert(41, "e");
    ///
    /// let b = a.split_off(&3);
    ///
    /// assert_eq!(a.len(), 2);
    /// assert_eq!(b.len(), 3);
    ///
    /// assert_eq!(a[&1], "a");
    /// assert_eq!(a[&2], "b");
    ///
    /// assert_eq!(b[&3], "c");
    /// assert_eq!(b[&17], "d");
    /// assert_eq!(b[&41], "e");
    /// ```
    #[stable(feature = "btree_split_off", since = "1.11.0")]
    pub fn split_off<Q: ?Sized + Ord>(&mut self, key: &Q) -> Self
    where
        K: Borrow<Q> + Ord,
        A: Clone,
    {
        if self.is_empty() {
            return Self::new_in((*self.alloc).clone());
        }

        let total_num = self.len();
        let left_root = self.root.as_mut().unwrap(); // 拆包成功，因为不为空

        let right_root = left_root.split_off(key, (*self.alloc).clone());

        let (new_left_len, right_len) = Root::calc_split_length(total_num, &left_root, &right_root);
        self.length = new_left_len;

        BTreeMap {
            root: Some(right_root),
            length: right_len,
            alloc: self.alloc.clone(),
            _marker: PhantomData,
        }
    }

    /// 创建一个迭代器，该迭代器以升序顺序访问所有元素 (键值对)，并使用闭包确定是否应删除元素。
    /// 如果闭包返回 `true`，则将元素从 map 中移除并产生。
    /// 如果闭包返回 `false` 或 panics，则该元素保留在 map 中，并且不会产生。
    ///
    /// 迭代器还允许您更改闭包中每个元素的值，而不管您是选择保留还是删除它。
    ///
    /// 如果迭代器仅被部分消耗或根本没有消耗，则其余每个元素仍将受到闭包的影响，闭包可能会更改其值，并通过返回 `true` 来丢弃该元素。
    ///
    ///
    /// 如果在闭包中出现 panic，或者在丢弃元素时发生 panic，或者 `DrainFilter` 值泄漏，将有多少个元素受到该闭包的影响，这是不确定的。
    ///
    /// # Examples
    ///
    /// 将 map 分为偶数和奇数键，重新使用原始的 map：
    ///
    /// ```
    /// #![feature(btree_drain_filter)]
    /// use std::collections::BTreeMap;
    ///
    /// let mut map: BTreeMap<i32, i32> = (0..8).map(|x| (x, x)).collect();
    /// let evens: BTreeMap<_, _> = map.drain_filter(|k, _v| k % 2 == 0).collect();
    /// let odds = map;
    /// assert_eq!(evens.keys().copied().collect::<Vec<_>>(), [0, 2, 4, 6]);
    /// assert_eq!(odds.keys().copied().collect::<Vec<_>>(), [1, 3, 5, 7]);
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[unstable(feature = "btree_drain_filter", issue = "70530")]
    pub fn drain_filter<F>(&mut self, pred: F) -> DrainFilter<'_, K, V, F, A>
    where
        K: Ord,
        F: FnMut(&K, &mut V) -> bool,
    {
        let (inner, alloc) = self.drain_filter_inner();
        DrainFilter { pred, inner, alloc }
    }

    pub(super) fn drain_filter_inner(&mut self) -> (DrainFilterInner<'_, K, V>, A)
    where
        K: Ord,
    {
        if let Some(root) = self.root.as_mut() {
            let (root, dormant_root) = DormantMutRef::new(root);
            let front = root.borrow_mut().first_leaf_edge();
            (
                DrainFilterInner {
                    length: &mut self.length,
                    dormant_root: Some(dormant_root),
                    cur_leaf_edge: Some(front),
                },
                (*self.alloc).clone(),
            )
        } else {
            (
                DrainFilterInner {
                    length: &mut self.length,
                    dormant_root: None,
                    cur_leaf_edge: None,
                },
                (*self.alloc).clone(),
            )
        }
    }

    /// 创建一个消费的迭代器，按顺序访问所有键。
    /// 调用后不能使用 map。
    /// 迭代器元素类型为 `K`。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut a = BTreeMap::new();
    /// a.insert(2, "b");
    /// a.insert(1, "a");
    ///
    /// let keys: Vec<i32> = a.into_keys().collect();
    /// assert_eq!(keys, [1, 2]);
    /// ```
    #[inline]
    #[stable(feature = "map_into_keys_values", since = "1.54.0")]
    pub fn into_keys(self) -> IntoKeys<K, V, A> {
        IntoKeys { inner: self.into_iter() }
    }

    /// 创建一个消费迭代器，按键顺序访问所有值。
    /// 调用后不能使用 map。
    /// 迭代器元素类型为 `V`。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut a = BTreeMap::new();
    /// a.insert(1, "hello");
    /// a.insert(2, "goodbye");
    ///
    /// let values: Vec<&str> = a.into_values().collect();
    /// assert_eq!(values, ["hello", "goodbye"]);
    /// ```
    #[inline]
    #[stable(feature = "map_into_keys_values", since = "1.54.0")]
    pub fn into_values(self) -> IntoValues<K, V, A> {
        IntoValues { inner: self.into_iter() }
    }

    /// 从排序的迭代器生成一个 `BTreeMap`。
    pub(crate) fn bulk_build_from_sorted_iter<I>(iter: I, alloc: A) -> Self
    where
        K: Ord,
        I: IntoIterator<Item = (K, V)>,
    {
        let mut root = Root::new(alloc.clone());
        let mut length = 0;
        root.bulk_push(DedupSortedIter::new(iter.into_iter()), &mut length, alloc.clone());
        BTreeMap { root: Some(root), length, alloc: ManuallyDrop::new(alloc), _marker: PhantomData }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<'a, K, V, A: Allocator + Clone> IntoIterator for &'a BTreeMap<K, V, A> {
    type Item = (&'a K, &'a V);
    type IntoIter = Iter<'a, K, V>;

    fn into_iter(self) -> Iter<'a, K, V> {
        self.iter()
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<'a, K: 'a, V: 'a> Iterator for Iter<'a, K, V> {
    type Item = (&'a K, &'a V);

    fn next(&mut self) -> Option<(&'a K, &'a V)> {
        if self.length == 0 {
            None
        } else {
            self.length -= 1;
            Some(unsafe { self.range.next_unchecked() })
        }
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        (self.length, Some(self.length))
    }

    fn last(mut self) -> Option<(&'a K, &'a V)> {
        self.next_back()
    }

    fn min(mut self) -> Option<(&'a K, &'a V)>
    where
        (&'a K, &'a V): Ord,
    {
        self.next()
    }

    fn max(mut self) -> Option<(&'a K, &'a V)>
    where
        (&'a K, &'a V): Ord,
    {
        self.next_back()
    }
}

#[stable(feature = "fused", since = "1.26.0")]
impl<K, V> FusedIterator for Iter<'_, K, V> {}

#[stable(feature = "rust1", since = "1.0.0")]
impl<'a, K: 'a, V: 'a> DoubleEndedIterator for Iter<'a, K, V> {
    fn next_back(&mut self) -> Option<(&'a K, &'a V)> {
        if self.length == 0 {
            None
        } else {
            self.length -= 1;
            Some(unsafe { self.range.next_back_unchecked() })
        }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<K, V> ExactSizeIterator for Iter<'_, K, V> {
    fn len(&self) -> usize {
        self.length
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<K, V> Clone for Iter<'_, K, V> {
    fn clone(&self) -> Self {
        Iter { range: self.range.clone(), length: self.length }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<'a, K, V, A: Allocator + Clone> IntoIterator for &'a mut BTreeMap<K, V, A> {
    type Item = (&'a K, &'a mut V);
    type IntoIter = IterMut<'a, K, V>;

    fn into_iter(self) -> IterMut<'a, K, V> {
        self.iter_mut()
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<'a, K, V> Iterator for IterMut<'a, K, V> {
    type Item = (&'a K, &'a mut V);

    fn next(&mut self) -> Option<(&'a K, &'a mut V)> {
        if self.length == 0 {
            None
        } else {
            self.length -= 1;
            Some(unsafe { self.range.next_unchecked() })
        }
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        (self.length, Some(self.length))
    }

    fn last(mut self) -> Option<(&'a K, &'a mut V)> {
        self.next_back()
    }

    fn min(mut self) -> Option<(&'a K, &'a mut V)>
    where
        (&'a K, &'a mut V): Ord,
    {
        self.next()
    }

    fn max(mut self) -> Option<(&'a K, &'a mut V)>
    where
        (&'a K, &'a mut V): Ord,
    {
        self.next_back()
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<'a, K, V> DoubleEndedIterator for IterMut<'a, K, V> {
    fn next_back(&mut self) -> Option<(&'a K, &'a mut V)> {
        if self.length == 0 {
            None
        } else {
            self.length -= 1;
            Some(unsafe { self.range.next_back_unchecked() })
        }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<K, V> ExactSizeIterator for IterMut<'_, K, V> {
    fn len(&self) -> usize {
        self.length
    }
}

#[stable(feature = "fused", since = "1.26.0")]
impl<K, V> FusedIterator for IterMut<'_, K, V> {}

impl<'a, K, V> IterMut<'a, K, V> {
    /// 返回其余项上的迭代器。
    #[inline]
    pub(super) fn iter(&self) -> Iter<'_, K, V> {
        Iter { range: self.range.reborrow(), length: self.length }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<K, V, A: Allocator + Clone> IntoIterator for BTreeMap<K, V, A> {
    type Item = (K, V);
    type IntoIter = IntoIter<K, V, A>;

    fn into_iter(self) -> IntoIter<K, V, A> {
        let mut me = ManuallyDrop::new(self);
        if let Some(root) = me.root.take() {
            let full_range = root.into_dying().full_range();

            IntoIter {
                range: full_range,
                length: me.length,
                alloc: unsafe { ManuallyDrop::take(&mut me.alloc) },
            }
        } else {
            IntoIter {
                range: LazyLeafRange::none(),
                length: 0,
                alloc: unsafe { ManuallyDrop::take(&mut me.alloc) },
            }
        }
    }
}

#[stable(feature = "btree_drop", since = "1.7.0")]
impl<K, V, A: Allocator + Clone> Drop for IntoIter<K, V, A> {
    fn drop(&mut self) {
        struct DropGuard<'a, K, V, A: Allocator + Clone>(&'a mut IntoIter<K, V, A>);

        impl<'a, K, V, A: Allocator + Clone> Drop for DropGuard<'a, K, V, A> {
            fn drop(&mut self) {
                // 继续我们下面执行的相同循环。
                // 这仅在展开时运行，因此我们这次不必担心 panic (它们会中止)。
                while let Some(kv) = self.0.dying_next() {
                    // SAFETY: 我们立即消耗这个 dying 的句柄。
                    unsafe { kv.drop_key_val() };
                }
            }
        }

        while let Some(kv) = self.dying_next() {
            let guard = DropGuard(self);
            // SAFETY: 在消耗掉 dying 的句柄之前，我们不会动树。
            unsafe { kv.drop_key_val() };
            mem::forget(guard);
        }
    }
}

impl<K, V, A: Allocator + Clone> IntoIter<K, V, A> {
    /// `next` 方法的核心是返回一个垂死的 KV 句柄，通过进一步调用这个函数和其他一些函数而无效。
    ///
    fn dying_next(
        &mut self,
    ) -> Option<Handle<NodeRef<marker::Dying, K, V, marker::LeafOrInternal>, marker::KV>> {
        if self.length == 0 {
            self.range.deallocating_end(self.alloc.clone());
            None
        } else {
            self.length -= 1;
            Some(unsafe { self.range.deallocating_next_unchecked(self.alloc.clone()) })
        }
    }

    /// `next_back` 方法的核心是返回一个垂死的 KV 句柄，通过进一步调用这个函数和其他一些函数而无效。
    ///
    fn dying_next_back(
        &mut self,
    ) -> Option<Handle<NodeRef<marker::Dying, K, V, marker::LeafOrInternal>, marker::KV>> {
        if self.length == 0 {
            self.range.deallocating_end(self.alloc.clone());
            None
        } else {
            self.length -= 1;
            Some(unsafe { self.range.deallocating_next_back_unchecked(self.alloc.clone()) })
        }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<K, V, A: Allocator + Clone> Iterator for IntoIter<K, V, A> {
    type Item = (K, V);

    fn next(&mut self) -> Option<(K, V)> {
        // SAFETY: 我们立即消耗这个 dying 的句柄。
        self.dying_next().map(unsafe { |kv| kv.into_key_val() })
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        (self.length, Some(self.length))
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<K, V, A: Allocator + Clone> DoubleEndedIterator for IntoIter<K, V, A> {
    fn next_back(&mut self) -> Option<(K, V)> {
        // SAFETY: 我们立即消耗这个 dying 的句柄。
        self.dying_next_back().map(unsafe { |kv| kv.into_key_val() })
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<K, V, A: Allocator + Clone> ExactSizeIterator for IntoIter<K, V, A> {
    fn len(&self) -> usize {
        self.length
    }
}

#[stable(feature = "fused", since = "1.26.0")]
impl<K, V, A: Allocator + Clone> FusedIterator for IntoIter<K, V, A> {}

#[stable(feature = "rust1", since = "1.0.0")]
impl<'a, K, V> Iterator for Keys<'a, K, V> {
    type Item = &'a K;

    fn next(&mut self) -> Option<&'a K> {
        self.inner.next().map(|(k, _)| k)
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        self.inner.size_hint()
    }

    fn last(mut self) -> Option<&'a K> {
        self.next_back()
    }

    fn min(mut self) -> Option<&'a K>
    where
        &'a K: Ord,
    {
        self.next()
    }

    fn max(mut self) -> Option<&'a K>
    where
        &'a K: Ord,
    {
        self.next_back()
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<'a, K, V> DoubleEndedIterator for Keys<'a, K, V> {
    fn next_back(&mut self) -> Option<&'a K> {
        self.inner.next_back().map(|(k, _)| k)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<K, V> ExactSizeIterator for Keys<'_, K, V> {
    fn len(&self) -> usize {
        self.inner.len()
    }
}

#[stable(feature = "fused", since = "1.26.0")]
impl<K, V> FusedIterator for Keys<'_, K, V> {}

#[stable(feature = "rust1", since = "1.0.0")]
impl<K, V> Clone for Keys<'_, K, V> {
    fn clone(&self) -> Self {
        Keys { inner: self.inner.clone() }
    }
}

#[stable(feature = "default_iters", since = "1.70.0")]
impl<K, V> Default for Keys<'_, K, V> {
    /// 创建一个空的 `btree_map::Keys`。
    ///
    /// ```
    /// # use std::collections::btree_map;
    /// let iter: btree_map::Keys<'_, u8, u8> = Default::default();
    /// assert_eq!(iter.len(), 0);
    /// ```
    fn default() -> Self {
        Keys { inner: Default::default() }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<'a, K, V> Iterator for Values<'a, K, V> {
    type Item = &'a V;

    fn next(&mut self) -> Option<&'a V> {
        self.inner.next().map(|(_, v)| v)
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        self.inner.size_hint()
    }

    fn last(mut self) -> Option<&'a V> {
        self.next_back()
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<'a, K, V> DoubleEndedIterator for Values<'a, K, V> {
    fn next_back(&mut self) -> Option<&'a V> {
        self.inner.next_back().map(|(_, v)| v)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<K, V> ExactSizeIterator for Values<'_, K, V> {
    fn len(&self) -> usize {
        self.inner.len()
    }
}

#[stable(feature = "fused", since = "1.26.0")]
impl<K, V> FusedIterator for Values<'_, K, V> {}

#[stable(feature = "rust1", since = "1.0.0")]
impl<K, V> Clone for Values<'_, K, V> {
    fn clone(&self) -> Self {
        Values { inner: self.inner.clone() }
    }
}

#[stable(feature = "default_iters", since = "1.70.0")]
impl<K, V> Default for Values<'_, K, V> {
    /// 创建一个空的 `btree_map::Values`。
    ///
    /// ```
    /// # use std::collections::btree_map;
    /// let iter: btree_map::Values<'_, u8, u8> = Default::default();
    /// assert_eq!(iter.len(), 0);
    /// ```
    fn default() -> Self {
        Values { inner: Default::default() }
    }
}

/// 通过在 BTreeMap 上调用 `drain_filter` 生成的迭代器。
#[unstable(feature = "btree_drain_filter", issue = "70530")]
pub struct DrainFilter<
    'a,
    K,
    V,
    F,
    #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator + Clone = Global,
> where
    F: 'a + FnMut(&K, &mut V) -> bool,
{
    pred: F,
    inner: DrainFilterInner<'a, K, V>,
    /// BTreeMap 将比 IntoIter 活得长，所以我们不关心 `alloc` 的丢弃顺序。
    alloc: A,
}
/// DrainFilter 的大多数实现在谓词类型上都是泛型的，因此也可用于 BTreeSet::DrainFilter。
///
pub(super) struct DrainFilterInner<'a, K, V> {
    /// 引用借用的 map 中的 length 字段，实时更新。
    length: &'a mut usize,
    /// 被引用到被借用 map 的根字段中。
    /// 包装在 `Option` 中，以允许 drop 处理器对其进行 `take` 处理。
    dormant_root: Option<DormantMutRef<'a, Root<K, V>>>,
    /// 在要返回的下一个元素或最后一个叶 edge 之前包含一个叶 edge。
    /// 如果 map 没有根，迭代超出了最后一片叶子 edge 或谓词中出现了 panic，则为空。
    ///
    cur_leaf_edge: Option<Handle<NodeRef<marker::Mut<'a>, K, V, marker::Leaf>, marker::Edge>>,
}

#[unstable(feature = "btree_drain_filter", issue = "70530")]
impl<K, V, F, A: Allocator + Clone> Drop for DrainFilter<'_, K, V, F, A>
where
    F: FnMut(&K, &mut V) -> bool,
{
    fn drop(&mut self) {
        self.for_each(drop);
    }
}

#[unstable(feature = "btree_drain_filter", issue = "70530")]
impl<K, V, F> fmt::Debug for DrainFilter<'_, K, V, F>
where
    K: fmt::Debug,
    V: fmt::Debug,
    F: FnMut(&K, &mut V) -> bool,
{
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_tuple("DrainFilter").field(&self.inner.peek()).finish()
    }
}

#[unstable(feature = "btree_drain_filter", issue = "70530")]
impl<K, V, F, A: Allocator + Clone> Iterator for DrainFilter<'_, K, V, F, A>
where
    F: FnMut(&K, &mut V) -> bool,
{
    type Item = (K, V);

    fn next(&mut self) -> Option<(K, V)> {
        self.inner.next(&mut self.pred, self.alloc.clone())
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        self.inner.size_hint()
    }
}

impl<'a, K, V> DrainFilterInner<'a, K, V> {
    /// 允许 Debug 实现预测下一个元素。
    pub(super) fn peek(&self) -> Option<(&K, &V)> {
        let edge = self.cur_leaf_edge.as_ref()?;
        edge.reborrow().next_kv().ok().map(Handle::into_kv)
    }

    /// 给定谓词，典型 `DrainFilter::next` 方法的实现。
    pub(super) fn next<F, A: Allocator + Clone>(&mut self, pred: &mut F, alloc: A) -> Option<(K, V)>
    where
        F: FnMut(&K, &mut V) -> bool,
    {
        while let Ok(mut kv) = self.cur_leaf_edge.take()?.next_kv() {
            let (k, v) = kv.kv_mut();
            if pred(k, v) {
                *self.length -= 1;
                let (kv, pos) = kv.remove_kv_tracking(
                    || {
                        // SAFETY: 我们将以不会使返回的位置无效的方式接触根部。
                        //
                        let root = unsafe { self.dormant_root.take().unwrap().awaken() };
                        root.pop_internal_level(alloc.clone());
                        self.dormant_root = Some(DormantMutRef::new(root).1);
                    },
                    alloc.clone(),
                );
                self.cur_leaf_edge = Some(pos);
                return Some(kv);
            }
            self.cur_leaf_edge = Some(kv.next_leaf_edge());
        }
        None
    }

    /// 典型的 `DrainFilter::size_hint` 方法的实现。
    pub(super) fn size_hint(&self) -> (usize, Option<usize>) {
        // 在大多数 btree 迭代器中，`self.length` 是要访问的元素数。
        // 在这里，它包含已访问的元素以及谓词决定不访问 drain 的元素。
        // 在迭代期间使这个上限更紧将需要一个额外的字段。
        //
        (0, Some(*self.length))
    }
}

#[unstable(feature = "btree_drain_filter", issue = "70530")]
impl<K, V, F> FusedIterator for DrainFilter<'_, K, V, F> where F: FnMut(&K, &mut V) -> bool {}

#[stable(feature = "btree_range", since = "1.17.0")]
impl<'a, K, V> Iterator for Range<'a, K, V> {
    type Item = (&'a K, &'a V);

    fn next(&mut self) -> Option<(&'a K, &'a V)> {
        self.inner.next_checked()
    }

    fn last(mut self) -> Option<(&'a K, &'a V)> {
        self.next_back()
    }

    fn min(mut self) -> Option<(&'a K, &'a V)>
    where
        (&'a K, &'a V): Ord,
    {
        self.next()
    }

    fn max(mut self) -> Option<(&'a K, &'a V)>
    where
        (&'a K, &'a V): Ord,
    {
        self.next_back()
    }
}

#[stable(feature = "default_iters", since = "1.70.0")]
impl<K, V> Default for Range<'_, K, V> {
    /// 创建一个空的 `btree_map::Range`。
    ///
    /// ```
    /// # use std::collections::btree_map;
    /// let iter: btree_map::Range<'_, u8, u8> = Default::default();
    /// assert_eq!(iter.count(), 0);
    /// ```
    fn default() -> Self {
        Range { inner: Default::default() }
    }
}

#[stable(feature = "map_values_mut", since = "1.10.0")]
impl<'a, K, V> Iterator for ValuesMut<'a, K, V> {
    type Item = &'a mut V;

    fn next(&mut self) -> Option<&'a mut V> {
        self.inner.next().map(|(_, v)| v)
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        self.inner.size_hint()
    }

    fn last(mut self) -> Option<&'a mut V> {
        self.next_back()
    }
}

#[stable(feature = "map_values_mut", since = "1.10.0")]
impl<'a, K, V> DoubleEndedIterator for ValuesMut<'a, K, V> {
    fn next_back(&mut self) -> Option<&'a mut V> {
        self.inner.next_back().map(|(_, v)| v)
    }
}

#[stable(feature = "map_values_mut", since = "1.10.0")]
impl<K, V> ExactSizeIterator for ValuesMut<'_, K, V> {
    fn len(&self) -> usize {
        self.inner.len()
    }
}

#[stable(feature = "fused", since = "1.26.0")]
impl<K, V> FusedIterator for ValuesMut<'_, K, V> {}

#[stable(feature = "map_into_keys_values", since = "1.54.0")]
impl<K, V, A: Allocator + Clone> Iterator for IntoKeys<K, V, A> {
    type Item = K;

    fn next(&mut self) -> Option<K> {
        self.inner.next().map(|(k, _)| k)
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        self.inner.size_hint()
    }

    fn last(mut self) -> Option<K> {
        self.next_back()
    }

    fn min(mut self) -> Option<K>
    where
        K: Ord,
    {
        self.next()
    }

    fn max(mut self) -> Option<K>
    where
        K: Ord,
    {
        self.next_back()
    }
}

#[stable(feature = "map_into_keys_values", since = "1.54.0")]
impl<K, V, A: Allocator + Clone> DoubleEndedIterator for IntoKeys<K, V, A> {
    fn next_back(&mut self) -> Option<K> {
        self.inner.next_back().map(|(k, _)| k)
    }
}

#[stable(feature = "map_into_keys_values", since = "1.54.0")]
impl<K, V, A: Allocator + Clone> ExactSizeIterator for IntoKeys<K, V, A> {
    fn len(&self) -> usize {
        self.inner.len()
    }
}

#[stable(feature = "map_into_keys_values", since = "1.54.0")]
impl<K, V, A: Allocator + Clone> FusedIterator for IntoKeys<K, V, A> {}

#[stable(feature = "default_iters", since = "1.70.0")]
impl<K, V, A> Default for IntoKeys<K, V, A>
where
    A: Allocator + Default + Clone,
{
    /// 创建一个空的 `btree_map::IntoKeys`。
    ///
    /// ```
    /// # use std::collections::btree_map;
    /// let iter: btree_map::IntoKeys<u8, u8> = Default::default();
    /// assert_eq!(iter.len(), 0);
    /// ```
    fn default() -> Self {
        IntoKeys { inner: Default::default() }
    }
}

#[stable(feature = "map_into_keys_values", since = "1.54.0")]
impl<K, V, A: Allocator + Clone> Iterator for IntoValues<K, V, A> {
    type Item = V;

    fn next(&mut self) -> Option<V> {
        self.inner.next().map(|(_, v)| v)
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        self.inner.size_hint()
    }

    fn last(mut self) -> Option<V> {
        self.next_back()
    }
}

#[stable(feature = "map_into_keys_values", since = "1.54.0")]
impl<K, V, A: Allocator + Clone> DoubleEndedIterator for IntoValues<K, V, A> {
    fn next_back(&mut self) -> Option<V> {
        self.inner.next_back().map(|(_, v)| v)
    }
}

#[stable(feature = "map_into_keys_values", since = "1.54.0")]
impl<K, V, A: Allocator + Clone> ExactSizeIterator for IntoValues<K, V, A> {
    fn len(&self) -> usize {
        self.inner.len()
    }
}

#[stable(feature = "map_into_keys_values", since = "1.54.0")]
impl<K, V, A: Allocator + Clone> FusedIterator for IntoValues<K, V, A> {}

#[stable(feature = "default_iters", since = "1.70.0")]
impl<K, V, A> Default for IntoValues<K, V, A>
where
    A: Allocator + Default + Clone,
{
    /// 创建一个空的 `btree_map::IntoValues`。
    ///
    /// ```
    /// # use std::collections::btree_map;
    /// let iter: btree_map::IntoValues<u8, u8> = Default::default();
    /// assert_eq!(iter.len(), 0);
    /// ```
    fn default() -> Self {
        IntoValues { inner: Default::default() }
    }
}

#[stable(feature = "btree_range", since = "1.17.0")]
impl<'a, K, V> DoubleEndedIterator for Range<'a, K, V> {
    fn next_back(&mut self) -> Option<(&'a K, &'a V)> {
        self.inner.next_back_checked()
    }
}

#[stable(feature = "fused", since = "1.26.0")]
impl<K, V> FusedIterator for Range<'_, K, V> {}

#[stable(feature = "btree_range", since = "1.17.0")]
impl<K, V> Clone for Range<'_, K, V> {
    fn clone(&self) -> Self {
        Range { inner: self.inner.clone() }
    }
}

#[stable(feature = "btree_range", since = "1.17.0")]
impl<'a, K, V> Iterator for RangeMut<'a, K, V> {
    type Item = (&'a K, &'a mut V);

    fn next(&mut self) -> Option<(&'a K, &'a mut V)> {
        self.inner.next_checked()
    }

    fn last(mut self) -> Option<(&'a K, &'a mut V)> {
        self.next_back()
    }

    fn min(mut self) -> Option<(&'a K, &'a mut V)>
    where
        (&'a K, &'a mut V): Ord,
    {
        self.next()
    }

    fn max(mut self) -> Option<(&'a K, &'a mut V)>
    where
        (&'a K, &'a mut V): Ord,
    {
        self.next_back()
    }
}

#[stable(feature = "btree_range", since = "1.17.0")]
impl<'a, K, V> DoubleEndedIterator for RangeMut<'a, K, V> {
    fn next_back(&mut self) -> Option<(&'a K, &'a mut V)> {
        self.inner.next_back_checked()
    }
}

#[stable(feature = "fused", since = "1.26.0")]
impl<K, V> FusedIterator for RangeMut<'_, K, V> {}

#[stable(feature = "rust1", since = "1.0.0")]
impl<K: Ord, V> FromIterator<(K, V)> for BTreeMap<K, V> {
    fn from_iter<T: IntoIterator<Item = (K, V)>>(iter: T) -> BTreeMap<K, V> {
        let mut inputs: Vec<_> = iter.into_iter().collect();

        if inputs.is_empty() {
            return BTreeMap::new();
        }

        // 使用稳定排序来保留插入顺序。
        inputs.sort_by(|a, b| a.0.cmp(&b.0));
        BTreeMap::bulk_build_from_sorted_iter(inputs, Global)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<K: Ord, V, A: Allocator + Clone> Extend<(K, V)> for BTreeMap<K, V, A> {
    #[inline]
    fn extend<T: IntoIterator<Item = (K, V)>>(&mut self, iter: T) {
        iter.into_iter().for_each(move |(k, v)| {
            self.insert(k, v);
        });
    }

    #[inline]
    fn extend_one(&mut self, (k, v): (K, V)) {
        self.insert(k, v);
    }
}

#[stable(feature = "extend_ref", since = "1.2.0")]
impl<'a, K: Ord + Copy, V: Copy, A: Allocator + Clone> Extend<(&'a K, &'a V)>
    for BTreeMap<K, V, A>
{
    fn extend<I: IntoIterator<Item = (&'a K, &'a V)>>(&mut self, iter: I) {
        self.extend(iter.into_iter().map(|(&key, &value)| (key, value)));
    }

    #[inline]
    fn extend_one(&mut self, (&k, &v): (&'a K, &'a V)) {
        self.insert(k, v);
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<K: Hash, V: Hash, A: Allocator + Clone> Hash for BTreeMap<K, V, A> {
    fn hash<H: Hasher>(&self, state: &mut H) {
        state.write_length_prefix(self.len());
        for elt in self {
            elt.hash(state);
        }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<K, V> Default for BTreeMap<K, V> {
    /// 创建一个空的 `BTreeMap`。
    fn default() -> BTreeMap<K, V> {
        BTreeMap::new()
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<K: PartialEq, V: PartialEq, A: Allocator + Clone> PartialEq for BTreeMap<K, V, A> {
    fn eq(&self, other: &BTreeMap<K, V, A>) -> bool {
        self.len() == other.len() && self.iter().zip(other).all(|(a, b)| a == b)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<K: Eq, V: Eq, A: Allocator + Clone> Eq for BTreeMap<K, V, A> {}

#[stable(feature = "rust1", since = "1.0.0")]
impl<K: PartialOrd, V: PartialOrd, A: Allocator + Clone> PartialOrd for BTreeMap<K, V, A> {
    #[inline]
    fn partial_cmp(&self, other: &BTreeMap<K, V, A>) -> Option<Ordering> {
        self.iter().partial_cmp(other.iter())
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<K: Ord, V: Ord, A: Allocator + Clone> Ord for BTreeMap<K, V, A> {
    #[inline]
    fn cmp(&self, other: &BTreeMap<K, V, A>) -> Ordering {
        self.iter().cmp(other.iter())
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<K: Debug, V: Debug, A: Allocator + Clone> Debug for BTreeMap<K, V, A> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_map().entries(self.iter()).finish()
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<K, Q: ?Sized, V, A: Allocator + Clone> Index<&Q> for BTreeMap<K, V, A>
where
    K: Borrow<Q> + Ord,
    Q: Ord,
{
    type Output = V;

    /// 返回与提供的键对应的值的引用。
    ///
    /// # Panics
    ///
    /// 如果键不存在于 `BTreeMap` 中，就会出现 panic。
    #[inline]
    fn index(&self, key: &Q) -> &V {
        self.get(key).expect("no entry found for key")
    }
}

#[stable(feature = "std_collections_from_array", since = "1.56.0")]
impl<K: Ord, V, const N: usize> From<[(K, V); N]> for BTreeMap<K, V> {
    /// 将 `[(K, V); N]` 转换为 `BTreeMap<(K, V)>`。
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let map1 = BTreeMap::from([(1, 2), (3, 4)]);
    /// let map2: BTreeMap<_, _> = [(1, 2), (3, 4)].into();
    /// assert_eq!(map1, map2);
    /// ```
    fn from(mut arr: [(K, V); N]) -> Self {
        if N == 0 {
            return BTreeMap::new();
        }

        // 使用稳定排序来保留插入顺序。
        arr.sort_by(|a, b| a.0.cmp(&b.0));
        BTreeMap::bulk_build_from_sorted_iter(arr, Global)
    }
}

impl<K, V, A: Allocator + Clone> BTreeMap<K, V, A> {
    /// 获取对 map 的条目进行迭代的迭代器，按键排序。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut map = BTreeMap::new();
    /// map.insert(3, "c");
    /// map.insert(2, "b");
    /// map.insert(1, "a");
    ///
    /// for (key, value) in map.iter() {
    ///     println!("{key}: {value}");
    /// }
    ///
    /// let (first_key, first_value) = map.iter().next().unwrap();
    /// assert_eq!((*first_key, *first_value), (1, "a"));
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn iter(&self) -> Iter<'_, K, V> {
        if let Some(root) = &self.root {
            let full_range = root.reborrow().full_range();

            Iter { range: full_range, length: self.length }
        } else {
            Iter { range: LazyLeafRange::none(), length: 0 }
        }
    }

    /// 在 map 的条目上获取一个可变迭代器，按键排序。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut map = BTreeMap::from([
    ///    ("a", 1),
    ///    ("b", 2),
    ///    ("c", 3),
    /// ]);
    ///
    /// // 如果键不是 "a"，则将值加 10
    /// for (key, value) in map.iter_mut() {
    ///     if key != &"a" {
    ///         *value += 10;
    ///     }
    /// }
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn iter_mut(&mut self) -> IterMut<'_, K, V> {
        if let Some(root) = &mut self.root {
            let full_range = root.borrow_valmut().full_range();

            IterMut { range: full_range, length: self.length, _marker: PhantomData }
        } else {
            IterMut { range: LazyLeafRange::none(), length: 0, _marker: PhantomData }
        }
    }

    /// 以排序顺序在 map 的键上获取一个迭代器。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut a = BTreeMap::new();
    /// a.insert(2, "b");
    /// a.insert(1, "a");
    ///
    /// let keys: Vec<_> = a.keys().cloned().collect();
    /// assert_eq!(keys, [1, 2]);
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn keys(&self) -> Keys<'_, K, V> {
        Keys { inner: self.iter() }
    }

    /// 按键顺序获取 map 值的迭代器。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut a = BTreeMap::new();
    /// a.insert(1, "hello");
    /// a.insert(2, "goodbye");
    ///
    /// let values: Vec<&str> = a.values().cloned().collect();
    /// assert_eq!(values, ["hello", "goodbye"]);
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn values(&self) -> Values<'_, K, V> {
        Values { inner: self.iter() }
    }

    /// 按键顺序获取 map 值的可变迭代器。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut a = BTreeMap::new();
    /// a.insert(1, String::from("hello"));
    /// a.insert(2, String::from("goodbye"));
    ///
    /// for value in a.values_mut() {
    ///     value.push_str("!");
    /// }
    ///
    /// let values: Vec<String> = a.values().cloned().collect();
    /// assert_eq!(values, [String::from("hello!"),
    ///                     String::from("goodbye!")]);
    /// ```
    #[stable(feature = "map_values_mut", since = "1.10.0")]
    pub fn values_mut(&mut self) -> ValuesMut<'_, K, V> {
        ValuesMut { inner: self.iter_mut() }
    }

    /// 返回 map 中的元素数。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut a = BTreeMap::new();
    /// assert_eq!(a.len(), 0);
    /// a.insert(1, "a");
    /// assert_eq!(a.len(), 1);
    /// ```
    #[must_use]
    #[stable(feature = "rust1", since = "1.0.0")]
    #[rustc_const_unstable(
        feature = "const_btree_len",
        issue = "71835",
        implied_by = "const_btree_new"
    )]
    pub const fn len(&self) -> usize {
        self.length
    }

    /// 如果 map 不包含任何元素，则返回 `true`。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// use std::collections::BTreeMap;
    ///
    /// let mut a = BTreeMap::new();
    /// assert!(a.is_empty());
    /// a.insert(1, "a");
    /// assert!(!a.is_empty());
    /// ```
    #[must_use]
    #[stable(feature = "rust1", since = "1.0.0")]
    #[rustc_const_unstable(
        feature = "const_btree_len",
        issue = "71835",
        implied_by = "const_btree_new"
    )]
    pub const fn is_empty(&self) -> bool {
        self.len() == 0
    }

    /// 返回指向第一个高于给定边界的元素的 [`Cursor`]。
    ///
    /// 如果不存在这样的元素，则返回指向 "ghost" 非元素的游标。
    ///
    /// 传递 [`Bound::Unbounded`] 将返回指向 map 的第一个元素的游标。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// #![feature(btree_cursors)]
    ///
    /// use std::collections::BTreeMap;
    /// use std::ops::Bound;
    ///
    /// let mut a = BTreeMap::new();
    /// a.insert(1, "a");
    /// a.insert(2, "b");
    /// a.insert(3, "c");
    /// a.insert(4, "c");
    /// let cursor = a.lower_bound(Bound::Excluded(&2));
    /// assert_eq!(cursor.key(), Some(&3));
    /// ```
    ///
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn lower_bound<Q>(&self, bound: Bound<&Q>) -> Cursor<'_, K, V>
    where
        K: Borrow<Q> + Ord,
        Q: Ord,
    {
        let root_node = match self.root.as_ref() {
            None => return Cursor { current: None, root: None },
            Some(root) => root.reborrow(),
        };
        let edge = root_node.lower_bound(SearchBound::from_range(bound));
        Cursor { current: edge.next_kv().ok(), root: self.root.as_ref() }
    }

    /// 返回指向第一个高于给定边界的元素的 [`CursorMut`]。
    ///
    /// 如果不存在这样的元素，则返回指向 "ghost" 非元素的游标。
    ///
    /// 传递 [`Bound::Unbounded`] 将返回指向 map 的第一个元素的游标。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// #![feature(btree_cursors)]
    ///
    /// use std::collections::BTreeMap;
    /// use std::ops::Bound;
    ///
    /// let mut a = BTreeMap::new();
    /// a.insert(1, "a");
    /// a.insert(2, "b");
    /// a.insert(3, "c");
    /// a.insert(4, "c");
    /// let cursor = a.lower_bound_mut(Bound::Excluded(&2));
    /// assert_eq!(cursor.key(), Some(&3));
    /// ```
    ///
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn lower_bound_mut<Q>(&mut self, bound: Bound<&Q>) -> CursorMut<'_, K, V, A>
    where
        K: Borrow<Q> + Ord,
        Q: Ord,
    {
        let (root, dormant_root) = DormantMutRef::new(&mut self.root);
        let root_node = match root.as_mut() {
            None => {
                return CursorMut {
                    current: None,
                    root: dormant_root,
                    length: &mut self.length,
                    alloc: &mut *self.alloc,
                };
            }
            Some(root) => root.borrow_mut(),
        };
        let edge = root_node.lower_bound(SearchBound::from_range(bound));
        CursorMut {
            current: edge.next_kv().ok(),
            root: dormant_root,
            length: &mut self.length,
            alloc: &mut *self.alloc,
        }
    }

    /// 返回指向低于给定界限的最后一个元素的 [`Cursor`]。
    ///
    /// 如果不存在这样的元素，则返回指向 "ghost" 非元素的游标。
    ///
    /// 传递 [`Bound::Unbounded`] 将返回指向 map 的最后一个元素的游标。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// #![feature(btree_cursors)]
    ///
    /// use std::collections::BTreeMap;
    /// use std::ops::Bound;
    ///
    /// let mut a = BTreeMap::new();
    /// a.insert(1, "a");
    /// a.insert(2, "b");
    /// a.insert(3, "c");
    /// a.insert(4, "c");
    /// let cursor = a.upper_bound(Bound::Excluded(&3));
    /// assert_eq!(cursor.key(), Some(&2));
    /// ```
    ///
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn upper_bound<Q>(&self, bound: Bound<&Q>) -> Cursor<'_, K, V>
    where
        K: Borrow<Q> + Ord,
        Q: Ord,
    {
        let root_node = match self.root.as_ref() {
            None => return Cursor { current: None, root: None },
            Some(root) => root.reborrow(),
        };
        let edge = root_node.upper_bound(SearchBound::from_range(bound));
        Cursor { current: edge.next_back_kv().ok(), root: self.root.as_ref() }
    }

    /// 返回指向低于给定界限的最后一个元素的 [`CursorMut`]。
    ///
    /// 如果不存在这样的元素，则返回指向 "ghost" 非元素的游标。
    ///
    /// 传递 [`Bound::Unbounded`] 将返回指向 map 的最后一个元素的游标。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// #![feature(btree_cursors)]
    ///
    /// use std::collections::BTreeMap;
    /// use std::ops::Bound;
    ///
    /// let mut a = BTreeMap::new();
    /// a.insert(1, "a");
    /// a.insert(2, "b");
    /// a.insert(3, "c");
    /// a.insert(4, "c");
    /// let cursor = a.upper_bound_mut(Bound::Excluded(&3));
    /// assert_eq!(cursor.key(), Some(&2));
    /// ```
    ///
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn upper_bound_mut<Q>(&mut self, bound: Bound<&Q>) -> CursorMut<'_, K, V, A>
    where
        K: Borrow<Q> + Ord,
        Q: Ord,
    {
        let (root, dormant_root) = DormantMutRef::new(&mut self.root);
        let root_node = match root.as_mut() {
            None => {
                return CursorMut {
                    current: None,
                    root: dormant_root,
                    length: &mut self.length,
                    alloc: &mut *self.alloc,
                };
            }
            Some(root) => root.borrow_mut(),
        };
        let edge = root_node.upper_bound(SearchBound::from_range(bound));
        CursorMut {
            current: edge.next_back_kv().ok(),
            root: dormant_root,
            length: &mut self.length,
            alloc: &mut *self.alloc,
        }
    }
}

/// `BTreeMap` 上的游标。
///
/// `Cursor` 类似于迭代器，不同之处在于它可以自由地来回查找。
///
/// 游标总是指向树中的一个元素，并以逻辑循环的方式进行索引。
/// 为了适应这一点，有一个 "ghost" 非元素在树的最后一个元素和第一个元素之间产生 `None`。
///
///
/// `Cursor` 是使用 [`BTreeMap::lower_bound`] 和 [`BTreeMap::upper_bound`] 方法创建的。
#[unstable(feature = "btree_cursors", issue = "107540")]
pub struct Cursor<'a, K: 'a, V: 'a> {
    current: Option<Handle<NodeRef<marker::Immut<'a>, K, V, marker::LeafOrInternal>, marker::KV>>,
    root: Option<&'a node::Root<K, V>>,
}

#[unstable(feature = "btree_cursors", issue = "107540")]
impl<K, V> Clone for Cursor<'_, K, V> {
    fn clone(&self) -> Self {
        let Cursor { current, root } = *self;
        Cursor { current, root }
    }
}

#[unstable(feature = "btree_cursors", issue = "107540")]
impl<K: Debug, V: Debug> Debug for Cursor<'_, K, V> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_tuple("Cursor").field(&self.key_value()).finish()
    }
}

/// `BTreeMap` 上的游标具有编辑操作。
///
/// `Cursor` 就像一个迭代器，除了它可以自由地来回 seek，并且可以在迭代期间安全地改变树。
/// 这是因为它产生的引用的生命周期与它自己的生命周期相关联，而不仅仅是底层树。
/// 这意味着游标不能一次产生多个元素。
///
/// 游标总是指向树中的一个元素，并以逻辑循环的方式进行索引。
/// 为了适应这一点，有一个 "ghost" 非元素在树的最后一个元素和第一个元素之间产生 `None`。
///
/// `Cursor` 是使用 [`BTreeMap::lower_bound_mut`] 和 [`BTreeMap::upper_bound_mut`] 方法创建的。
///
///
///
#[unstable(feature = "btree_cursors", issue = "107540")]
pub struct CursorMut<
    'a,
    K: 'a,
    V: 'a,
    #[unstable(feature = "allocator_api", issue = "32838")] A = Global,
> {
    current: Option<Handle<NodeRef<marker::Mut<'a>, K, V, marker::LeafOrInternal>, marker::KV>>,
    root: DormantMutRef<'a, Option<node::Root<K, V>>>,
    length: &'a mut usize,
    alloc: &'a mut A,
}

#[unstable(feature = "btree_cursors", issue = "107540")]
impl<K: Debug, V: Debug, A> Debug for CursorMut<'_, K, V, A> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_tuple("CursorMut").field(&self.key_value()).finish()
    }
}

impl<'a, K, V> Cursor<'a, K, V> {
    /// 将游标移动到 `BTreeMap` 的下一个元素。
    ///
    /// 如果游标指向 "ghost" 非元素，那么这会将其移动到 `BTreeMap` 的第一个元素。
    /// 如果它指向 `BTreeMap` 的最后一个元素，那么这会将它移动到 "ghost" 非元素。
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn move_next(&mut self) {
        match self.current.take() {
            None => {
                self.current = self.root.and_then(|root| {
                    root.reborrow().first_leaf_edge().forget_node_type().right_kv().ok()
                });
            }
            Some(current) => {
                self.current = current.next_leaf_edge().next_kv().ok();
            }
        }
    }

    /// 将游标移动到 `BTreeMap` 的前一个元素。
    ///
    /// 如果游标指向 "ghost" 非元素，那么这会将其移动到 `BTreeMap` 的最后一个元素。
    /// 如果它指向 `BTreeMap` 的第一个元素，那么这会将它移动到 "ghost" 非元素。
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn move_prev(&mut self) {
        match self.current.take() {
            None => {
                self.current = self.root.and_then(|root| {
                    root.reborrow().last_leaf_edge().forget_node_type().left_kv().ok()
                });
            }
            Some(current) => {
                self.current = current.next_back_leaf_edge().next_back_kv().ok();
            }
        }
    }

    /// 将引用返回到游标当前指向的元素的键。
    ///
    ///
    /// 如果游标当前指向 "ghost" 非元素，则返回 `None`。
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn key(&self) -> Option<&'a K> {
        self.current.as_ref().map(|current| current.into_kv().0)
    }

    /// 将引用返回到游标当前指向的元素的值。
    ///
    ///
    /// 如果游标当前指向 "ghost" 非元素，则返回 `None`。
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn value(&self) -> Option<&'a V> {
        self.current.as_ref().map(|current| current.into_kv().1)
    }

    /// 将引用返回到游标当前指向的元素的键和值。
    ///
    ///
    /// 如果游标当前指向 "ghost" 非元素，则返回 `None`。
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn key_value(&self) -> Option<(&'a K, &'a V)> {
        self.current.as_ref().map(|current| current.into_kv())
    }

    /// 返回下一个元素的引用。
    ///
    /// 如果游标指向 "ghost" 非元素，则返回 `BTreeMap` 的第一个元素。
    /// 如果它指向 `BTreeMap` 的最后一个元素，则返回 `None`。
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn peek_next(&self) -> Option<(&'a K, &'a V)> {
        let mut next = self.clone();
        next.move_next();
        next.current.as_ref().map(|current| current.into_kv())
    }

    /// 返回上一个元素的引用。
    ///
    /// 如果游标指向 "ghost" 非元素，则返回 `BTreeMap` 的最后一个元素。
    /// 如果它指向 `BTreeMap` 的第一个元素，则返回 `None`。
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn peek_prev(&self) -> Option<(&'a K, &'a V)> {
        let mut prev = self.clone();
        prev.move_prev();
        prev.current.as_ref().map(|current| current.into_kv())
    }
}

impl<'a, K, V, A> CursorMut<'a, K, V, A> {
    /// 将游标移动到 `BTreeMap` 的下一个元素。
    ///
    /// 如果游标指向 "ghost" 非元素，那么这会将其移动到 `BTreeMap` 的第一个元素。
    /// 如果它指向 `BTreeMap` 的最后一个元素，那么这会将它移动到 "ghost" 非元素。
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn move_next(&mut self) {
        match self.current.take() {
            None => {
                // SAFETY: root 之前的借用已经结束。
                self.current = unsafe { self.root.reborrow() }.as_mut().and_then(|root| {
                    root.borrow_mut().first_leaf_edge().forget_node_type().right_kv().ok()
                });
            }
            Some(current) => {
                self.current = current.next_leaf_edge().next_kv().ok();
            }
        }
    }

    /// 将游标移动到 `BTreeMap` 的前一个元素。
    ///
    /// 如果游标指向 "ghost" 非元素，那么这会将其移动到 `BTreeMap` 的最后一个元素。
    /// 如果它指向 `BTreeMap` 的第一个元素，那么这会将它移动到 "ghost" 非元素。
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn move_prev(&mut self) {
        match self.current.take() {
            None => {
                // SAFETY: root 之前的借用已经结束。
                self.current = unsafe { self.root.reborrow() }.as_mut().and_then(|root| {
                    root.borrow_mut().last_leaf_edge().forget_node_type().left_kv().ok()
                });
            }
            Some(current) => {
                self.current = current.next_back_leaf_edge().next_back_kv().ok();
            }
        }
    }

    /// 将引用返回到游标当前指向的元素的键。
    ///
    ///
    /// 如果游标当前指向 "ghost" 非元素，则返回 `None`。
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn key(&self) -> Option<&K> {
        self.current.as_ref().map(|current| current.reborrow().into_kv().0)
    }

    /// 将引用返回到游标当前指向的元素的值。
    ///
    ///
    /// 如果游标当前指向 "ghost" 非元素，则返回 `None`。
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn value(&self) -> Option<&V> {
        self.current.as_ref().map(|current| current.reborrow().into_kv().1)
    }

    /// 将引用返回到游标当前指向的元素的键和值。
    ///
    ///
    /// 如果游标当前指向 "ghost" 非元素，则返回 `None`。
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn key_value(&self) -> Option<(&K, &V)> {
        self.current.as_ref().map(|current| current.reborrow().into_kv())
    }

    /// 将可变引用返回到游标当前指向的元素的值。
    ///
    ///
    /// 如果游标当前指向 "ghost" 非元素，则返回 `None`。
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn value_mut(&mut self) -> Option<&mut V> {
        self.current.as_mut().map(|current| current.kv_mut().1)
    }

    /// 返回对键的引用和对游标当前指向的元素的值的可变引用。
    ///
    ///
    /// 如果游标当前指向 "ghost" 非元素，则返回 `None`。
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn key_value_mut(&mut self) -> Option<(&K, &mut V)> {
        self.current.as_mut().map(|current| {
            let (k, v) = current.kv_mut();
            (&*k, v)
        })
    }

    /// 返回对光标当前指向的元素的键的可变引用。
    ///
    /// 如果游标当前指向 "ghost" 非元素，则返回 `None`。
    ///
    /// # Safety
    ///
    /// 这可用于修改密钥，但您必须确保维护 `BTreeMap` 不，变体。
    /// Specifically:
    ///
    /// * 密钥在树中必须保持唯一。
    /// * 键必须保持相对于树中其他元素的排序顺序。
    ///
    ///
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub unsafe fn key_mut_unchecked(&mut self) -> Option<&mut K> {
        self.current.as_mut().map(|current| current.kv_mut().0)
    }

    /// 返回一个引用到下一个元素的键和值。
    ///
    /// 如果游标指向 "ghost" 非元素，则返回 `BTreeMap` 的第一个元素。
    /// 如果它指向 `BTreeMap` 的最后一个元素，则返回 `None`。
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn peek_next(&mut self) -> Option<(&K, &mut V)> {
        let (k, v) = match self.current {
            None => {
                // SAFETY: root 之前的借用已经结束。
                unsafe { self.root.reborrow() }
                    .as_mut()?
                    .borrow_mut()
                    .first_leaf_edge()
                    .next_kv()
                    .ok()?
                    .into_kv_valmut()
            }
            // SAFETY: 我们不使用它来改变树。
            Some(ref mut current) => {
                unsafe { current.reborrow_mut() }.next_leaf_edge().next_kv().ok()?.into_kv_valmut()
            }
        };
        Some((k, v))
    }

    /// 返回一个引用到前一个元素的键和值。
    ///
    /// 如果游标指向 "ghost" 非元素，则返回 `BTreeMap` 的最后一个元素。
    /// 如果它指向 `BTreeMap` 的第一个元素，则返回 `None`。
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn peek_prev(&mut self) -> Option<(&K, &mut V)> {
        let (k, v) = match self.current.as_mut() {
            None => {
                // SAFETY: root 之前的借用已经结束。
                unsafe { self.root.reborrow() }
                    .as_mut()?
                    .borrow_mut()
                    .last_leaf_edge()
                    .next_back_kv()
                    .ok()?
                    .into_kv_valmut()
            }
            Some(current) => {
                // SAFETY: 我们不使用它来改变树。
                unsafe { current.reborrow_mut() }
                    .next_back_leaf_edge()
                    .next_back_kv()
                    .ok()?
                    .into_kv_valmut()
            }
        };
        Some((k, v))
    }

    /// 返回指向当前元素的只读游标。
    ///
    /// 返回的 `Cursor` 的生命周期与 `CursorMut` 的生命周期绑定在一起，这意味着它不能超过 `CursorMut` 的生命周期，并且 `CursorMut` 被冻结为 `Cursor` 的生命周期。
    ///
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn as_cursor(&self) -> Cursor<'_, K, V> {
        Cursor {
            // SAFETY: 当游标存在时，树是不变的。
            root: unsafe { self.root.reborrow_shared().as_ref() },
            current: self.current.as_ref().map(|current| current.reborrow()),
        }
    }
}

// 现在树编辑操作
impl<'a, K: Ord, V, A: Allocator + Clone> CursorMut<'a, K, V, A> {
    /// 在当前元素之后将一个新元素插入到 `BTreeMap` 中。
    ///
    /// 如果游标指向 "ghost" 非元素，则新元素将插入到 `BTreeMap` 的前面。
    ///
    ///
    /// # Safety
    ///
    /// 您必须确保维护 `BTreeMap` 不，变体。
    /// Specifically:
    ///
    /// * 新插入的元素的键在树中必须是唯一的。
    /// * 树中的所有键必须保持排序顺序。
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub unsafe fn insert_after_unchecked(&mut self, key: K, value: V) {
        let edge = match self.current.take() {
            None => {
                // SAFETY: 我们对这棵树没有其他的引用。
                match unsafe { self.root.reborrow() } {
                    root @ None => {
                        // 树是空的，分配一个新的根。
                        let mut node = NodeRef::new_leaf(self.alloc.clone());
                        node.borrow_mut().push(key, value);
                        *root = Some(node.forget_type());
                        *self.length += 1;
                        return;
                    }
                    Some(root) => root.borrow_mut().first_leaf_edge(),
                }
            }
            Some(current) => current.next_leaf_edge(),
        };

        let handle = edge.insert_recursing(key, value, self.alloc.clone(), |ins| {
            drop(ins.left);
            // SAFETY: 新插入值的句柄总是在叶子节点上，因此添加新的根节点不会使其无效。
            //
            let root = unsafe { self.root.reborrow().as_mut().unwrap() };
            root.push_internal_level(self.alloc.clone()).push(ins.kv.0, ins.kv.1, ins.right)
        });
        self.current = handle.left_edge().next_back_kv().ok();
        *self.length += 1;
    }

    /// 在当前元素之前将一个新元素插入到 `BTreeMap` 中。
    ///
    /// 如果游标指向 "ghost" 非元素，则新元素将插入到 `BTreeMap` 的末尾。
    ///
    ///
    /// # Safety
    ///
    /// 您必须确保维护 `BTreeMap` 不，变体。
    /// Specifically:
    ///
    /// * 新插入的元素的键在树中必须是唯一的。
    /// * 树中的所有键必须保持排序顺序。
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub unsafe fn insert_before_unchecked(&mut self, key: K, value: V) {
        let edge = match self.current.take() {
            None => {
                // SAFETY: 我们对这棵树没有其他的引用。
                match unsafe { self.root.reborrow() } {
                    root @ None => {
                        // 树是空的，分配一个新的根。
                        let mut node = NodeRef::new_leaf(self.alloc.clone());
                        node.borrow_mut().push(key, value);
                        *root = Some(node.forget_type());
                        *self.length += 1;
                        return;
                    }
                    Some(root) => root.borrow_mut().last_leaf_edge(),
                }
            }
            Some(current) => current.next_back_leaf_edge(),
        };

        let handle = edge.insert_recursing(key, value, self.alloc.clone(), |ins| {
            drop(ins.left);
            // SAFETY: 新插入值的句柄总是在叶子节点上，因此添加新的根节点不会使其无效。
            //
            let root = unsafe { self.root.reborrow().as_mut().unwrap() };
            root.push_internal_level(self.alloc.clone()).push(ins.kv.0, ins.kv.1, ins.right)
        });
        self.current = handle.right_edge().next_kv().ok();
        *self.length += 1;
    }

    /// 在当前元素之后将一个新元素插入到 `BTreeMap` 中。
    ///
    /// 如果游标指向 "ghost" 非元素，则新元素将插入到 `BTreeMap` 的前面。
    ///
    ///
    /// # Panics
    ///
    /// 如果满足以下条件，则此函数 panics：
    /// - 给定键比较小于或等于当前元素 (如果有)。
    /// - 给定的键比较大于或等于下一个元素 (如果有)。
    ///
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn insert_after(&mut self, key: K, value: V) {
        if let Some(current) = self.key() {
            if &key <= current {
                panic!("key must be ordered above the current element");
            }
        }
        if let Some((next, _)) = self.peek_next() {
            if &key >= next {
                panic!("key must be ordered below the next element");
            }
        }
        unsafe {
            self.insert_after_unchecked(key, value);
        }
    }

    /// 在当前元素之前将一个新元素插入到 `BTreeMap` 中。
    ///
    /// 如果游标指向 "ghost" 非元素，则新元素将插入到 `BTreeMap` 的末尾。
    ///
    ///
    /// # Panics
    ///
    /// 如果满足以下条件，则此函数 panics：
    /// - 给定键比较大于或等于当前元素 (如果有)。
    /// - 给定的键比较小于或等于前一个元素 (如果有)。
    ///
    ///
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn insert_before(&mut self, key: K, value: V) {
        if let Some(current) = self.key() {
            if &key >= current {
                panic!("key must be ordered below the current element");
            }
        }
        if let Some((prev, _)) = self.peek_prev() {
            if &key <= prev {
                panic!("key must be ordered above the previous element");
            }
        }
        unsafe {
            self.insert_before_unchecked(key, value);
        }
    }

    /// 从 `BTreeMap` 中移除当前元素。
    ///
    /// 被移除的元素被返回，游标移动到 `BTreeMap` 中的下一个元素。
    ///
    ///
    /// 如果游标当前指向 "ghost" 非元素，则不删除任何元素，并返回 `None`。
    /// 在这种情况下，游标不会移动。
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn remove_current(&mut self) -> Option<(K, V)> {
        let current = self.current.take()?;
        let mut emptied_internal_root = false;
        let (kv, pos) =
            current.remove_kv_tracking(|| emptied_internal_root = true, self.alloc.clone());
        self.current = pos.next_kv().ok();
        *self.length -= 1;
        if emptied_internal_root {
            // SAFETY: 这是安全的，因为 current 不指向现在为空的根节点。
            //
            let root = unsafe { self.root.reborrow().as_mut().unwrap() };
            root.pop_internal_level(self.alloc.clone());
        }
        Some(kv)
    }

    /// 从 `BTreeMap` 中移除当前元素。
    ///
    /// 被移除的元素被返回，游标移动到 `BTreeMap` 中的前一个元素。
    ///
    ///
    /// 如果游标当前指向 "ghost" 非元素，则不删除任何元素，并返回 `None`。
    /// 在这种情况下，游标不会移动。
    #[unstable(feature = "btree_cursors", issue = "107540")]
    pub fn remove_current_and_move_back(&mut self) -> Option<(K, V)> {
        let current = self.current.take()?;
        let mut emptied_internal_root = false;
        let (kv, pos) =
            current.remove_kv_tracking(|| emptied_internal_root = true, self.alloc.clone());
        self.current = pos.next_back_kv().ok();
        *self.length -= 1;
        if emptied_internal_root {
            // SAFETY: 这是安全的，因为 current 不指向现在为空的根节点。
            //
            let root = unsafe { self.root.reborrow().as_mut().unwrap() };
            root.pop_internal_level(self.alloc.clone());
        }
        Some(kv)
    }
}

#[cfg(test)]
mod tests;