Skip to content

Commit 30b9585

Browse files
JustForFun88JustForFun88
committed
Further doc improvement
1 parent 24c1706 commit 30b9585

File tree

1 file changed

+247
-0
lines changed

1 file changed

+247
-0
lines changed

‎src/map.rs

Lines changed: 247 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2680,6 +2680,56 @@ pub struct ValuesMut<'a, K, V> {
26802680
/// See the [`HashMap::raw_entry_mut`] docs for usage examples.
26812681
///
26822682
/// [`HashMap::raw_entry_mut`]: struct.HashMap.html#method.raw_entry_mut
2683+
///
2684+
/// # Examples
2685+
///
2686+
/// ```
2687+
/// use hashbrown::hash_map::{RawEntryBuilderMut, RawEntryMut::Vacant, RawEntryMut::Occupied};
2688+
/// use hashbrown::HashMap;
2689+
/// use core::hash::{BuildHasher, Hash};
2690+
///
2691+
/// let mut map = HashMap::new();
2692+
/// map.extend([(1, 11), (2, 12), (3, 13), (4, 14), (5, 15), (6, 16)]);
2693+
/// assert_eq!(map.len(), 6);
2694+
///
2695+
/// fn compute_hash<K: Hash + ?Sized, S: BuildHasher>(hash_builder: &S, key: &K) -> u64 {
2696+
/// use core::hash::Hasher;
2697+
/// let mut state = hash_builder.build_hasher();
2698+
/// key.hash(&mut state);
2699+
/// state.finish()
2700+
/// }
2701+
///
2702+
/// let builder: RawEntryBuilderMut<_, _, _> = map.raw_entry_mut();
2703+
///
2704+
/// // Existing key
2705+
/// match builder.from_key(&6) {
2706+
/// Vacant(_) => unreachable!(),
2707+
/// Occupied(view) => assert_eq!(view.get(), &16),
2708+
/// }
2709+
///
2710+
/// for key in 0..12 {
2711+
/// let hash = compute_hash(map.hasher(), &key);
2712+
/// let value = map.get(&key).cloned();
2713+
/// let key_value = value.as_ref().map(|v| (&key, v));
2714+
///
2715+
/// println!("Key: {} and value: {:?}", key, value);
2716+
///
2717+
/// match map.raw_entry_mut().from_key(&key) {
2718+
/// Occupied(mut o) => assert_eq!(Some(o.get_key_value()), key_value),
2719+
/// Vacant(_) => assert_eq!(value, None),
2720+
/// }
2721+
/// match map.raw_entry_mut().from_key_hashed_nocheck(hash, &key) {
2722+
/// Occupied(mut o) => assert_eq!(Some(o.get_key_value()), key_value),
2723+
/// Vacant(_) => assert_eq!(value, None),
2724+
/// }
2725+
/// match map.raw_entry_mut().from_hash(hash, |q| *q == key) {
2726+
/// Occupied(mut o) => assert_eq!(Some(o.get_key_value()), key_value),
2727+
/// Vacant(_) => assert_eq!(value, None),
2728+
/// }
2729+
/// }
2730+
///
2731+
/// assert_eq!(map.len(), 6);
2732+
/// ```
26832733
pub struct RawEntryBuilderMut<'a, K, V, S, A: Allocator + Clone = Global> {
26842734
map: &'a mut HashMap<K, V, S, A>,
26852735
}
@@ -2695,17 +2745,170 @@ pub struct RawEntryBuilderMut<'a, K, V, S, A: Allocator + Clone = Global> {
26952745
/// [`Entry`]: enum.Entry.html
26962746
/// [`raw_entry_mut`]: struct.HashMap.html#method.raw_entry_mut
26972747
/// [`RawEntryBuilderMut`]: struct.RawEntryBuilderMut.html
2748+
///
2749+
/// # Examples
2750+
///
2751+
/// ```
2752+
/// use core::hash::{BuildHasher, Hash};
2753+
/// use hashbrown::hash_map::{HashMap, RawEntryMut, RawOccupiedEntryMut};
2754+
///
2755+
/// let mut map = HashMap::new();
2756+
/// map.extend([('a', 1), ('b', 2), ('c', 3)]);
2757+
/// assert_eq!(map.len(), 3);
2758+
///
2759+
/// fn compute_hash<K: Hash + ?Sized, S: BuildHasher>(hash_builder: &S, key: &K) -> u64 {
2760+
/// use core::hash::Hasher;
2761+
/// let mut state = hash_builder.build_hasher();
2762+
/// key.hash(&mut state);
2763+
/// state.finish()
2764+
/// }
2765+
///
2766+
/// // Existing key (insert)
2767+
/// let raw: RawEntryMut<_, _, _> = map.raw_entry_mut().from_key(&'a');
2768+
/// let _raw_o: RawOccupiedEntryMut<_, _, _> = raw.insert('a', 10);
2769+
/// assert_eq!(map.len(), 3);
2770+
///
2771+
/// // Nonexistent key (insert)
2772+
/// map.raw_entry_mut().from_key(&'d').insert('d', 40);
2773+
/// assert_eq!(map.len(), 4);
2774+
///
2775+
/// // Existing key (or_insert)
2776+
/// let hash = compute_hash(map.hasher(), &'b');
2777+
/// let kv = map
2778+
/// .raw_entry_mut()
2779+
/// .from_key_hashed_nocheck(hash, &'b')
2780+
/// .or_insert('b', 20);
2781+
/// assert_eq!(kv, (&mut 'b', &mut 2));
2782+
/// *kv.1 = 20;
2783+
/// assert_eq!(map.len(), 4);
2784+
///
2785+
/// // Nonexistent key (or_insert)
2786+
/// let hash = compute_hash(map.hasher(), &'e');
2787+
/// let kv = map
2788+
/// .raw_entry_mut()
2789+
/// .from_key_hashed_nocheck(hash, &'e')
2790+
/// .or_insert('e', 50);
2791+
/// assert_eq!(kv, (&mut 'e', &mut 50));
2792+
/// assert_eq!(map.len(), 5);
2793+
///
2794+
/// // Existing key (or_insert_with)
2795+
/// let hash = compute_hash(map.hasher(), &'c');
2796+
/// let kv = map
2797+
/// .raw_entry_mut()
2798+
/// .from_hash(hash, |q| q == &'c')
2799+
/// .or_insert_with(|| ('c', 30));
2800+
/// assert_eq!(kv, (&mut 'c', &mut 3));
2801+
/// *kv.1 = 30;
2802+
/// assert_eq!(map.len(), 5);
2803+
///
2804+
/// // Nonexistent key (or_insert_with)
2805+
/// let hash = compute_hash(map.hasher(), &'f');
2806+
/// let kv = map
2807+
/// .raw_entry_mut()
2808+
/// .from_hash(hash, |q| q == &'f')
2809+
/// .or_insert_with(|| ('f', 60));
2810+
/// assert_eq!(kv, (&mut 'f', &mut 60));
2811+
/// assert_eq!(map.len(), 6);
2812+
///
2813+
/// println!("Our HashMap: {:?}", map);
2814+
///
2815+
/// let mut vec: Vec<_> = map.iter().map(|(&k, &v)| (k, v)).collect();
2816+
/// // The `Iter` iterator produces items in arbitrary order, so the
2817+
/// // items must be sorted to test them against a sorted array.
2818+
/// vec.sort_unstable();
2819+
/// assert_eq!(vec, [('a', 10), ('b', 20), ('c', 30), ('d', 40), ('e', 50), ('f', 60)]);
2820+
/// ```
26982821
pub enum RawEntryMut<'a, K, V, S, A: Allocator + Clone = Global> {
26992822
/// An occupied entry.
2823+
///
2824+
/// # Examples
2825+
///
2826+
/// ```
2827+
/// use hashbrown::{hash_map::RawEntryMut, HashMap};
2828+
/// let mut map: HashMap<_, _> = [("a", 100), ("b", 200)].into();
2829+
///
2830+
/// match map.raw_entry_mut().from_key(&"a") {
2831+
/// RawEntryMut::Vacant(_) => unreachable!(),
2832+
/// RawEntryMut::Occupied(_) => { }
2833+
/// }
2834+
/// ```
27002835
Occupied(RawOccupiedEntryMut<'a, K, V, S, A>),
27012836
/// A vacant entry.
2837+
///
2838+
/// # Examples
2839+
///
2840+
/// ```
2841+
/// use hashbrown::{hash_map::RawEntryMut, HashMap};
2842+
/// let mut map: HashMap<&str, i32> = HashMap::new();
2843+
///
2844+
/// match map.raw_entry_mut().from_key("a") {
2845+
/// RawEntryMut::Occupied(_) => unreachable!(),
2846+
/// RawEntryMut::Vacant(_) => { }
2847+
/// }
2848+
/// ```
27022849
Vacant(RawVacantEntryMut<'a, K, V, S, A>),
27032850
}
27042851

27052852
/// A view into an occupied entry in a `HashMap`.
27062853
/// It is part of the [`RawEntryMut`] enum.
27072854
///
27082855
/// [`RawEntryMut`]: enum.RawEntryMut.html
2856+
///
2857+
/// # Examples
2858+
///
2859+
/// ```
2860+
/// use core::hash::{BuildHasher, Hash};
2861+
/// use hashbrown::hash_map::{HashMap, RawEntryMut, RawOccupiedEntryMut};
2862+
///
2863+
/// let mut map = HashMap::new();
2864+
/// map.extend([("a", 10), ("b", 20), ("c", 30)]);
2865+
///
2866+
/// fn compute_hash<K: Hash + ?Sized, S: BuildHasher>(hash_builder: &S, key: &K) -> u64 {
2867+
/// use core::hash::Hasher;
2868+
/// let mut state = hash_builder.build_hasher();
2869+
/// key.hash(&mut state);
2870+
/// state.finish()
2871+
/// }
2872+
///
2873+
/// let _raw_o: RawOccupiedEntryMut<_, _, _> = map.raw_entry_mut().from_key(&"a").insert("a", 100);
2874+
/// assert_eq!(map.len(), 3);
2875+
///
2876+
/// // Existing key (insert and update)
2877+
/// match map.raw_entry_mut().from_key(&"a") {
2878+
/// RawEntryMut::Vacant(_) => unreachable!(),
2879+
/// RawEntryMut::Occupied(mut view) => {
2880+
/// assert_eq!(view.get(), &100);
2881+
/// let v = view.get_mut();
2882+
/// let new_v = (*v) * 10;
2883+
/// *v = new_v;
2884+
/// assert_eq!(view.insert(1111), 1000);
2885+
/// }
2886+
/// }
2887+
///
2888+
/// assert_eq!(map[&"a"], 1111);
2889+
/// assert_eq!(map.len(), 3);
2890+
///
2891+
/// // Existing key (take)
2892+
/// let hash = compute_hash(map.hasher(), &"c");
2893+
/// match map.raw_entry_mut().from_key_hashed_nocheck(hash, &"c") {
2894+
/// RawEntryMut::Vacant(_) => unreachable!(),
2895+
/// RawEntryMut::Occupied(view) => {
2896+
/// assert_eq!(view.remove_entry(), ("c", 30));
2897+
/// }
2898+
/// }
2899+
/// assert_eq!(map.raw_entry().from_key(&"c"), None);
2900+
/// assert_eq!(map.len(), 2);
2901+
///
2902+
/// let hash = compute_hash(map.hasher(), &"b");
2903+
/// match map.raw_entry_mut().from_hash(hash, |q| *q == "b") {
2904+
/// RawEntryMut::Vacant(_) => unreachable!(),
2905+
/// RawEntryMut::Occupied(view) => {
2906+
/// assert_eq!(view.remove_entry(), ("b", 20));
2907+
/// }
2908+
/// }
2909+
/// assert_eq!(map.get(&"b"), None);
2910+
/// assert_eq!(map.len(), 1);
2911+
/// ```
27092912
pub struct RawOccupiedEntryMut<'a, K, V, S, A: Allocator + Clone = Global> {
27102913
elem: Bucket<(K, V)>,
27112914
table: &'a mut RawTable<(K, V), A>,
@@ -2733,6 +2936,50 @@ where
27332936
/// It is part of the [`RawEntryMut`] enum.
27342937
///
27352938
/// [`RawEntryMut`]: enum.RawEntryMut.html
2939+
///
2940+
/// # Examples
2941+
///
2942+
/// ```
2943+
/// use core::hash::{BuildHasher, Hash};
2944+
/// use hashbrown::hash_map::{HashMap, RawEntryMut, RawVacantEntryMut};
2945+
///
2946+
/// let mut map = HashMap::<&str, i32>::new();
2947+
///
2948+
/// fn compute_hash<K: Hash + ?Sized, S: BuildHasher>(hash_builder: &S, key: &K) -> u64 {
2949+
/// use core::hash::Hasher;
2950+
/// let mut state = hash_builder.build_hasher();
2951+
/// key.hash(&mut state);
2952+
/// state.finish()
2953+
/// }
2954+
///
2955+
/// let raw_v: RawVacantEntryMut<_, _, _> = match map.raw_entry_mut().from_key(&"a") {
2956+
/// RawEntryMut::Vacant(view) => view,
2957+
/// RawEntryMut::Occupied(_) => unreachable!(),
2958+
/// };
2959+
/// raw_v.insert("a", 10);
2960+
/// assert!(map[&"a"] == 10 && map.len() == 1);
2961+
///
2962+
/// // Nonexistent key (insert and update)
2963+
/// let hash = compute_hash(map.hasher(), &"b");
2964+
/// match map.raw_entry_mut().from_key_hashed_nocheck(hash, &"b") {
2965+
/// RawEntryMut::Occupied(_) => unreachable!(),
2966+
/// RawEntryMut::Vacant(view) => {
2967+
/// let (k, value) = view.insert("b", 2);
2968+
/// assert_eq!((*k, *value), ("b", 2));
2969+
/// *value = 20;
2970+
/// }
2971+
/// }
2972+
/// assert!(map[&"b"] == 20 && map.len() == 2);
2973+
///
2974+
/// let hash = compute_hash(map.hasher(), &"c");
2975+
/// match map.raw_entry_mut().from_hash(hash, |q| *q == "c") {
2976+
/// RawEntryMut::Occupied(_) => unreachable!(),
2977+
/// RawEntryMut::Vacant(view) => {
2978+
/// assert_eq!(view.insert("c", 30), (&mut "c", &mut 30));
2979+
/// }
2980+
/// }
2981+
/// assert!(map[&"c"] == 30 && map.len() == 3);
2982+
/// ```
27362983
pub struct RawVacantEntryMut<'a, K, V, S, A: Allocator + Clone = Global> {
27372984
table: &'a mut RawTable<(K, V), A>,
27382985
hash_builder: &'a S,

0 commit comments

Comments
 (0)