From d68c3ab17b6f6c3b71d0531063aec8e64098f59c Mon Sep 17 00:00:00 2001 From: Anders Kaseorg Date: Mon, 3 Jul 2017 17:18:01 -0400 Subject: Document unintuitive argument order for Vec::dedup_by relation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When trying to use dedup_by to merge some auxiliary information from removed elements into kept elements, I was surprised to observe that vec.dedup_by(same_bucket) calls same_bucket(a, b) where b appears before a in the vector, and discards a when true is returned. This argument order is probably a bug, but since it has already been stabilized, I guess we should document it as a feature and move on. (Vec::dedup also uses == with this unexpected argument order, but I figure that’s not important since == is expected to be symmetric with no side effects.) Signed-off-by: Anders Kaseorg --- src/liballoc/vec.rs | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) (limited to 'src/liballoc/vec.rs') diff --git a/src/liballoc/vec.rs b/src/liballoc/vec.rs index 5d1999a4262..1a5975686df 100644 --- a/src/liballoc/vec.rs +++ b/src/liballoc/vec.rs @@ -823,7 +823,8 @@ impl Vec { } } - /// Removes consecutive elements in the vector that resolve to the same key. + /// Removes all but the first of consecutive elements in the vector that resolve to the same + /// key. /// /// If the vector is sorted, this removes all duplicates. /// @@ -842,11 +843,13 @@ impl Vec { self.dedup_by(|a, b| key(a) == key(b)) } - /// Removes consecutive elements in the vector according to a predicate. + /// Removes all but the first of consecutive elements in the vector satisfying a given equality + /// relation. /// /// The `same_bucket` function is passed references to two elements from the vector, and - /// returns `true` if the elements compare equal, or `false` if they do not. Only the first - /// of adjacent equal items is kept. + /// returns `true` if the elements compare equal, or `false` if they do not. The elements are + /// passed in opposite order from their order in the vector, so if `same_bucket(a, b)` returns + /// `true`, `a` is removed. /// /// If the vector is sorted, this removes all duplicates. /// -- cgit 1.4.1-3-g733a5