Skip to content

Commit 170a28a

Browse files
ripytideripytide
committed
improve btree_cursors functions documentation
1 parent 90aaf18 commit 170a28a

File tree

1 file changed

+130
-87
lines changed
  • alloc/src/collections/btree

1 file changed

+130
-87
lines changed

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

+130-87
Original file line numberDiff line numberDiff line change
@@ -2522,10 +2522,17 @@ impl<K, V, A: Allocator + Clone> BTreeMap<K, V, A> {
25222522
self.len() == 0
25232523
}
25242524

2525-
/// Returns a [`Cursor`] pointing to the first gap above the given bound.
2525+
/// Returns a [`Cursor`] pointing at the gap before the smallest key
2526+
/// greater than the given bound.
25262527
///
2527-
/// Passing [`Bound::Unbounded`] will return a cursor pointing to the start
2528-
/// of the map.
2528+
/// Passing [`Bound::Included(x)`] will return a cursor pointing to the
2529+
/// gap before the smallest key greater than or equal to `x`.
2530+
///
2531+
/// Passing [`Bound::Excluded(x)`] will return a cursor pointing to the
2532+
/// gap before the smallest key greater than `x`.
2533+
///
2534+
/// Passing [`Bound::Unbounded`] will return a cursor pointing to the
2535+
/// gap before the smallest key in the map.
25292536
///
25302537
/// # Examples
25312538
///
@@ -2535,17 +2542,24 @@ impl<K, V, A: Allocator + Clone> BTreeMap<K, V, A> {
25352542
/// use std::collections::BTreeMap;
25362543
/// use std::ops::Bound;
25372544
///
2538-
/// let mut a = BTreeMap::new();
2539-
/// a.insert(1, "a");
2540-
/// a.insert(2, "b");
2541-
/// a.insert(3, "c");
2542-
/// a.insert(4, "d");
2543-
/// let cursor = a.lower_bound(Bound::Included(&2));
2545+
/// let map = BTreeMap::from([
2546+
/// (1, "a"),
2547+
/// (2, "b"),
2548+
/// (3, "c"),
2549+
/// (4, "d"),
2550+
/// ]);
2551+
///
2552+
/// let cursor = map.lower_bound(Bound::Included(&2));
25442553
/// assert_eq!(cursor.peek_prev(), Some((&1, &"a")));
25452554
/// assert_eq!(cursor.peek_next(), Some((&2, &"b")));
2546-
/// let cursor = a.lower_bound(Bound::Excluded(&2));
2555+
///
2556+
/// let cursor = map.lower_bound(Bound::Excluded(&2));
25472557
/// assert_eq!(cursor.peek_prev(), Some((&2, &"b")));
25482558
/// assert_eq!(cursor.peek_next(), Some((&3, &"c")));
2559+
///
2560+
/// let cursor = map.lower_bound(Bound::Unbounded);
2561+
/// assert_eq!(cursor.peek_prev(), None);
2562+
/// assert_eq!(cursor.peek_next(), Some((&1, &"a")));
25492563
/// ```
25502564
#[unstable(feature = "btree_cursors", issue = "107540")]
25512565
pub fn lower_bound<Q: ?Sized>(&self, bound: Bound<&Q>) -> Cursor<'_, K, V>
@@ -2561,11 +2575,17 @@ impl<K, V, A: Allocator + Clone> BTreeMap<K, V, A> {
25612575
Cursor { current: Some(edge), root: self.root.as_ref() }
25622576
}
25632577

2564-
/// Returns a [`CursorMut`] pointing to the first gap above the given bound.
2578+
/// Returns a [`CursorMut`] pointing at the gap before the smallest key
2579+
/// greater than the given bound.
25652580
///
2581+
/// Passing [`Bound::Included(x)`] will return a cursor pointing to the
2582+
/// gap before the smallest key greater than or equal to `x`.
25662583
///
2567-
/// Passing [`Bound::Unbounded`] will return a cursor pointing to the start
2568-
/// of the map.
2584+
/// Passing [`Bound::Excluded(x)`] will return a cursor pointing to the
2585+
/// gap before the smallest key greater than `x`.
2586+
///
2587+
/// Passing [`Bound::Unbounded`] will return a cursor pointing to the
2588+
/// gap before the smallest key in the map.
25692589
///
25702590
/// # Examples
25712591
///
@@ -2575,17 +2595,24 @@ impl<K, V, A: Allocator + Clone> BTreeMap<K, V, A> {
25752595
/// use std::collections::BTreeMap;
25762596
/// use std::ops::Bound;
25772597
///
2578-
/// let mut a = BTreeMap::new();
2579-
/// a.insert(1, "a");
2580-
/// a.insert(2, "b");
2581-
/// a.insert(3, "c");
2582-
/// a.insert(4, "d");
2583-
/// let mut cursor = a.lower_bound_mut(Bound::Included(&2));
2598+
/// let mut map = BTreeMap::from([
2599+
/// (1, "a"),
2600+
/// (2, "b"),
2601+
/// (3, "c"),
2602+
/// (4, "d"),
2603+
/// ]);
2604+
///
2605+
/// let mut cursor = map.lower_bound_mut(Bound::Included(&2));
25842606
/// assert_eq!(cursor.peek_prev(), Some((&1, &mut "a")));
25852607
/// assert_eq!(cursor.peek_next(), Some((&2, &mut "b")));
2586-
/// let mut cursor = a.lower_bound_mut(Bound::Excluded(&2));
2608+
///
2609+
/// let mut cursor = map.lower_bound_mut(Bound::Excluded(&2));
25872610
/// assert_eq!(cursor.peek_prev(), Some((&2, &mut "b")));
25882611
/// assert_eq!(cursor.peek_next(), Some((&3, &mut "c")));
2612+
///
2613+
/// let mut cursor = map.lower_bound_mut(Bound::Unbounded);
2614+
/// assert_eq!(cursor.peek_prev(), None);
2615+
/// assert_eq!(cursor.peek_next(), Some((&1, &mut "a")));
25892616
/// ```
25902617
#[unstable(feature = "btree_cursors", issue = "107540")]
25912618
pub fn lower_bound_mut<Q: ?Sized>(&mut self, bound: Bound<&Q>) -> CursorMut<'_, K, V, A>
@@ -2618,10 +2645,17 @@ impl<K, V, A: Allocator + Clone> BTreeMap<K, V, A> {
26182645
}
26192646
}
26202647

2621-
/// Returns a [`Cursor`] pointing at the last gap below the given bound.
2648+
/// Returns a [`Cursor`] pointing at the gap after the greatest key
2649+
/// smaller than the given bound.
26222650
///
2623-
/// Passing [`Bound::Unbounded`] will return a cursor pointing to the end
2624-
/// of the map.
2651+
/// Passing [`Bound::Included(x)`] will return a cursor pointing to the
2652+
/// gap after the greatest key smaller than or equal to `x`.
2653+
///
2654+
/// Passing [`Bound::Excluded(x)`] will return a cursor pointing to the
2655+
/// gap after the greatest key smaller than `x`.
2656+
///
2657+
/// Passing [`Bound::Unbounded`] will return a cursor pointing to the
2658+
/// gap after the greatest key in the map.
26252659
///
26262660
/// # Examples
26272661
///
@@ -2631,17 +2665,24 @@ impl<K, V, A: Allocator + Clone> BTreeMap<K, V, A> {
26312665
/// use std::collections::BTreeMap;
26322666
/// use std::ops::Bound;
26332667
///
2634-
/// let mut a = BTreeMap::new();
2635-
/// a.insert(1, "a");
2636-
/// a.insert(2, "b");
2637-
/// a.insert(3, "c");
2638-
/// a.insert(4, "d");
2639-
/// let cursor = a.upper_bound(Bound::Included(&3));
2640-
/// assert_eq!(cursor.peek_prev(), Some((&3, &"c")));
2641-
/// assert_eq!(cursor.peek_next(), Some((&4, &"d")));
2642-
/// let cursor = a.upper_bound(Bound::Excluded(&3));
2668+
/// let map = BTreeMap::from([
2669+
/// (1, "a"),
2670+
/// (2, "b"),
2671+
/// (3, "c"),
2672+
/// (4, "d"),
2673+
/// ]);
2674+
///
2675+
/// let cursor = map.upper_bound(Bound::Included(&3));
2676+
/// assert_eq!(cursor.peek_prev(), Some((&3, &"d")));
2677+
/// assert_eq!(cursor.peek_next(), Some((&4, &"c")));
2678+
///
2679+
/// let cursor = map.upper_bound(Bound::Excluded(&3));
26432680
/// assert_eq!(cursor.peek_prev(), Some((&2, &"b")));
26442681
/// assert_eq!(cursor.peek_next(), Some((&3, &"c")));
2682+
///
2683+
/// let cursor = map.upper_bound(Bound::Unbounded);
2684+
/// assert_eq!(cursor.peek_prev(), Some((&4, &"d")));
2685+
/// assert_eq!(cursor.peek_next(), None);
26452686
/// ```
26462687
#[unstable(feature = "btree_cursors", issue = "107540")]
26472688
pub fn upper_bound<Q: ?Sized>(&self, bound: Bound<&Q>) -> Cursor<'_, K, V>
@@ -2657,10 +2698,17 @@ impl<K, V, A: Allocator + Clone> BTreeMap<K, V, A> {
26572698
Cursor { current: Some(edge), root: self.root.as_ref() }
26582699
}
26592700

2660-
/// Returns a [`CursorMut`] pointing at the last gap below the given bound.
2701+
/// Returns a [`CursorMut`] pointing at the gap after the greatest key
2702+
/// smaller than the given bound.
26612703
///
2662-
/// Passing [`Bound::Unbounded`] will return a cursor pointing to the end
2663-
/// of the map.
2704+
/// Passing [`Bound::Included(x)`] will return a cursor pointing to the
2705+
/// gap after the greatest key smaller than or equal to `x`.
2706+
///
2707+
/// Passing [`Bound::Excluded(x)`] will return a cursor pointing to the
2708+
/// gap after the greatest key smaller than `x`.
2709+
///
2710+
/// Passing [`Bound::Unbounded`] will return a cursor pointing to the
2711+
/// gap after the greatest key in the map.
26642712
///
26652713
/// # Examples
26662714
///
@@ -2670,17 +2718,24 @@ impl<K, V, A: Allocator + Clone> BTreeMap<K, V, A> {
26702718
/// use std::collections::BTreeMap;
26712719
/// use std::ops::Bound;
26722720
///
2673-
/// let mut a = BTreeMap::new();
2674-
/// a.insert(1, "a");
2675-
/// a.insert(2, "b");
2676-
/// a.insert(3, "c");
2677-
/// a.insert(4, "d");
2678-
/// let mut cursor = a.upper_bound_mut(Bound::Included(&3));
2721+
/// let mut map = BTreeMap::from([
2722+
/// (1, "a"),
2723+
/// (2, "b"),
2724+
/// (3, "c"),
2725+
/// (4, "d"),
2726+
/// ]);
2727+
///
2728+
/// let mut cursor = map.upper_bound_mut(Bound::Included(&3));
26792729
/// assert_eq!(cursor.peek_prev(), Some((&3, &mut "c")));
26802730
/// assert_eq!(cursor.peek_next(), Some((&4, &mut "d")));
2681-
/// let mut cursor = a.upper_bound_mut(Bound::Excluded(&3));
2731+
///
2732+
/// let mut cursor = map.upper_bound_mut(Bound::Excluded(&3));
26822733
/// assert_eq!(cursor.peek_prev(), Some((&2, &mut "b")));
26832734
/// assert_eq!(cursor.peek_next(), Some((&3, &mut "c")));
2735+
///
2736+
/// let mut cursor = map.upper_bound_mut(Bound::Unbounded);
2737+
/// assert_eq!(cursor.peek_prev(), Some((&4, &mut "d")));
2738+
/// assert_eq!(cursor.peek_next(), None);
26842739
/// ```
26852740
#[unstable(feature = "btree_cursors", issue = "107540")]
26862741
pub fn upper_bound_mut<Q: ?Sized>(&mut self, bound: Bound<&Q>) -> CursorMut<'_, K, V, A>
@@ -3040,8 +3095,8 @@ impl<'a, K, V, A> CursorMutKey<'a, K, V, A> {
30403095

30413096
// Now the tree editing operations
30423097
impl<'a, K: Ord, V, A: Allocator + Clone> CursorMutKey<'a, K, V, A> {
3043-
/// Inserts a new element into the `BTreeMap` in the gap that the
3044-
/// `CursorMutKey` is currently pointing to.
3098+
/// Inserts a new key-value pair into the map in the gap that the
3099+
/// cursor is currently pointing to.
30453100
///
30463101
/// After the insertion the cursor will be pointing at the gap before the
30473102
/// newly inserted element.
@@ -3083,8 +3138,8 @@ impl<'a, K: Ord, V, A: Allocator + Clone> CursorMutKey<'a, K, V, A> {
30833138
*self.length += 1;
30843139
}
30853140

3086-
/// Inserts a new element into the `BTreeMap` in the gap that the
3087-
/// `CursorMutKey` is currently pointing to.
3141+
/// Inserts a new key-value pair into the map in the gap that the
3142+
/// cursor is currently pointing to.
30883143
///
30893144
/// After the insertion the cursor will be pointing at the gap after the
30903145
/// newly inserted element.
@@ -3129,19 +3184,16 @@ impl<'a, K: Ord, V, A: Allocator + Clone> CursorMutKey<'a, K, V, A> {
31293184
*self.length += 1;
31303185
}
31313186

3132-
/// Inserts a new element into the `BTreeMap` in the gap that the
3133-
/// `CursorMutKey` is currently pointing to.
3187+
/// Inserts a new key-value pair into the map in the gap that the
3188+
/// cursor is currently pointing to.
31343189
///
31353190
/// After the insertion the cursor will be pointing at the gap before the
31363191
/// newly inserted element.
31373192
///
3138-
/// # Panics
3139-
///
3140-
/// This function panics if:
3141-
/// - the given key compares less than or equal to the current element (if
3142-
/// any).
3143-
/// - the given key compares greater than or equal to the next element (if
3144-
/// any).
3193+
/// If the inserted key is not greater than the key before the cursor
3194+
/// (if any), or if it not less than the key after the cursor (if any),
3195+
/// then an [`UnorderedKeyError`] is returned since this would
3196+
/// invalidate the [`Ord`] invariant between the keys of the map.
31453197
#[unstable(feature = "btree_cursors", issue = "107540")]
31463198
pub fn insert_after(&mut self, key: K, value: V) -> Result<(), UnorderedKeyError> {
31473199
if let Some((prev, _)) = self.peek_prev() {
@@ -3160,19 +3212,16 @@ impl<'a, K: Ord, V, A: Allocator + Clone> CursorMutKey<'a, K, V, A> {
31603212
Ok(())
31613213
}
31623214

3163-
/// Inserts a new element into the `BTreeMap` in the gap that the
3164-
/// `CursorMutKey` is currently pointing to.
3215+
/// Inserts a new key-value pair into the map in the gap that the
3216+
/// cursor is currently pointing to.
31653217
///
31663218
/// After the insertion the cursor will be pointing at the gap after the
31673219
/// newly inserted element.
31683220
///
3169-
/// # Panics
3170-
///
3171-
/// This function panics if:
3172-
/// - the given key compares greater than or equal to the current element
3173-
/// (if any).
3174-
/// - the given key compares less than or equal to the previous element (if
3175-
/// any).
3221+
/// If the inserted key is not greater than the key before the cursor
3222+
/// (if any), or if it not less than the key after the cursor (if any),
3223+
/// then an [`UnorderedKeyError`] is returned since this would
3224+
/// invalidate the [`Ord`] invariant between the keys of the map.
31763225
#[unstable(feature = "btree_cursors", issue = "107540")]
31773226
pub fn insert_before(&mut self, key: K, value: V) -> Result<(), UnorderedKeyError> {
31783227
if let Some((prev, _)) = self.peek_prev() {
@@ -3239,10 +3288,10 @@ impl<'a, K: Ord, V, A: Allocator + Clone> CursorMutKey<'a, K, V, A> {
32393288
}
32403289

32413290
impl<'a, K: Ord, V, A: Allocator + Clone> CursorMut<'a, K, V, A> {
3242-
/// Inserts a new element into the `BTreeMap` in the gap that the
3243-
/// `CursorMut` is currently pointing to.
3291+
/// Inserts a new key-value pair into the map in the gap that the
3292+
/// cursor is currently pointing to.
32443293
///
3245-
/// After the insertion the cursor will be pointing at the gap before the
3294+
/// After the insertion the cursor will be pointing at the gap after the
32463295
/// newly inserted element.
32473296
///
32483297
/// # Safety
@@ -3257,8 +3306,8 @@ impl<'a, K: Ord, V, A: Allocator + Clone> CursorMut<'a, K, V, A> {
32573306
unsafe { self.inner.insert_after_unchecked(key, value) }
32583307
}
32593308

3260-
/// Inserts a new element into the `BTreeMap` in the gap that the
3261-
/// `CursorMut` is currently pointing to.
3309+
/// Inserts a new key-value pair into the map in the gap that the
3310+
/// cursor is currently pointing to.
32623311
///
32633312
/// After the insertion the cursor will be pointing at the gap after the
32643313
/// newly inserted element.
@@ -3275,37 +3324,31 @@ impl<'a, K: Ord, V, A: Allocator + Clone> CursorMut<'a, K, V, A> {
32753324
unsafe { self.inner.insert_before_unchecked(key, value) }
32763325
}
32773326

3278-
/// Inserts a new element into the `BTreeMap` in the gap that the
3279-
/// `CursorMut` is currently pointing to.
3327+
/// Inserts a new key-value pair into the map in the gap that the
3328+
/// cursor is currently pointing to.
32803329
///
32813330
/// After the insertion the cursor will be pointing at the gap before the
32823331
/// newly inserted element.
32833332
///
3284-
/// # Panics
3285-
///
3286-
/// This function panics if:
3287-
/// - the given key compares less than or equal to the current element (if
3288-
/// any).
3289-
/// - the given key compares greater than or equal to the next element (if
3290-
/// any).
3333+
/// If the inserted key is not greater than the key before the cursor
3334+
/// (if any), or if it not less than the key after the cursor (if any),
3335+
/// then an [`UnorderedKeyError`] is returned since this would
3336+
/// invalidate the [`Ord`] invariant between the keys of the map.
32913337
#[unstable(feature = "btree_cursors", issue = "107540")]
32923338
pub fn insert_after(&mut self, key: K, value: V) -> Result<(), UnorderedKeyError> {
32933339
self.inner.insert_after(key, value)
32943340
}
32953341

3296-
/// Inserts a new element into the `BTreeMap` in the gap that the
3297-
/// `CursorMut` is currently pointing to.
3342+
/// Inserts a new key-value pair into the map in the gap that the
3343+
/// cursor is currently pointing to.
32983344
///
32993345
/// After the insertion the cursor will be pointing at the gap after the
33003346
/// newly inserted element.
33013347
///
3302-
/// # Panics
3303-
///
3304-
/// This function panics if:
3305-
/// - the given key compares greater than or equal to the current element
3306-
/// (if any).
3307-
/// - the given key compares less than or equal to the previous element (if
3308-
/// any).
3348+
/// If the inserted key is not greater than the key before the cursor
3349+
/// (if any), or if it not less than the key after the cursor (if any),
3350+
/// then an [`UnorderedKeyError`] is returned since this would
3351+
/// invalidate the [`Ord`] invariant between the keys of the map.
33093352
#[unstable(feature = "btree_cursors", issue = "107540")]
33103353
pub fn insert_before(&mut self, key: K, value: V) -> Result<(), UnorderedKeyError> {
33113354
self.inner.insert_before(key, value)

0 commit comments

Comments
 (0)