Rename first*/last* BTree{Set,Map} methods to min*/max*

Note: `BTreeSet::{first,last}` are renamed to `{get_min,get_max}` to
avoid conflicts with `Ord::{min,max}`.

Author: WaffleLapkin

library/alloc/benches/btree/map.rs

@@ -227,17 +227,17 @@ pub fn iteration_mut_100000(b: &mut Bencher) {
     bench_iteration_mut(b, 100000);
 }
 
-fn bench_first_and_last_nightly(b: &mut Bencher, size: i32) {
+fn bench_min_and_max_nightly(b: &mut Bencher, size: i32) {
     let map: BTreeMap<_, _> = (0..size).map(|i| (i, i)).collect();
     b.iter(|| {
         for _ in 0..10 {
-            black_box(map.first_key_value());
-            black_box(map.last_key_value());
+            black_box(map.min_key_value());
+            black_box(map.max_key_value());
         }
     });
 }
 
-fn bench_first_and_last_stable(b: &mut Bencher, size: i32) {
+fn bench_min_and_max_stable(b: &mut Bencher, size: i32) {
     let map: BTreeMap<_, _> = (0..size).map(|i| (i, i)).collect();
     b.iter(|| {
         for _ in 0..10 {
@@ -248,33 +248,33 @@ fn bench_first_and_last_stable(b: &mut Bencher, size: i32) {
 }
 
 #[bench]
-pub fn first_and_last_0_nightly(b: &mut Bencher) {
-    bench_first_and_last_nightly(b, 0);
+pub fn min_and_max_0_nightly(b: &mut Bencher) {
+    bench_min_and_max_nightly(b, 0);
 }
 
 #[bench]
-pub fn first_and_last_0_stable(b: &mut Bencher) {
-    bench_first_and_last_stable(b, 0);
+pub fn min_and_max_0_stable(b: &mut Bencher) {
+    bench_min_and_max_stable(b, 0);
 }
 
 #[bench]
-pub fn first_and_last_100_nightly(b: &mut Bencher) {
-    bench_first_and_last_nightly(b, 100);
+pub fn min_and_max_100_nightly(b: &mut Bencher) {
+    bench_min_and_max_nightly(b, 100);
 }
 
 #[bench]
-pub fn first_and_last_100_stable(b: &mut Bencher) {
-    bench_first_and_last_stable(b, 100);
+pub fn min_and_max_100_stable(b: &mut Bencher) {
+    bench_min_and_max_stable(b, 100);
 }
 
 #[bench]
-pub fn first_and_last_10k_nightly(b: &mut Bencher) {
-    bench_first_and_last_nightly(b, 10_000);
+pub fn min_and_max_10k_nightly(b: &mut Bencher) {
+    bench_min_and_max_nightly(b, 10_000);
 }
 
 #[bench]
-pub fn first_and_last_10k_stable(b: &mut Bencher) {
-    bench_first_and_last_stable(b, 10_000);
+pub fn min_and_max_10k_stable(b: &mut Bencher) {
+    bench_min_and_max_stable(b, 10_000);
 }
 
 const BENCH_RANGE_SIZE: i32 = 145;
@@ -410,7 +410,7 @@ pub fn clone_slim_100_and_pop_all(b: &mut Bencher) {
     let src = slim_map(100);
     b.iter(|| {
         let mut map = src.clone();
-        while map.pop_first().is_some() {}
+        while map.pop_min().is_some() {}
         map
     });
 }
@@ -481,7 +481,7 @@ pub fn clone_slim_10k_and_pop_all(b: &mut Bencher) {
     let src = slim_map(10_000);
     b.iter(|| {
         let mut map = src.clone();
-        while map.pop_first().is_some() {}
+        while map.pop_min().is_some() {}
         map
     });
 }
@@ -552,7 +552,7 @@ pub fn clone_fat_val_100_and_pop_all(b: &mut Bencher) {
     let src = fat_val_map(100);
     b.iter(|| {
         let mut map = src.clone();
-        while map.pop_first().is_some() {}
+        while map.pop_min().is_some() {}
         map
     });
 }

library/alloc/benches/btree/set.rs

@@ -93,7 +93,7 @@ pub fn clone_100_and_pop_all(b: &mut Bencher) {
     let src = slim_set(100);
     b.iter(|| {
         let mut set = src.clone();
-        while set.pop_first().is_some() {}
+        while set.pop_min().is_some() {}
         set
     });
 }
@@ -164,7 +164,7 @@ pub fn clone_10k_and_pop_all(b: &mut Bencher) {
     let src = slim_set(10_000);
     b.iter(|| {
         let mut set = src.clone();
-        while set.pop_first().is_some() {}
+        while set.pop_min().is_some() {}
         set
     });
 }

library/alloc/src/collections/btree/map.rs

@@ -600,8 +600,7 @@ impl<K, V> BTreeMap<K, V> {
         }
     }
 
-    /// Returns the first key-value pair in the map.
-    /// The key in this pair is the minimum key in the map.
+    /// Returns the key-value pair with the minimum key in the map.
     ///
     /// # Examples
     ///
@@ -612,22 +611,21 @@ impl<K, V> BTreeMap<K, V> {
     /// use std::collections::BTreeMap;
     ///
     /// let mut map = BTreeMap::new();
-    /// assert_eq!(map.first_key_value(), None);
+    /// assert_eq!(map.min_key_value(), None);
     /// map.insert(1, "b");
     /// map.insert(2, "a");
-    /// assert_eq!(map.first_key_value(), Some((&1, &"b")));
+    /// assert_eq!(map.min_key_value(), Some((&1, &"b")));
     /// ```
     #[unstable(feature = "map_first_last", issue = "62924")]
-    pub fn first_key_value(&self) -> Option<(&K, &V)>
+    pub fn min_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)
     }
 
-    /// Returns the first entry in the map for in-place manipulation.
-    /// The key of this entry is the minimum key in the map.
+    /// Returns the entry with the minimum key in the map for in-place manipulation.
     ///
     /// # Examples
     ///
@@ -638,16 +636,16 @@ impl<K, V> BTreeMap<K, V> {
     /// let mut map = BTreeMap::new();
     /// map.insert(1, "a");
     /// map.insert(2, "b");
-    /// if let Some(mut entry) = map.first_entry() {
+    /// if let Some(mut entry) = map.min_entry() {
     ///     if *entry.key() > 0 {
-    ///         entry.insert("first");
+    ///         entry.insert("min");
     ///     }
     /// }
-    /// assert_eq!(*map.get(&1).unwrap(), "first");
+    /// assert_eq!(*map.get(&1).unwrap(), "min");
     /// assert_eq!(*map.get(&2).unwrap(), "b");
     /// ```
     #[unstable(feature = "map_first_last", issue = "62924")]
-    pub fn first_entry(&mut self) -> Option<OccupiedEntry<'_, K, V>>
+    pub fn min_entry(&mut self) -> Option<OccupiedEntry<'_, K, V>>
     where
         K: Ord,
     {
@@ -657,8 +655,7 @@ impl<K, V> BTreeMap<K, V> {
         Some(OccupiedEntry { handle: kv.forget_node_type(), dormant_map, _marker: PhantomData })
     }
 
-    /// Removes and returns the first element in the map.
-    /// The key of this element is the minimum key that was in the map.
+    /// Removes and returns the key-value pair with the minimum key in the map.
     ///
     /// # Examples
     ///
@@ -671,21 +668,21 @@ impl<K, V> BTreeMap<K, V> {
     /// let mut map = BTreeMap::new();
     /// map.insert(1, "a");
     /// map.insert(2, "b");
-    /// while let Some((key, _val)) = map.pop_first() {
+    /// while let Some((key, _val)) = map.pop_min() {
     ///     assert!(map.iter().all(|(k, _v)| *k > key));
     /// }
     /// assert!(map.is_empty());
     /// ```
     #[unstable(feature = "map_first_last", issue = "62924")]
-    pub fn pop_first(&mut self) -> Option<(K, V)>
+    pub fn pop_min(&mut self) -> Option<(K, V)>
     where
         K: Ord,
     {
-        self.first_entry().map(|entry| entry.remove_entry())
+        self.min_entry().map(|entry| entry.remove_entry())
     }
 
-    /// Returns the last key-value pair in the map.
-    /// The key in this pair is the maximum key in the map.
+    /// Returns the key-value pair with the maximum key in the
+    /// map. The key in this pair is the maximum key in the map.
     ///
     /// # Examples
     ///
@@ -698,19 +695,18 @@ impl<K, V> BTreeMap<K, V> {
     /// let mut map = BTreeMap::new();
     /// map.insert(1, "b");
     /// map.insert(2, "a");
-    /// assert_eq!(map.last_key_value(), Some((&2, &"a")));
+    /// assert_eq!(map.max_key_value(), Some((&2, &"a")));
     /// ```
     #[unstable(feature = "map_first_last", issue = "62924")]
-    pub fn last_key_value(&self) -> Option<(&K, &V)>
+    pub fn max_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)
     }
 
-    /// Returns the last entry in the map for in-place manipulation.
-    /// The key of this entry is the maximum key in the map.
+    /// Returns the entry with the maximum key in the map for in-place manipulation.
     ///
     /// # Examples
     ///
@@ -721,16 +717,16 @@ impl<K, V> BTreeMap<K, V> {
     /// let mut map = BTreeMap::new();
     /// map.insert(1, "a");
     /// map.insert(2, "b");
-    /// if let Some(mut entry) = map.last_entry() {
+    /// if let Some(mut entry) = map.max_entry() {
     ///     if *entry.key() > 0 {
-    ///         entry.insert("last");
+    ///         entry.insert("max");
     ///     }
     /// }
     /// assert_eq!(*map.get(&1).unwrap(), "a");
-    /// assert_eq!(*map.get(&2).unwrap(), "last");
+    /// assert_eq!(*map.get(&2).unwrap(), "max");
     /// ```
     #[unstable(feature = "map_first_last", issue = "62924")]
-    pub fn last_entry(&mut self) -> Option<OccupiedEntry<'_, K, V>>
+    pub fn max_entry(&mut self) -> Option<OccupiedEntry<'_, K, V>>
     where
         K: Ord,
     {
@@ -740,8 +736,7 @@ impl<K, V> BTreeMap<K, V> {
         Some(OccupiedEntry { handle: kv.forget_node_type(), dormant_map, _marker: PhantomData })
     }
 
-    /// Removes and returns the last element in the map.
-    /// The key of this element is the maximum key that was in the map.
+    /// Removes and returns the key-value pair with the maximum key in the map.
     ///
     /// # Examples
     ///
@@ -754,17 +749,17 @@ impl<K, V> BTreeMap<K, V> {
     /// let mut map = BTreeMap::new();
     /// map.insert(1, "a");
     /// map.insert(2, "b");
-    /// while let Some((key, _val)) = map.pop_last() {
+    /// while let Some((key, _val)) = map.pop_max() {
     ///     assert!(map.iter().all(|(k, _v)| *k < key));
     /// }
     /// assert!(map.is_empty());
     /// ```
     #[unstable(feature = "map_first_last", issue = "62924")]
-    pub fn pop_last(&mut self) -> Option<(K, V)>
+    pub fn pop_max(&mut self) -> Option<(K, V)>
     where
         K: Ord,
     {
-        self.last_entry().map(|entry| entry.remove_entry())
+        self.max_entry().map(|entry| entry.remove_entry())
     }
 
     /// Returns `true` if the map contains a value for the specified key.