diff --git a/text/0000-contains-method-for-various-collections.md b/text/0000-contains-method-for-various-collections.md new file mode 100644 index 00000000000..3a2d97f7395 --- /dev/null +++ b/text/0000-contains-method-for-various-collections.md @@ -0,0 +1,95 @@ +- Feature Name: contains_method_for_various_collections +- Start Date: 2016-03-16 +- RFC PR: (leave this empty) +- Rust Issue: (leave this empty) + +# Summary +[summary]: #summary + +Add a `contains` method to `VecDeque` and `LinkedList` that checks if the +collection contains a given item. + +# Motivation +[motivation]: #motivation + +A `contains` method exists for the slice type `[T]` and for `Vec` through +`Deref`, but there is no easy way to check if a `VecDeque` or `LinkedList` +contains a specific item. Currently, the shortest way to do it is something +like: + +```rust +vec_deque.iter().any(|e| e == item) +``` + +While this is not insanely verbose, a `contains` method has the following +advantages: + +- the name `contains` expresses the programmer's intent... +- ... and thus is more idiomatic +- it's as short as it can get +- programmers that are used to call `contains` on a `Vec` are confused by the + non-existence of the method for `VecDeque` or `LinkedList` + +# Detailed design +[design]: #detailed-design + +Add the following method to `std::collections::VecDeque`: + +```rust +impl VecDeque { + /// Returns `true` if the `VecDeque` contains an element equal to the + /// given value. + pub fn contains(&self, x: &T) -> bool + where T: PartialEq + { + // implementation with a result equivalent to the result + // of `self.iter().any(|e| e == x)` + } +} +``` + +Add the following method to `std::collections::LinkedList`: + +```rust +impl LinkedList { + /// Returns `true` if the `LinkedList` contains an element equal to the + /// given value. + pub fn contains(&self, x: &T) -> bool + where T: PartialEq + { + // implementation with a result equivalent to the result + // of `self.iter().any(|e| e == x)` + } +} +``` + +The new methods should probably be marked as unstable initially and be +stabilized later. + +# Drawbacks +[drawbacks]: #drawbacks + +Obviously more methods increase the complexity of the standard library, but in +case of this RFC the increase is rather tiny. + +While `VecDeque::contains` should be (nearly) as fast as `[T]::contains`, +`LinkedList::contains` will probably be much slower due to the cache +inefficient nature of a linked list. Offering a method that is short to +write and convenient to use could lead to excessive use of said method +without knowing about the problems mentioned above. + +# Alternatives +[alternatives]: #alternatives + +There are a few alternatives: + +- add `VecDeque::contains` only and do not add `LinkedList::contains` +- do nothing, because -- technically -- the same functionality is offered + through iterators +- also add `BinaryHeap::contains`, since it could be convenient for some use + cases, too + +# Unresolved questions +[unresolved]: #unresolved-questions + +None so far.