Add Collection.contains method

[DartBot]

This issue was originally filed by @seaneagan

---

There are currently several methods to determine if a collection
"contains" a value:

map.containsKey(key)
map.containsValue(value)
set.contains(item)
list.indexOf(item) != -1

I propose unifying these into a Collection.contains method, whose
default implementation would be something like:

contains (T item) {
 for(final T i in this) {
   if(item == i) {
     return true;
   }
 }
 return false;
}

I use item == i rather than i == item since the caller likely
knows and cares more about the == method of the item they pass in than
that of each item in the collection. Another option would be item === i, but I think that is a less common use case which could be done
via a separate "containsIdentical" method.

It also might make sense to shorten Map's getKeys()/getValues() to
just keys/values (getters). I assume, as in Java, that these methods
return Collections which are backed by the original Map, and thus are
O(1). Then the above examples would simplify to:

map.keys.contains(key);
map.values.contains(value);
set.contains(item);
list.contains(item);

... and even if you don't know the particular Collection sub-interface
of a collection, you can still easily test whether it contains an
item:

collection.contains(item);

List.indexOf would still be necessary for determining the exact index
at which the list contains the item, but Map.containsKey,
Map.containsValue, and Set.contains could all be removed.

FWIW, JavaScript doesn't yet have a builtin collections framework, but
the need for a "contains" method for lists is being discussed for ES6
(see https://mail.mozilla.org/pipermail/es-discuss/2011-December/019099.html),
and the most popular collections library
(http://documentcloud.github.com/underscore/) has a "contains" method
similar to what I am proposing.

[dgrove]

Added Area-Library, Triaged labels.

[DartBot]

This comment was originally written by @tomyeh

---

Agree that it is more consistent and avoids unnecessary typo.

In additions, Collection.remove(E) is a nice feature too.

[DartBot]

This comment was originally written by @seaneagan

---

Filed issue #1248 separately for shortening getKeys() / getValues() to keys / values.

[DartBot]

This comment was originally written by @seaneagan

---

Java also has Collection#contains, whose contract does indeed use item == i (see above), however, it special cases null:

item === null ? i === null : item == i

which is good, since it avoids an NPE when item === null. Also, Java does not actually require calling ==, but something equivalent to == such as comparing hashCode()'s, which is also a good idea.

Java also has Collection#containsAll, which is quite useful as well, its contract in Dart should be:

containsAll(Iterable<E> other) {
  for(final i in other) if(!contains(i)) return false;
  return true;
}

except similarly to "contains" not needing to call ==, "containsAll" should not need to call "contains", i.e. it could inline it.

[DartBot]

This comment was originally written by @seaneagan

---

Just wanted to point out that:

http://news.dartlang.org/2012/01/proposed-changes-for-equality.html

really helps here, since the null checks are implied, and thus the contract goes back to being just:

item == i

[alan-knight]

I'd also comment that it would be nice to allow strings to be treated like collections for some operations. Sadly, strings already have a contains method that does something different. And an indexOf that behaves differently.

[munificent]

Looks like this is in Collection now.

---

Added AssumedStale label.