A potential ambiguity concerning the alternate wording and the example usage of `HashSet::retain`.

[aalekhpatel07]

Location

Lines 310-321 of std/collections/hash/set.rs

Summary

The alternate (and presumably simpler) wording says

"In other words, remove all elements e for which f(&e) returns false."

but the example usage in the doc comment would've compiled just fine even if we accidentally misread/misinterpreted that as "... returns true" (since the count of removed and retained items are equal):

let mut set = HashSet::from([1, 2, 3, 4, 5, 6]);
set.retain(|&k| k % 2 == 0);
assert_eq!(set.len(), 3);

To demonstrate that exactly only the false elements are filtered out we could potentially change the example so that it fits better with the alternate definition:

let mut set = HashSet::from([1, 2, 3, 4, 5, 6, 7]);
set.retain(|&k| k % 2 == 0);
assert_eq!(set.len(), 3);

[compiler-errors]

Alternatively, since HashSet implements PartialEq, this is even more clear:

use std::collections::HashSet;

fn main() {
    let mut set = HashSet::from([1, 2, 3, 4, 5, 6]);
    set.retain(|&k| k % 2 == 0);
    assert_eq!(set, HashSet::from([2, 4, 6]));
}

[Ezrashaw]

@rustbot claim