Implement low-hanging fruit of collection conventions

* Renames/deprecates the simplest and most obvious methods
* Adds FIXME(conventions)s for outstanding work
* Marks "handled" methods as unstable

NOTE: the semantics of reserve and reserve_exact have changed!
Other methods have had their semantics changed as well, but in a
way that should obviously not typecheck if used incorrectly.

Lots of work and breakage to come, but this handles most of the core
APIs and most eggregious breakage. Future changes should *mostly* focus on
niche collections, APIs, or simply back-compat additions.

[breaking-change]

1 files changed, 124 insertions, 68 deletions

diff --git a/src/libcollections/enum_set.rs b/src/libcollections/enum_set.rs
index bcae4fe68c9..454d4f1ca87 100644
--- a/src/libcollections/enum_set.rs
+++ b/src/libcollections/enum_set.rs
@@ -16,6 +16,10 @@
 use core::prelude::*;
 use core::fmt;
 
+// FIXME(conventions): implement BitXor
+// FIXME(contentions): implement union family of methods? (general design may be wrong here)
+// FIXME(conventions): implement len
+
 #[deriving(Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 /// A specialized `Set` implementation to use enum types.
 pub struct EnumSet<E> {
@@ -47,34 +51,56 @@ pub trait CLike {
     fn from_uint(uint) -> Self;
 }
 
-fn bit<E:CLike>(e: E) -> uint {
+fn bit<E:CLike>(e: &E) -> uint {
     1 << e.to_uint()
 }
 
 impl<E:CLike> EnumSet<E> {
-    /// Returns an empty `EnumSet`.
+    /// Deprecated: Renamed to `new`.
+    #[deprecated = "Renamed to `new`"]
     pub fn empty() -> EnumSet<E> {
+        EnumSet::new()
+    }
+
+    /// Returns an empty `EnumSet`.
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
+    pub fn new() -> EnumSet<E> {
         EnumSet {bits: 0}
     }
 
     /// Returns true if the `EnumSet` is empty.
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn is_empty(&self) -> bool {
         self.bits == 0
     }
 
+    pub fn clear(&mut self) {
+        self.bits = 0;
+    }
+
     /// Returns `true` if the `EnumSet` contains any enum of the given `EnumSet`.
+    /// Deprecated: Use `is_disjoint`.
+    #[deprecated = "Use `is_disjoint`"]
     pub fn intersects(&self, e: EnumSet<E>) -> bool {
-        (self.bits & e.bits) != 0
+        !self.is_disjoint(&e)
     }
 
-    /// Returns the intersection of both `EnumSets`.
-    pub fn intersection(&self, e: EnumSet<E>) -> EnumSet<E> {
-        EnumSet {bits: self.bits & e.bits}
+    /// Returns `false` if the `EnumSet` contains any enum of the given `EnumSet`.
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
+    pub fn is_disjoint(&self, other: &EnumSet<E>) -> bool {
+        (self.bits & other.bits) == 0
     }
 
-    /// Returns `true` if a given `EnumSet` is included in an `EnumSet`.
-    pub fn contains(&self, e: EnumSet<E>) -> bool {
-        (self.bits & e.bits) == e.bits
+    /// Returns `true` if a given `EnumSet` is included in this `EnumSet`.
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
+    pub fn is_superset(&self, other: &EnumSet<E>) -> bool {
+        (self.bits & other.bits) == other.bits
+    }
+
+    /// Returns `true` if this `EnumSet` is included in the given `EnumSet`.
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
+    pub fn is_subset(&self, other: &EnumSet<E>) -> bool {
+        other.is_subset(self)
     }
 
     /// Returns the union of both `EnumSets`.
@@ -82,17 +108,47 @@ impl<E:CLike> EnumSet<E> {
         EnumSet {bits: self.bits | e.bits}
     }
 
-    /// Adds an enum to an `EnumSet`.
+    /// Returns the intersection of both `EnumSets`.
+    pub fn intersection(&self, e: EnumSet<E>) -> EnumSet<E> {
+        EnumSet {bits: self.bits & e.bits}
+    }
+
+    /// Deprecated: Use `insert`.
+    #[deprecated = "Use `insert`"]
     pub fn add(&mut self, e: E) {
-        self.bits |= bit(e);
+        self.insert(e);
     }
 
-    /// Returns `true` if an `EnumSet` contains a given enum.
+    /// Adds an enum to the `EnumSet`, and returns `true` if it wasn't there before
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
+    pub fn insert(&mut self, e: E) -> bool {
+        let result = !self.contains(&e);
+        self.bits |= bit(&e);
+        result
+    }
+
+    /// Removes an enum from the EnumSet
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
+    pub fn remove(&mut self, e: &E) -> bool {
+        let result = self.contains(e);
+        self.bits &= !bit(e);
+        result
+    }
+
+    /// Deprecated: use `contains`.
+    #[deprecated = "use `contains"]
     pub fn contains_elem(&self, e: E) -> bool {
+        self.contains(&e)
+    }
+
+    /// Returns `true` if an `EnumSet` contains a given enum.
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
+    pub fn contains(&self, e: &E) -> bool {
         (self.bits & bit(e)) != 0
     }
 
     /// Returns an iterator over an `EnumSet`.
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn iter(&self) -> Items<E> {
         Items::new(self.bits)
     }
@@ -174,18 +230,18 @@ mod test {
     }
 
     #[test]
-    fn test_empty() {
-        let e: EnumSet<Foo> = EnumSet::empty();
+    fn test_new() {
+        let e: EnumSet<Foo> = EnumSet::new();
         assert!(e.is_empty());
     }
 
     #[test]
     fn test_show() {
-        let mut e = EnumSet::empty();
+        let mut e = EnumSet::new();
         assert_eq!("{}", e.to_string().as_slice());
-        e.add(A);
+        e.insert(A);
         assert_eq!("{A}", e.to_string().as_slice());
-        e.add(C);
+        e.insert(C);
         assert_eq!("{A, C}", e.to_string().as_slice());
     }
 
@@ -194,75 +250,75 @@ mod test {
 
     #[test]
     fn test_two_empties_do_not_intersect() {
-        let e1: EnumSet<Foo> = EnumSet::empty();
-        let e2: EnumSet<Foo> = EnumSet::empty();
-        assert!(!e1.intersects(e2));
+        let e1: EnumSet<Foo> = EnumSet::new();
+        let e2: EnumSet<Foo> = EnumSet::new();
+        assert!(e1.is_disjoint(&e2));
     }
 
     #[test]
     fn test_empty_does_not_intersect_with_full() {
-        let e1: EnumSet<Foo> = EnumSet::empty();
+        let e1: EnumSet<Foo> = EnumSet::new();
 
-        let mut e2: EnumSet<Foo> = EnumSet::empty();
-        e2.add(A);
-        e2.add(B);
-        e2.add(C);
+        let mut e2: EnumSet<Foo> = EnumSet::new();
+        e2.insert(A);
+        e2.insert(B);
+        e2.insert(C);
 
-        assert!(!e1.intersects(e2));
+        assert!(e1.is_disjoint(&e2));
     }
 
     #[test]
     fn test_disjoint_intersects() {
-        let mut e1: EnumSet<Foo> = EnumSet::empty();
-        e1.add(A);
+        let mut e1: EnumSet<Foo> = EnumSet::new();
+        e1.insert(A);
 
-        let mut e2: EnumSet<Foo> = EnumSet::empty();
-        e2.add(B);
+        let mut e2: EnumSet<Foo> = EnumSet::new();
+        e2.insert(B);
 
-        assert!(!e1.intersects(e2));
+        assert!(e1.is_disjoint(&e2));
     }
 
     #[test]
     fn test_overlapping_intersects() {
-        let mut e1: EnumSet<Foo> = EnumSet::empty();
-        e1.add(A);
+        let mut e1: EnumSet<Foo> = EnumSet::new();
+        e1.insert(A);
 
-        let mut e2: EnumSet<Foo> = EnumSet::empty();
-        e2.add(A);
-        e2.add(B);
+        let mut e2: EnumSet<Foo> = EnumSet::new();
+        e2.insert(A);
+        e2.insert(B);
 
-        assert!(e1.intersects(e2));
+        assert!(!e1.is_disjoint(&e2));
     }
 
     ///////////////////////////////////////////////////////////////////////////
     // contains and contains_elem
 
     #[test]
-    fn test_contains() {
-        let mut e1: EnumSet<Foo> = EnumSet::empty();
-        e1.add(A);
+    fn test_superset() {
+        let mut e1: EnumSet<Foo> = EnumSet::new();
+        e1.insert(A);
 
-        let mut e2: EnumSet<Foo> = EnumSet::empty();
-        e2.add(A);
-        e2.add(B);
+        let mut e2: EnumSet<Foo> = EnumSet::new();
+        e2.insert(A);
+        e2.insert(B);
 
-        assert!(!e1.contains(e2));
-        assert!(e2.contains(e1));
+        assert!(!e1.is_superset(&e2));
+        assert!(e2.is_superset(&e1));
     }
 
     #[test]
-    fn test_contains_elem() {
-        let mut e1: EnumSet<Foo> = EnumSet::empty();
-        e1.add(A);
-        assert!(e1.contains_elem(A));
-        assert!(!e1.contains_elem(B));
-        assert!(!e1.contains_elem(C));
-
-        e1.add(A);
-        e1.add(B);
-        assert!(e1.contains_elem(A));
-        assert!(e1.contains_elem(B));
-        assert!(!e1.contains_elem(C));
+    fn test_contains() {
+        let mut e1: EnumSet<Foo> = EnumSet::new();
+        e1.insert(A);
+        assert!(e1.contains(&A));
+        assert!(!e1.contains(&B));
+        assert!(!e1.contains(&C));
+
+        e1.insert(A);
+        e1.insert(B);
+        assert!(e1.contains(&A));
+        assert!(e1.contains(&B));
+        assert!(!e1.contains(&C));
     }
 
     ///////////////////////////////////////////////////////////////////////////
@@ -270,24 +326,24 @@ mod test {
 
     #[test]
     fn test_iterator() {
-        let mut e1: EnumSet<Foo> = EnumSet::empty();
+        let mut e1: EnumSet<Foo> = EnumSet::new();
 
         let elems: Vec<Foo> = e1.iter().collect();
         assert!(elems.is_empty())
 
-        e1.add(A);
+        e1.insert(A);
         let elems = e1.iter().collect();
         assert_eq!(vec![A], elems)
 
-        e1.add(C);
+        e1.insert(C);
         let elems = e1.iter().collect();
         assert_eq!(vec![A,C], elems)
 
-        e1.add(C);
+        e1.insert(C);
         let elems = e1.iter().collect();
         assert_eq!(vec![A,C], elems)
 
-        e1.add(B);
+        e1.insert(B);
         let elems = e1.iter().collect();
         assert_eq!(vec![A,B,C], elems)
     }
@@ -297,13 +353,13 @@ mod test {
 
     #[test]
     fn test_operators() {
-        let mut e1: EnumSet<Foo> = EnumSet::empty();
-        e1.add(A);
-        e1.add(C);
+        let mut e1: EnumSet<Foo> = EnumSet::new();
+        e1.insert(A);
+        e1.insert(C);
 
-        let mut e2: EnumSet<Foo> = EnumSet::empty();
-        e2.add(B);
-        e2.add(C);
+        let mut e2: EnumSet<Foo> = EnumSet::new();
+        e2.insert(B);
+        e2.insert(C);
 
         let e_union = e1 | e2;
         let elems = e_union.iter().collect();