From d68c3ab17b6f6c3b71d0531063aec8e64098f59c Mon Sep 17 00:00:00 2001
From: Anders Kaseorg <andersk@mit.edu>
Date: Mon, 3 Jul 2017 17:18:01 -0400
Subject: [PATCH] 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 <andersk@mit.edu>
---
 src/liballoc/tests/vec.rs |  5 +++++
 src/liballoc/vec.rs       | 11 +++++++----
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/src/liballoc/tests/vec.rs b/src/liballoc/tests/vec.rs
index fdf453b39cf..17f1229c206 100644
--- a/src/liballoc/tests/vec.rs
+++ b/src/liballoc/tests/vec.rs
@@ -274,6 +274,11 @@ fn test_dedup_by() {
     vec.dedup_by(|a, b| a.eq_ignore_ascii_case(b));
 
     assert_eq!(vec, ["foo", "bar", "baz", "bar"]);
+
+    let mut vec = vec![("foo", 1), ("foo", 2), ("bar", 3), ("bar", 4), ("bar", 5)];
+    vec.dedup_by(|a, b| a.0 == b.0 && { b.1 += a.1; true });
+
+    assert_eq!(vec, [("foo", 3), ("bar", 12)]);
 }
 
 #[test]
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<T> Vec<T> {
         }
     }
 
-    /// 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<T> Vec<T> {
         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.
     ///