Misc Stabilization for collections

This commit:

*Renames `BinaryHeap::top` to `BinaryHeap::peek`
*Stabilizes `front/back/front_mut/back_mut` in `DList` and `RingBuf`
*Stabilizes `swap` in `RingBuf`

Because of the method renaming, this is a [breaking-change].

src/libcollections/binary_heap.rs

@@ -272,15 +272,16 @@ impl<T: Ord> BinaryHeap<T> {
     /// use std::collections::BinaryHeap;
     ///
     /// let mut heap = BinaryHeap::new();
-    /// assert_eq!(heap.top(), None);
+    /// assert_eq!(heap.peek(), None);
     ///
     /// heap.push(1i);
     /// heap.push(5i);
     /// heap.push(2i);
-    /// assert_eq!(heap.top(), Some(&5i));
+    /// assert_eq!(heap.peek(), Some(&5i));
     ///
     /// ```
-    pub fn top(&self) -> Option<&T> {
+    #[stable]
+    pub fn peek(&self) -> Option<&T> {
         self.data.get(0)
     }
 
@@ -388,7 +389,7 @@ impl<T: Ord> BinaryHeap<T> {
     /// heap.push(1i);
     ///
     /// assert_eq!(heap.len(), 3);
-    /// assert_eq!(heap.top(), Some(&5i));
+    /// assert_eq!(heap.peek(), Some(&5i));
     /// ```
     #[unstable = "matches collection reform specification, waiting for dust to settle"]
     pub fn push(&mut self, item: T) {
@@ -412,7 +413,7 @@ impl<T: Ord> BinaryHeap<T> {
     /// assert_eq!(heap.push_pop(3i), 5);
     /// assert_eq!(heap.push_pop(9i), 9);
     /// assert_eq!(heap.len(), 2);
-    /// assert_eq!(heap.top(), Some(&3i));
+    /// assert_eq!(heap.peek(), Some(&3i));
     /// ```
     pub fn push_pop(&mut self, mut item: T) -> T {
         match self.data.get_mut(0) {
@@ -442,7 +443,7 @@ impl<T: Ord> BinaryHeap<T> {
     /// assert_eq!(heap.replace(1i), None);
     /// assert_eq!(heap.replace(3i), Some(1i));
     /// assert_eq!(heap.len(), 1);
-    /// assert_eq!(heap.top(), Some(&3i));
+    /// assert_eq!(heap.peek(), Some(&3i));
     /// ```
     pub fn replace(&mut self, mut item: T) -> Option<T> {
         if !self.is_empty() {
@@ -714,13 +715,13 @@ mod tests {
     }
 
     #[test]
-    fn test_top_and_pop() {
+    fn test_peek_and_pop() {
         let data = vec!(2u, 4, 6, 2, 1, 8, 10, 3, 5, 7, 0, 9, 1);
         let mut sorted = data.clone();
         sorted.sort();
         let mut heap = BinaryHeap::from_vec(data);
         while !heap.is_empty() {
-            assert_eq!(heap.top().unwrap(), sorted.last().unwrap());
+            assert_eq!(heap.peek().unwrap(), sorted.last().unwrap());
             assert_eq!(heap.pop().unwrap(), sorted.pop().unwrap());
         }
     }
@@ -729,44 +730,44 @@ mod tests {
     fn test_push() {
         let mut heap = BinaryHeap::from_vec(vec!(2i, 4, 9));
         assert_eq!(heap.len(), 3);
-        assert!(*heap.top().unwrap() == 9);
+        assert!(*heap.peek().unwrap() == 9);
         heap.push(11);
         assert_eq!(heap.len(), 4);
-        assert!(*heap.top().unwrap() == 11);
+        assert!(*heap.peek().unwrap() == 11);
         heap.push(5);
         assert_eq!(heap.len(), 5);
-        assert!(*heap.top().unwrap() == 11);
+        assert!(*heap.peek().unwrap() == 11);
         heap.push(27);
         assert_eq!(heap.len(), 6);
-        assert!(*heap.top().unwrap() == 27);
+        assert!(*heap.peek().unwrap() == 27);
         heap.push(3);
         assert_eq!(heap.len(), 7);
-        assert!(*heap.top().unwrap() == 27);
+        assert!(*heap.peek().unwrap() == 27);
         heap.push(103);
         assert_eq!(heap.len(), 8);
-        assert!(*heap.top().unwrap() == 103);
+        assert!(*heap.peek().unwrap() == 103);
     }
 
     #[test]
     fn test_push_unique() {
         let mut heap = BinaryHeap::from_vec(vec!(box 2i, box 4, box 9));
         assert_eq!(heap.len(), 3);
-        assert!(*heap.top().unwrap() == box 9);
+        assert!(*heap.peek().unwrap() == box 9);
         heap.push(box 11);
         assert_eq!(heap.len(), 4);
-        assert!(*heap.top().unwrap() == box 11);
+        assert!(*heap.peek().unwrap() == box 11);
         heap.push(box 5);
         assert_eq!(heap.len(), 5);
-        assert!(*heap.top().unwrap() == box 11);
+        assert!(*heap.peek().unwrap() == box 11);
         heap.push(box 27);
         assert_eq!(heap.len(), 6);
-        assert!(*heap.top().unwrap() == box 27);
+        assert!(*heap.peek().unwrap() == box 27);
         heap.push(box 3);
         assert_eq!(heap.len(), 7);
-        assert!(*heap.top().unwrap() == box 27);
+        assert!(*heap.peek().unwrap() == box 27);
         heap.push(box 103);
         assert_eq!(heap.len(), 8);
-        assert!(*heap.top().unwrap() == box 103);
+        assert!(*heap.peek().unwrap() == box 103);
     }
 
     #[test]
@@ -831,9 +832,9 @@ mod tests {
     }
 
     #[test]
-    fn test_empty_top() {
+    fn test_empty_peek() {
         let empty = BinaryHeap::<int>::new();
-        assert!(empty.top().is_none());
+        assert!(empty.peek().is_none());
     }
 
     #[test]

src/libcollections/dlist.rs

@@ -451,31 +451,31 @@ impl<T> DList<T> {
     /// Provides a reference to the front element, or `None` if the list is
     /// empty.
     #[inline]
-    #[unstable = "matches collection reform specification, waiting for dust to settle"]
+    #[stable]
     pub fn front(&self) -> Option<&T> {
         self.list_head.as_ref().map(|head| &head.value)
     }
 
     /// Provides a mutable reference to the front element, or `None` if the list
     /// is empty.
     #[inline]
-    #[unstable = "matches collection reform specification, waiting for dust to settle"]
+    #[stable]
     pub fn front_mut(&mut self) -> Option<&mut T> {
         self.list_head.as_mut().map(|head| &mut head.value)
     }
 
     /// Provides a reference to the back element, or `None` if the list is
     /// empty.
     #[inline]
-    #[unstable = "matches collection reform specification, waiting for dust to settle"]
+    #[stable]
     pub fn back(&self) -> Option<&T> {
         self.list_tail.resolve_immut().as_ref().map(|tail| &tail.value)
     }
 
     /// Provides a mutable reference to the back element, or `None` if the list
     /// is empty.
     #[inline]
-    #[unstable = "matches collection reform specification, waiting for dust to settle"]
+    #[stable]
     pub fn back_mut(&mut self) -> Option<&mut T> {
         self.list_tail.resolve().map(|tail| &mut tail.value)
     }

src/libcollections/ring_buf.rs

@@ -228,6 +228,7 @@ impl<T> RingBuf<T> {
     /// assert_eq!(buf[0], 5);
     /// assert_eq!(buf[2], 3);
     /// ```
+    #[stable]
     pub fn swap(&mut self, i: uint, j: uint) {
         assert!(i < self.len());
         assert!(j < self.len());
@@ -546,7 +547,7 @@ impl<T> RingBuf<T> {
     /// d.push_back(2i);
     /// assert_eq!(d.front(), Some(&1i));
     /// ```
-    #[unstable = "matches collection reform specification, waiting for dust to settle"]
+    #[stable]
     pub fn front(&self) -> Option<&T> {
         if !self.is_empty() { Some(&self[0]) } else { None }
     }
@@ -570,7 +571,7 @@ impl<T> RingBuf<T> {
     /// }
     /// assert_eq!(d.front(), Some(&9i));
     /// ```
-    #[unstable = "matches collection reform specification, waiting for dust to settle"]
+    #[stable]
     pub fn front_mut(&mut self) -> Option<&mut T> {
         if !self.is_empty() { Some(&mut self[0]) } else { None }
     }
@@ -590,7 +591,7 @@ impl<T> RingBuf<T> {
     /// d.push_back(2i);
     /// assert_eq!(d.back(), Some(&2i));
     /// ```
-    #[unstable = "matches collection reform specification, waiting for dust to settle"]
+    #[stable]
     pub fn back(&self) -> Option<&T> {
         if !self.is_empty() { Some(&self[self.len() - 1]) } else { None }
     }
@@ -614,7 +615,7 @@ impl<T> RingBuf<T> {
     /// }
     /// assert_eq!(d.back(), Some(&9i));
     /// ```
-    #[unstable = "matches collection reform specification, waiting for dust to settle"]
+    #[stable]
     pub fn back_mut(&mut self) -> Option<&mut T> {
         let len = self.len();
         if !self.is_empty() { Some(&mut self[len - 1]) } else { None }