From d29d1a332bc44b461859ccc756d53cbd81cbea0e Mon Sep 17 00:00:00 2001 From: Paul Mabileau Date: Sat, 17 May 2025 02:09:06 +0200 Subject: [PATCH 1/7] Docs(lib/alloc/vec): Add the missing `an` to `extract_if`'s first sentence As inspired by the equivalent methods from other collection types. Signed-off-by: Paul Mabileau --- library/alloc/src/vec/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs index 59879f23d7850..4d03ca63ec8ad 100644 --- a/library/alloc/src/vec/mod.rs +++ b/library/alloc/src/vec/mod.rs @@ -3648,7 +3648,7 @@ impl Vec { Splice { drain: self.drain(range), replace_with: replace_with.into_iter() } } - /// Creates an iterator which uses a closure to determine if element in the range should be removed. + /// Creates an iterator which uses a closure to determine if an element in the range should be removed. /// /// If the closure returns true, then the element is removed and yielded. /// If the closure returns false, the element will remain in the vector and will not be yielded From cd5772e396361c72e4662655687a462aee6c6aea Mon Sep 17 00:00:00 2001 From: Paul Mabileau Date: Sat, 17 May 2025 02:14:55 +0200 Subject: [PATCH 2/7] Docs(lib/coll/hm): Reword `extract_if` to use `element` instead of `value` A minor change, but it seemed interesting to unify this one's description, especially considering all the other equivalents use `element` as well. Signed-off-by: Paul Mabileau --- library/std/src/collections/hash/set.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/library/std/src/collections/hash/set.rs b/library/std/src/collections/hash/set.rs index 8514dfd9a984d..5043d1bd1df7c 100644 --- a/library/std/src/collections/hash/set.rs +++ b/library/std/src/collections/hash/set.rs @@ -276,10 +276,10 @@ impl HashSet { Drain { base: self.base.drain() } } - /// Creates an iterator which uses a closure to determine if a value should be removed. + /// Creates an iterator which uses a closure to determine if an element should be removed. /// - /// If the closure returns true, then the value is removed and yielded. - /// If the closure returns false, the value will remain in the list and will not be yielded + /// If the closure returns true, then the element is removed and yielded. + /// If the closure returns false, the element will remain in the list and will not be yielded /// by the iterator. /// /// If the returned `ExtractIf` is not exhausted, e.g. because it is dropped without iterating From 35f847363729b16332eab1a85900617218495757 Mon Sep 17 00:00:00 2001 From: Paul Mabileau Date: Sat, 17 May 2025 02:22:13 +0200 Subject: [PATCH 3/7] Docs(lib/coll/btm): Split `extract_if`'s first sentence from the following ones This also seems like a small mistake: the first main sentence is put in the same paragraph as the other two following ones while other equivalents all have it split. Therefore, do the same here. Signed-off-by: Paul Mabileau --- library/alloc/src/collections/btree/map.rs | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/library/alloc/src/collections/btree/map.rs b/library/alloc/src/collections/btree/map.rs index 5ca32ed741af8..ea81645aa6491 100644 --- a/library/alloc/src/collections/btree/map.rs +++ b/library/alloc/src/collections/btree/map.rs @@ -1398,10 +1398,12 @@ impl BTreeMap { } /// Creates an iterator that visits all elements (key-value pairs) in - /// ascending key order and uses a closure to determine if an element should - /// be removed. If the closure returns `true`, the element is removed from - /// the map and yielded. If the closure returns `false`, or panics, the - /// element remains in the map and will not be yielded. + /// ascending key order and uses a closure to determine if an element + /// should be removed. + /// + /// If the closure returns `true`, the element is removed from the map and + /// yielded. If the closure returns `false`, or panics, the element remains + /// in the map and will not be yielded. /// /// The iterator also lets you mutate the value of each element in the /// closure, regardless of whether you choose to keep or remove it. From 9205ee27a815e5b356cfce6269d9ded1d1c098f7 Mon Sep 17 00:00:00 2001 From: Paul Mabileau Date: Sat, 17 May 2025 02:36:08 +0200 Subject: [PATCH 4/7] Docs(lib/extract_if): Unify paragraph about closure actions Also fixes `HashSet`'s that incorrectly designated itself as a `list`. Signed-off-by: Paul Mabileau --- library/alloc/src/collections/linked_list.rs | 6 +++--- library/alloc/src/vec/mod.rs | 6 +++--- library/std/src/collections/hash/map.rs | 6 +++--- library/std/src/collections/hash/set.rs | 6 +++--- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/library/alloc/src/collections/linked_list.rs b/library/alloc/src/collections/linked_list.rs index 00e2805d11f61..1890a114d3cb2 100644 --- a/library/alloc/src/collections/linked_list.rs +++ b/library/alloc/src/collections/linked_list.rs @@ -1124,9 +1124,9 @@ impl LinkedList { /// Creates an iterator which uses a closure to determine if an element should be removed. /// - /// If the closure returns true, then the element is removed and yielded. - /// If the closure returns false, the element will remain in the list and will not be yielded - /// by the iterator. + /// If the closure returns `true`, the element is removed from the list and + /// yielded. If the closure returns `false`, or panics, the element remains + /// in the list and will not be yielded. /// /// If the returned `ExtractIf` is not exhausted, e.g. because it is dropped without iterating /// or the iteration short-circuits, then the remaining elements will be retained. diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs index 4d03ca63ec8ad..e5f2c9468e386 100644 --- a/library/alloc/src/vec/mod.rs +++ b/library/alloc/src/vec/mod.rs @@ -3650,9 +3650,9 @@ impl Vec { /// Creates an iterator which uses a closure to determine if an element in the range should be removed. /// - /// If the closure returns true, then the element is removed and yielded. - /// If the closure returns false, the element will remain in the vector and will not be yielded - /// by the iterator. + /// If the closure returns `true`, the element is removed from the vector + /// and yielded. If the closure returns `false`, or panics, the element + /// remains in the vector and will not be yielded. /// /// Only elements that fall in the provided range are considered for extraction, but any elements /// after the range will still have to be moved if any element has been extracted. diff --git a/library/std/src/collections/hash/map.rs b/library/std/src/collections/hash/map.rs index 3530f890f5294..9732d2c2d5ce9 100644 --- a/library/std/src/collections/hash/map.rs +++ b/library/std/src/collections/hash/map.rs @@ -650,9 +650,9 @@ impl HashMap { /// Creates an iterator which uses a closure to determine if an element should be removed. /// - /// If the closure returns true, the element is removed from the map and yielded. - /// If the closure returns false, or panics, the element remains in the map and will not be - /// yielded. + /// If the closure returns `true`, the element is removed from the map and + /// yielded. If the closure returns `false`, or panics, the element remains + /// in the map and will not be yielded. /// /// Note that `extract_if` lets you mutate every value in the filter closure, regardless of /// whether you choose to keep or remove it. diff --git a/library/std/src/collections/hash/set.rs b/library/std/src/collections/hash/set.rs index 5043d1bd1df7c..482d57b47f677 100644 --- a/library/std/src/collections/hash/set.rs +++ b/library/std/src/collections/hash/set.rs @@ -278,9 +278,9 @@ impl HashSet { /// Creates an iterator which uses a closure to determine if an element should be removed. /// - /// If the closure returns true, then the element is removed and yielded. - /// If the closure returns false, the element will remain in the list and will not be yielded - /// by the iterator. + /// If the closure returns `true`, the element is removed from the set and + /// yielded. If the closure returns `false`, or panics, the element remains + /// in the set and will not be yielded. /// /// If the returned `ExtractIf` is not exhausted, e.g. because it is dropped without iterating /// or the iteration short-circuits, then the remaining elements will be retained. From 014434e96f4f42e06b6c2dfc00110209b121040e Mon Sep 17 00:00:00 2001 From: Paul Mabileau Date: Sat, 17 May 2025 02:45:56 +0200 Subject: [PATCH 5/7] Docs(lib/extract_if): Unify paragraph about elements mutation Take the one from `BTreeMap` that seems the best-worded and most precise among the available variations. Signed-off-by: Paul Mabileau --- library/alloc/src/collections/linked_list.rs | 4 ++-- library/alloc/src/vec/mod.rs | 4 ++-- library/std/src/collections/hash/map.rs | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/library/alloc/src/collections/linked_list.rs b/library/alloc/src/collections/linked_list.rs index 1890a114d3cb2..0e365ebd3080a 100644 --- a/library/alloc/src/collections/linked_list.rs +++ b/library/alloc/src/collections/linked_list.rs @@ -1132,8 +1132,8 @@ impl LinkedList { /// or the iteration short-circuits, then the remaining elements will be retained. /// Use `extract_if().for_each(drop)` if you do not need the returned iterator. /// - /// Note that `extract_if` lets you mutate every element in the filter closure, regardless of - /// whether you choose to keep or remove it. + /// The iterator also lets you mutate the value of each element in the + /// closure, regardless of whether you choose to keep or remove it. /// /// # Examples /// diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs index e5f2c9468e386..3ea5f160666bc 100644 --- a/library/alloc/src/vec/mod.rs +++ b/library/alloc/src/vec/mod.rs @@ -3692,8 +3692,8 @@ impl Vec { /// But `extract_if` is easier to use. `extract_if` is also more efficient, /// because it can backshift the elements of the array in bulk. /// - /// Note that `extract_if` also lets you mutate the elements passed to the filter closure, - /// regardless of whether you choose to keep or remove them. + /// The iterator also lets you mutate the value of each element in the + /// closure, regardless of whether you choose to keep or remove it. /// /// # Panics /// diff --git a/library/std/src/collections/hash/map.rs b/library/std/src/collections/hash/map.rs index 9732d2c2d5ce9..5e053d3644856 100644 --- a/library/std/src/collections/hash/map.rs +++ b/library/std/src/collections/hash/map.rs @@ -654,8 +654,8 @@ impl HashMap { /// yielded. If the closure returns `false`, or panics, the element remains /// in the map and will not be yielded. /// - /// Note that `extract_if` lets you mutate every value in the filter closure, regardless of - /// whether you choose to keep or remove it. + /// The iterator also lets you mutate the value of each element in the + /// closure, regardless of whether you choose to keep or remove it. /// /// If the returned `ExtractIf` is not exhausted, e.g. because it is dropped without iterating /// or the iteration short-circuits, then the remaining elements will be retained. From a9330dd0e9fbc1698b69ac82e138d9dcef31bc33 Mon Sep 17 00:00:00 2001 From: Paul Mabileau Date: Sat, 17 May 2025 02:49:57 +0200 Subject: [PATCH 6/7] Docs(lib/coll/hm): Add kv pair to `extract_if`'s first sentence Make it consistent in this regard with `BTreeMap`'s. Signed-off-by: Paul Mabileau --- library/std/src/collections/hash/map.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/std/src/collections/hash/map.rs b/library/std/src/collections/hash/map.rs index 5e053d3644856..edbdd0411457f 100644 --- a/library/std/src/collections/hash/map.rs +++ b/library/std/src/collections/hash/map.rs @@ -648,7 +648,7 @@ impl HashMap { Drain { base: self.base.drain() } } - /// Creates an iterator which uses a closure to determine if an element should be removed. + /// Creates an iterator which uses a closure to determine if an element (key-value pair) should be removed. /// /// If the closure returns `true`, the element is removed from the map and /// yielded. If the closure returns `false`, or panics, the element remains From b1d7480acbc6bcc01f0eef98feaccdf53b387cd3 Mon Sep 17 00:00:00 2001 From: Paul Mabileau Date: Sat, 17 May 2025 02:54:21 +0200 Subject: [PATCH 7/7] Docs(lib/extract_if): Unify example description Signed-off-by: Paul Mabileau --- library/alloc/src/collections/linked_list.rs | 2 +- library/alloc/src/vec/mod.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/library/alloc/src/collections/linked_list.rs b/library/alloc/src/collections/linked_list.rs index 0e365ebd3080a..d03c1969b5b70 100644 --- a/library/alloc/src/collections/linked_list.rs +++ b/library/alloc/src/collections/linked_list.rs @@ -1137,7 +1137,7 @@ impl LinkedList { /// /// # Examples /// - /// Splitting a list into evens and odds, reusing the original list: + /// Splitting a list into even and odd values, reusing the original list: /// /// ``` /// use std::collections::LinkedList; diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs index 3ea5f160666bc..ce7321544b6b9 100644 --- a/library/alloc/src/vec/mod.rs +++ b/library/alloc/src/vec/mod.rs @@ -3701,7 +3701,7 @@ impl Vec { /// /// # Examples /// - /// Splitting an array into evens and odds, reusing the original allocation: + /// Splitting a vector into even and odd values, reusing the original vector: /// /// ``` /// let mut numbers = vec![1, 2, 3, 4, 5, 6, 8, 9, 11, 13, 14, 15];