Rollup merge of #43041 - andersk:dedup_by, r=alexcrichton

Document unintuitive argument order for Vec::dedup_by relation

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.)

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]