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]

Author: Gankra

src/libcollections/binary_heap.rs

@@ -162,6 +162,8 @@ use core::ptr;
 use slice;
 use vec::Vec;
 
+// FIXME(conventions): implement into_iter
+
 /// A priority queue implemented with a binary heap.
 ///
 /// This will be a max-heap.
@@ -184,6 +186,7 @@ impl<T: Ord> BinaryHeap<T> {
     /// use std::collections::BinaryHeap;
     /// let pq: BinaryHeap<uint> = BinaryHeap::new();
     /// ```
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn new() -> BinaryHeap<T> { BinaryHeap{data: vec!(),} }
 
     /// Creates an empty `BinaryHeap` with a specific capacity.
@@ -197,6 +200,7 @@ impl<T: Ord> BinaryHeap<T> {
     /// use std::collections::BinaryHeap;
     /// let pq: BinaryHeap<uint> = BinaryHeap::with_capacity(10u);
     /// ```
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn with_capacity(capacity: uint) -> BinaryHeap<T> {
         BinaryHeap { data: Vec::with_capacity(capacity) }
     }
@@ -234,6 +238,7 @@ impl<T: Ord> BinaryHeap<T> {
     ///     println!("{}", x);
     /// }
     /// ```
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn iter<'a>(&'a self) -> Items<'a, T> {
         Items { iter: self.data.iter() }
     }
@@ -268,10 +273,19 @@ impl<T: Ord> BinaryHeap<T> {
     /// let pq: BinaryHeap<uint> = BinaryHeap::with_capacity(100u);
     /// assert!(pq.capacity() >= 100u);
     /// ```
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn capacity(&self) -> uint { self.data.capacity() }
 
-    /// Reserves capacity for exactly `n` elements in the `BinaryHeap`.
-    /// Do nothing if the capacity is already sufficient.
+    /// Reserves the minimum capacity for exactly `additional` more elements to be inserted in the
+    /// given `BinaryHeap`. Does nothing if the capacity is already sufficient.
+    ///
+    /// Note that the allocator may give the collection more space than it requests. Therefore
+    /// capacity can not be relied upon to be precisely minimal. Prefer `reserve` if future
+    /// insertions are expected.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the new capacity overflows `uint`.
     ///
     /// # Example
     ///
@@ -280,12 +294,17 @@ impl<T: Ord> BinaryHeap<T> {
     ///
     /// let mut pq: BinaryHeap<uint> = BinaryHeap::new();
     /// pq.reserve_exact(100u);
-    /// assert!(pq.capacity() == 100u);
+    /// assert!(pq.capacity() >= 100u);
     /// ```
-    pub fn reserve_exact(&mut self, n: uint) { self.data.reserve_exact(n) }
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
+    pub fn reserve_exact(&mut self, additional: uint) { self.data.reserve_exact(additional) }
 
-    /// Reserves capacity for at least `n` elements in the `BinaryHeap`.
-    /// Do nothing if the capacity is already sufficient.
+    /// Reserves capacity for at least `additional` more elements to be inserted in the
+    /// `BinaryHeap`. The collection may reserve more space to avoid frequent reallocations.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the new capacity overflows `uint`.
     ///
     /// # Example
     ///
@@ -296,8 +315,15 @@ impl<T: Ord> BinaryHeap<T> {
     /// pq.reserve(100u);
     /// assert!(pq.capacity() >= 100u);
     /// ```
-    pub fn reserve(&mut self, n: uint) {
-        self.data.reserve(n)
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
+    pub fn reserve(&mut self, additional: uint) {
+        self.data.reserve(additional)
+    }
+
+    /// Discards as much additional capacity as possible.
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
+    pub fn shrink_to_fit(&mut self) {
+        self.data.shrink_to_fit()
     }
 
     /// Removes the greatest item from a queue and returns it, or `None` if it
@@ -314,6 +340,7 @@ impl<T: Ord> BinaryHeap<T> {
     /// assert_eq!(pq.pop(), Some(1i));
     /// assert_eq!(pq.pop(), None);
     /// ```
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn pop(&mut self) -> Option<T> {
         match self.data.pop() {
             None           => { None }
@@ -342,6 +369,7 @@ impl<T: Ord> BinaryHeap<T> {
     /// assert_eq!(pq.len(), 3);
     /// assert_eq!(pq.top(), Some(&5i));
     /// ```
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn push(&mut self, item: T) {
         self.data.push(item);
         let new_len = self.len() - 1;
@@ -495,12 +523,15 @@ impl<T: Ord> BinaryHeap<T> {
     }
 
     /// Returns the length of the queue.
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn len(&self) -> uint { self.data.len() }
 
     /// Returns true if the queue contains no elements
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn is_empty(&self) -> bool { self.len() == 0 }
 
     /// Drops all items from the queue.
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn clear(&mut self) { self.data.truncate(0) }
 }
 
@@ -528,8 +559,7 @@ impl<T: Ord> Extendable<T> for BinaryHeap<T> {
     fn extend<Iter: Iterator<T>>(&mut self, mut iter: Iter) {
         let (lower, _) = iter.size_hint();
 
-        let len = self.capacity();
-        self.reserve(len + lower);
+        self.reserve(lower);
 
         for elem in iter {
             self.push(elem);

src/libcollections/bit.rs

@@ -75,6 +75,8 @@ use std::hash;
 
 use vec::Vec;
 
+// FIXME(conventions): look, we just need to refactor this whole thing. Inside and out.
+
 type MatchWords<'a> = Chain<MaskWords<'a>, Skip<Take<Enumerate<Repeat<u32>>>>>;
 // Take two BitV's, and return iterators of their words, where the shorter one
 // has been padded with 0's
@@ -216,6 +218,7 @@ impl Bitv {
     /// use std::collections::Bitv;
     /// let mut bv = Bitv::new();
     /// ```
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn new() -> Bitv {
         Bitv { storage: Vec::new(), nbits: 0 }
     }
@@ -613,6 +616,7 @@ impl Bitv {
     /// bv.truncate(2);
     /// assert!(bv.eq_vec([false, true]));
     /// ```
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn truncate(&mut self, len: uint) {
         if len < self.len() {
             self.nbits = len;
@@ -760,14 +764,17 @@ impl Bitv {
 
     /// Return the total number of bits in this vector
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn len(&self) -> uint { self.nbits }
 
     /// Returns true if there are no bits in this vector
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn is_empty(&self) -> bool { self.len() == 0 }
 
     /// Clears all bits in this vector.
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn clear(&mut self) {
         for w in self.storage.iter_mut() { *w = 0u32; }
     }
@@ -849,8 +856,7 @@ impl Clone for Bitv {
     #[inline]
     fn clone_from(&mut self, source: &Bitv) {
         self.nbits = source.nbits;
-        self.storage.reserve(source.storage.len());
-        for (i, w) in self.storage.iter_mut().enumerate() { *w = source.storage[i]; }
+        self.storage.clone_from(&source.storage);
     }
 }
 
@@ -1052,6 +1058,7 @@ impl BitvSet {
     /// let mut s = BitvSet::new();
     /// ```
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn new() -> BitvSet {
         BitvSet(Bitv::new())
     }
@@ -1067,6 +1074,7 @@ impl BitvSet {
     /// assert!(s.capacity() >= 100);
     /// ```
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn with_capacity(nbits: uint) -> BitvSet {
         let bitv = Bitv::with_capacity(nbits, false);
         BitvSet::from_bitv(bitv)
@@ -1106,6 +1114,7 @@ impl BitvSet {
     /// assert!(s.capacity() >= 100);
     /// ```
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn capacity(&self) -> uint {
         let &BitvSet(ref bitv) = self;
         bitv.capacity()
@@ -1212,6 +1221,7 @@ impl BitvSet {
     /// println!("new capacity: {}", s.capacity());
     /// ```
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn shrink_to_fit(&mut self) {
         let &BitvSet(ref mut bitv) = self;
         // Obtain original length
@@ -1240,6 +1250,7 @@ impl BitvSet {
     /// }
     /// ```
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn iter<'a>(&'a self) -> BitPositions<'a> {
         BitPositions {set: self, next_idx: 0u}
     }
@@ -1262,6 +1273,7 @@ impl BitvSet {
     /// }
     /// ```
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn union<'a>(&'a self, other: &'a BitvSet) -> TwoBitPositions<'a> {
         TwoBitPositions {
             set: self,
@@ -1290,6 +1302,7 @@ impl BitvSet {
     /// }
     /// ```
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn intersection<'a>(&'a self, other: &'a BitvSet) -> Take<TwoBitPositions<'a>> {
         let min = cmp::min(self.capacity(), other.capacity());
         TwoBitPositions {
@@ -1326,6 +1339,7 @@ impl BitvSet {
     /// }
     /// ```
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn difference<'a>(&'a self, other: &'a BitvSet) -> TwoBitPositions<'a> {
         TwoBitPositions {
             set: self,
@@ -1355,6 +1369,7 @@ impl BitvSet {
     /// }
     /// ```
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn symmetric_difference<'a>(&'a self, other: &'a BitvSet) -> TwoBitPositions<'a> {
         TwoBitPositions {
             set: self,
@@ -1473,27 +1488,31 @@ impl BitvSet {
 
     /// Return the number of set bits in this set.
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn len(&self) -> uint  {
         let &BitvSet(ref bitv) = self;
         bitv.storage.iter().fold(0, |acc, &n| acc + n.count_ones())
     }
 
     /// Returns whether there are no bits set in this set
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn is_empty(&self) -> bool {
         let &BitvSet(ref bitv) = self;
         bitv.storage.iter().all(|&n| n == 0)
     }
 
     /// Clears all bits in this set
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn clear(&mut self) {
         let &BitvSet(ref mut bitv) = self;
         bitv.clear();
     }
 
     /// Returns `true` if this set contains the specified integer.
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn contains(&self, value: &uint) -> bool {
         let &BitvSet(ref bitv) = self;
         *value < bitv.nbits && bitv.get(*value)
@@ -1502,12 +1521,14 @@ impl BitvSet {
     /// Returns `true` if the set has no elements in common with `other`.
     /// This is equivalent to checking for an empty intersection.
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn is_disjoint(&self, other: &BitvSet) -> bool {
         self.intersection(other).next().is_none()
     }
 
     /// Returns `true` if the set is a subset of another.
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn is_subset(&self, other: &BitvSet) -> bool {
         let &BitvSet(ref self_bitv) = self;
         let &BitvSet(ref other_bitv) = other;
@@ -1521,12 +1542,14 @@ impl BitvSet {
 
     /// Returns `true` if the set is a superset of another.
     #[inline]
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn is_superset(&self, other: &BitvSet) -> bool {
         other.is_subset(self)
     }
 
     /// Adds a value to the set. Returns `true` if the value was not already
     /// present in the set.
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn insert(&mut self, value: uint) -> bool {
         if self.contains(&value) {
             return false;
@@ -1545,6 +1568,7 @@ impl BitvSet {
 
     /// Removes a value from the set. Returns `true` if the value was
     /// present in the set.
+    #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn remove(&mut self, value: &uint) -> bool {
         if !self.contains(value) {
             return false;