auto merge of #15611 : brson/rust/pushpop, r=alexcrichton

This fixes naming conventions for `push`/`pop` from either end of a structure by partially implementing @erickt's suggestion from #10852 (comment), namely:

* push/pop from the 'back' are called `push` and `pop`.
* push/pop from the 'front' are called `push_front` and `pop_front`.
* `push`/`pop` are declared on the `MutableSeq` trait.
* Implement `MutableSeq` for `Vec`, `DList`, and `RingBuf`.
* Add `MutableSeq` to the prelude.

I did not make any further refactorings because there is some more extensive thought that needs to be put into the collections traits. This is an easy first step that should close #10852.

I left the `push_back` and `pop_back` methods on `DList` and `RingBuf` deprecated. Because `MutableSeq` is in the prelude it shouldn't break many, but it is a breaking change.

Author: bors

src/compiletest/runtest.rs

@@ -1178,7 +1178,7 @@ fn make_run_args(config: &Config, props: &TestProps, testfile: &Path) ->
     // Add the arguments in the run_flags directive
     args.push_all_move(split_maybe_args(&props.run_flags));
 
-    let prog = args.shift().unwrap();
+    let prog = args.remove(0).unwrap();
     return ProcArgs {
         prog: prog,
         args: args,

src/etc/vim/syntax/rust.vim

@@ -100,7 +100,7 @@ syn keyword rustTrait Clone
 syn keyword rustTrait PartialEq PartialOrd Eq Ord Equiv
 syn keyword rustEnum Ordering
 syn keyword rustEnumVariant Less Equal Greater
-syn keyword rustTrait Collection Mutable Map MutableMap
+syn keyword rustTrait Collection Mutable Map MutableMap MutableSeq
 syn keyword rustTrait Set MutableSet
 syn keyword rustTrait FromIterator Extendable ExactSize
 syn keyword rustTrait Iterator DoubleEndedIterator

src/liballoc/arc.rs

@@ -268,6 +268,7 @@ impl<T: Share + Send> Drop for Weak<T> {
 #[allow(experimental)]
 mod tests {
     use std::clone::Clone;
+    use std::collections::MutableSeq;
     use std::comm::channel;
     use std::mem::drop;
     use std::ops::Drop;

src/libcollections/bitv.rs

@@ -72,7 +72,7 @@ use core::slice;
 use core::uint;
 use std::hash;
 
-use {Collection, Mutable, Set, MutableSet};
+use {Collection, Mutable, Set, MutableSet, MutableSeq};
 use vec::Vec;
 
 
@@ -1574,7 +1574,7 @@ mod tests {
     use std::rand::Rng;
     use test::Bencher;
 
-    use {Set, Mutable, MutableSet};
+    use {Set, Mutable, MutableSet, MutableSeq};
     use bitv::{Bitv, BitvSet, from_fn, from_bytes};
     use bitv;
     use vec::Vec;

src/libcollections/btree.rs

@@ -24,7 +24,7 @@ use alloc::boxed::Box;
 use core::fmt;
 use core::fmt::Show;
 
-use Collection;
+use {Collection, MutableSeq};
 use vec::Vec;
 
 #[allow(missing_doc)]
@@ -782,6 +782,8 @@ mod test_btree {
 
     use super::{BTree, Node, LeafElt};
 
+    use MutableSeq;
+
     //Tests the functionality of the insert methods (which are unfinished).
     #[test]
     fn insert_test_one() {

src/libcollections/dlist.rs

@@ -30,7 +30,7 @@ use core::iter;
 use core::mem;
 use core::ptr;
 
-use {Collection, Mutable, Deque};
+use {Collection, Mutable, Deque, MutableSeq};
 
 /// A doubly-linked list.
 pub struct DList<T> {
@@ -249,18 +249,13 @@ impl<T> Deque<T> for DList<T> {
     fn pop_front(&mut self) -> Option<T> {
         self.pop_front_node().map(|box Node{value, ..}| value)
     }
+}
 
-    /// Add an element last in the list
-    ///
-    /// O(1)
-    fn push_back(&mut self, elt: T) {
+impl<T> MutableSeq<T> for DList<T> {
+    fn push(&mut self, elt: T) {
         self.push_back_node(box Node::new(elt))
     }
-
-    /// Remove the last element and return it, or None if the list is empty
-    ///
-    /// O(1)
-    fn pop_back(&mut self) -> Option<T> {
+    fn pop(&mut self) -> Option<T> {
         self.pop_back_node().map(|box Node{value, ..}| value)
     }
 }
@@ -284,12 +279,12 @@ impl<T> DList<T> {
     /// # Example
     ///
     /// ```rust
-    /// use std::collections::{DList, Deque};
+    /// use std::collections::DList;
     ///
     /// let mut dl = DList::new();
-    /// dl.push_back(1i);
-    /// dl.push_back(2);
-    /// dl.push_back(3);
+    /// dl.push(1i);
+    /// dl.push(2);
+    /// dl.push(3);
     ///
     /// dl.rotate_forward();
     ///
@@ -311,12 +306,12 @@ impl<T> DList<T> {
     /// # Example
     ///
     /// ```rust
-    /// use std::collections::{DList, Deque};
+    /// use std::collections::DList;
     ///
     /// let mut dl = DList::new();
-    /// dl.push_back(1i);
-    /// dl.push_back(2);
-    /// dl.push_back(3);
+    /// dl.push(1i);
+    /// dl.push(2);
+    /// dl.push(3);
     ///
     /// dl.rotate_backward();
     ///
@@ -338,14 +333,14 @@ impl<T> DList<T> {
     /// # Example
     ///
     /// ```rust
-    /// use std::collections::{DList, Deque};
+    /// use std::collections::DList;
     ///
     /// let mut a = DList::new();
     /// let mut b = DList::new();
-    /// a.push_back(1i);
-    /// a.push_back(2);
-    /// b.push_back(3i);
-    /// b.push_back(4);
+    /// a.push(1i);
+    /// a.push(2);
+    /// b.push(3i);
+    /// b.push(4);
     ///
     /// a.append(b);
     ///
@@ -379,14 +374,14 @@ impl<T> DList<T> {
     /// # Example
     ///
     /// ```rust
-    /// use std::collections::{DList, Deque};
+    /// use std::collections::DList;
     ///
     /// let mut a = DList::new();
     /// let mut b = DList::new();
-    /// a.push_back(1i);
-    /// a.push_back(2);
-    /// b.push_back(3i);
-    /// b.push_back(4);
+    /// a.push(1i);
+    /// a.push(2);
+    /// b.push(3i);
+    /// b.push(4);
     ///
     /// a.prepend(b);
     ///
@@ -408,13 +403,13 @@ impl<T> DList<T> {
     /// # Example
     ///
     /// ```rust
-    /// use std::collections::{DList, Deque};
+    /// use std::collections::DList;
     ///
     /// let mut a: DList<int> = DList::new();
-    /// a.push_back(2i);
-    /// a.push_back(4);
-    /// a.push_back(7);
-    /// a.push_back(8);
+    /// a.push(2i);
+    /// a.push(4);
+    /// a.push(7);
+    /// a.push(8);
     ///
     /// // insert 11 before the first odd number in the list
     /// a.insert_when(11, |&e, _| e % 2 == 1);
@@ -719,7 +714,7 @@ mod tests {
     use test::Bencher;
     use test;
 
-    use Deque;
+    use {Deque, MutableSeq};
     use super::{DList, Node, ListInsertion};
     use vec::Vec;
 

src/libcollections/enum_set.rs

@@ -141,6 +141,8 @@ mod test {
 
     use enum_set::{EnumSet, CLike};
 
+    use MutableSeq;
+
     #[deriving(PartialEq, Show)]
     #[repr(uint)]
     enum Foo {

src/libcollections/hash/sip.rs

@@ -281,6 +281,8 @@ mod tests {
     use super::super::{Hash, Writer};
     use super::{SipState, hash, hash_with_keys};
 
+    use MutableSeq;
+
     // Hash just the bytes of the slice, without length prefix
     struct Bytes<'a>(&'a [u8]);
 

src/libcollections/lib.rs

@@ -325,6 +325,30 @@ pub trait MutableSet<T>: Set<T> + Mutable {
     fn remove(&mut self, value: &T) -> bool;
 }
 
+pub trait MutableSeq<T>: Mutable {
+    /// Append an element to the back of a collection.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// let mut vec = vec!(1i, 2);
+    /// vec.push(3);
+    /// assert_eq!(vec, vec!(1, 2, 3));
+    /// ```
+    fn push(&mut self, t: T);
+    /// Remove the last element from a collection and return it, or `None` if it is
+    /// empty.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// let mut vec = vec!(1i, 2, 3);
+    /// assert_eq!(vec.pop(), Some(3));
+    /// assert_eq!(vec, vec!(1, 2));
+    /// ```
+    fn pop(&mut self) -> Option<T>;
+}
+
 /// A double-ended sequence that allows querying, insertion and deletion at both
 /// ends.
 ///
@@ -336,9 +360,9 @@ pub trait MutableSet<T>: Set<T> + Mutable {
 /// use std::collections::{RingBuf, Deque};
 ///
 /// let mut queue = RingBuf::new();
-/// queue.push_back(1i);
-/// queue.push_back(2i);
-/// queue.push_back(3i);
+/// queue.push(1i);
+/// queue.push(2i);
+/// queue.push(3i);
 ///
 /// // Will print 1, 2, 3
 /// while !queue.is_empty() {
@@ -374,17 +398,17 @@ pub trait MutableSet<T>: Set<T> + Mutable {
 /// // Init deque with 1, 2, 3, 4
 /// deque.push_front(2i);
 /// deque.push_front(1i);
-/// deque.push_back(3i);
-/// deque.push_back(4i);
+/// deque.push(3i);
+/// deque.push(4i);
 ///
 /// // Will print (1, 4) and (2, 3)
 /// while !deque.is_empty() {
 ///     let f = deque.pop_front().unwrap();
-///     let b = deque.pop_back().unwrap();
+///     let b = deque.pop().unwrap();
 ///     println!("{}", (f, b));
 /// }
 /// ```
-pub trait Deque<T> : Mutable {
+pub trait Deque<T> : MutableSeq<T> {
     /// Provide a reference to the front element, or `None` if the sequence is
     /// empty.
     ///
@@ -396,8 +420,8 @@ pub trait Deque<T> : Mutable {
     /// let mut d = RingBuf::new();
     /// assert_eq!(d.front(), None);
     ///
-    /// d.push_back(1i);
-    /// d.push_back(2i);
+    /// d.push(1i);
+    /// d.push(2i);
     /// assert_eq!(d.front(), Some(&1i));
     /// ```
     fn front<'a>(&'a self) -> Option<&'a T>;
@@ -413,8 +437,8 @@ pub trait Deque<T> : Mutable {
     /// let mut d = RingBuf::new();
     /// assert_eq!(d.front_mut(), None);
     ///
-    /// d.push_back(1i);
-    /// d.push_back(2i);
+    /// d.push(1i);
+    /// d.push(2i);
     /// match d.front_mut() {
     ///     Some(x) => *x = 9i,
     ///     None => (),
@@ -434,8 +458,8 @@ pub trait Deque<T> : Mutable {
     /// let mut d = DList::new();
     /// assert_eq!(d.back(), None);
     ///
-    /// d.push_back(1i);
-    /// d.push_back(2i);
+    /// d.push(1i);
+    /// d.push(2i);
     /// assert_eq!(d.back(), Some(&2i));
     /// ```
     fn back<'a>(&'a self) -> Option<&'a T>;
@@ -451,8 +475,8 @@ pub trait Deque<T> : Mutable {
     /// let mut d = DList::new();
     /// assert_eq!(d.back(), None);
     ///
-    /// d.push_back(1i);
-    /// d.push_back(2i);
+    /// d.push(1i);
+    /// d.push(2i);
     /// match d.back_mut() {
     ///     Some(x) => *x = 9i,
     ///     None => (),
@@ -479,21 +503,22 @@ pub trait Deque<T> : Mutable {
     ///
     /// # Example
     ///
-    /// ```
+    /// ```ignore
     /// use std::collections::{DList, Deque};
     ///
     /// let mut d = DList::new();
     /// d.push_back(1i);
     /// d.push_back(2i);
     /// assert_eq!(d.front(), Some(&1i));
     /// ```
-    fn push_back(&mut self, elt: T);
+    #[deprecated = "use the `push` method"]
+    fn push_back(&mut self, elt: T) { self.push(elt) }
 
     /// Remove the last element and return it, or `None` if the sequence is empty.
     ///
     /// # Example
     ///
-    /// ```
+    /// ```ignore
     /// use std::collections::{RingBuf, Deque};
     ///
     /// let mut d = RingBuf::new();
@@ -504,7 +529,8 @@ pub trait Deque<T> : Mutable {
     /// assert_eq!(d.pop_back(), Some(1i));
     /// assert_eq!(d.pop_back(), None);
     /// ```
-    fn pop_back(&mut self) -> Option<T>;
+    #[deprecated = "use the `pop` method"]
+    fn pop_back(&mut self) -> Option<T> { self.pop() }
 
     /// Remove the first element and return it, or `None` if the sequence is empty.
     ///
@@ -514,8 +540,8 @@ pub trait Deque<T> : Mutable {
     /// use std::collections::{RingBuf, Deque};
     ///
     /// let mut d = RingBuf::new();
-    /// d.push_back(1i);
-    /// d.push_back(2i);
+    /// d.push(1i);
+    /// d.push(2i);
     ///
     /// assert_eq!(d.pop_front(), Some(1i));
     /// assert_eq!(d.pop_front(), Some(2i));
@@ -535,4 +561,8 @@ mod std {
     pub use core::clone;    // deriving(Clone)
     pub use core::cmp;      // deriving(Eq, Ord, etc.)
     pub use hash;           // deriving(Hash)
+
+    pub mod collections {
+        pub use MutableSeq;
+    }
 }

src/libcollections/priority_queue.rs

@@ -154,7 +154,7 @@ use core::default::Default;
 use core::mem::{zeroed, replace, swap};
 use core::ptr;
 
-use {Collection, Mutable};
+use {Collection, Mutable, MutableSeq};
 use slice;
 use vec::Vec;
 
@@ -388,6 +388,7 @@ mod tests {
 
     use priority_queue::PriorityQueue;
     use vec::Vec;
+    use MutableSeq;
 
     #[test]
     fn test_iterator() {