core: Move the collections traits to libcollections

This commit moves Mutable, Map, MutableMap, Set, and MutableSet from
`core::collections` to the `collections` crate at the top-level. Additionally,
this removes the `deque` module and moves the `Deque` trait to only being
available at the top-level of the collections crate.

All functionality continues to be reexported through `std::collections`.

[breaking-change]

Author: alexcrichton

src/libcollections/bitv.rs

@@ -20,6 +20,7 @@ use core::slice;
 use core::uint;
 use std::hash;
 
+use {Collection, Mutable, Set, MutableSet};
 use vec::Vec;
 
 #[deriving(Clone)]
@@ -1008,6 +1009,7 @@ mod tests {
     use std::rand::Rng;
     use test::Bencher;
 
+    use {Set, Mutable, MutableSet};
     use bitv::{Bitv, SmallBitv, BigBitv, BitvSet, from_bools, from_fn,
                from_bytes};
     use bitv;

src/libcollections/btree.rs

@@ -24,6 +24,7 @@ use alloc::owned::Box;
 use core::fmt;
 use core::fmt::Show;
 
+use Collection;
 use vec::Vec;
 
 #[allow(missing_doc)]

src/libcollections/deque.rs

@@ -10,41 +10,13 @@
 
 //! Container traits for collections
 
-use core::prelude::*;
-
-/// A double-ended sequence that allows querying, insertion and deletion at both ends.
-pub trait Deque<T> : Mutable {
-    /// Provide a reference to the front element, or None if the sequence is empty
-    fn front<'a>(&'a self) -> Option<&'a T>;
-
-    /// Provide a mutable reference to the front element, or None if the sequence is empty
-    fn front_mut<'a>(&'a mut self) -> Option<&'a mut T>;
-
-    /// Provide a reference to the back element, or None if the sequence is empty
-    fn back<'a>(&'a self) -> Option<&'a T>;
-
-    /// Provide a mutable reference to the back element, or None if the sequence is empty
-    fn back_mut<'a>(&'a mut self) -> Option<&'a mut T>;
-
-    /// Insert an element first in the sequence
-    fn push_front(&mut self, elt: T);
-
-    /// Insert an element last in the sequence
-    fn push_back(&mut self, elt: T);
-
-    /// Remove the last element and return it, or None if the sequence is empty
-    fn pop_back(&mut self) -> Option<T>;
-
-    /// Remove the first element and return it, or None if the sequence is empty
-    fn pop_front(&mut self) -> Option<T>;
-}
-
 #[cfg(test)]
 pub mod bench {
     use std::prelude::*;
     use std::rand;
     use std::rand::Rng;
     use test::Bencher;
+    use MutableMap;
 
     pub fn insert_rand_n<M:MutableMap<uint,uint>>(n: uint,
                                                   map: &mut M,
@@ -121,3 +93,4 @@ pub mod bench {
         })
      }
 }
+

src/libcollections/dlist.rs

@@ -13,7 +13,7 @@
 //! The DList allows pushing and popping elements at either end.
 //!
 //! DList implements the trait Deque. It should be imported with `use
-//! collections::deque::Deque`.
+//! collections::Deque`.
 
 // DList is constructed like a singly-linked list over the field `next`.
 // including the last link being None; each Node owns its `next` field.
@@ -29,7 +29,7 @@ use core::iter;
 use core::mem;
 use core::ptr;
 
-use deque::Deque;
+use {Collection, Mutable, Deque};
 
 /// A doubly-linked list.
 pub struct DList<T> {
@@ -629,7 +629,7 @@ mod tests {
     use test::Bencher;
     use test;
 
-    use deque::Deque;
+    use Deque;
     use super::{DList, Node, ListInsertion};
     use vec::Vec;
 

src/libcollections/lib.rs

@@ -32,9 +32,11 @@ extern crate alloc;
 #[cfg(test)] #[phase(syntax, link)] extern crate std;
 #[cfg(test)] #[phase(syntax, link)] extern crate log;
 
+use core::prelude::*;
+
+pub use core::collections::Collection;
 pub use bitv::{Bitv, BitvSet};
 pub use btree::BTree;
-pub use deque::Deque;
 pub use dlist::DList;
 pub use enum_set::EnumSet;
 pub use priority_queue::PriorityQueue;
@@ -47,7 +49,6 @@ mod macros;
 
 pub mod bitv;
 pub mod btree;
-pub mod deque;
 pub mod dlist;
 pub mod enum_set;
 pub mod priority_queue;
@@ -64,12 +65,120 @@ pub mod hash;
 // Internal unicode fiddly bits for the str module
 mod unicode;
 
-// FIXME(#14008) should this actually exist, or should a method be added?
-fn expect<T>(a: core::option::Option<T>, b: &str) -> T {
-    match a {
-        core::option::Some(a) => a,
-        core::option::None => fail!("{}", b),
+mod deque;
+
+/// A trait to represent mutable containers
+pub trait Mutable: Collection {
+    /// Clear the container, removing all values.
+    fn clear(&mut self);
+}
+
+/// A map is a key-value store where values may be looked up by their keys. This
+/// trait provides basic operations to operate on these stores.
+pub trait Map<K, V>: Collection {
+    /// Return a reference to the value corresponding to the key
+    fn find<'a>(&'a self, key: &K) -> Option<&'a V>;
+
+    /// Return true if the map contains a value for the specified key
+    #[inline]
+    fn contains_key(&self, key: &K) -> bool {
+        self.find(key).is_some()
+    }
+}
+
+/// This trait provides basic operations to modify the contents of a map.
+pub trait MutableMap<K, V>: Map<K, V> + Mutable {
+    /// Insert a key-value pair into the map. An existing value for a
+    /// key is replaced by the new value. Return true if the key did
+    /// not already exist in the map.
+    #[inline]
+    fn insert(&mut self, key: K, value: V) -> bool {
+        self.swap(key, value).is_none()
+    }
+
+    /// Remove a key-value pair from the map. Return true if the key
+    /// was present in the map, otherwise false.
+    #[inline]
+    fn remove(&mut self, key: &K) -> bool {
+        self.pop(key).is_some()
+    }
+
+    /// Insert a key-value pair from the map. If the key already had a value
+    /// present in the map, that value is returned. Otherwise None is returned.
+    fn swap(&mut self, k: K, v: V) -> Option<V>;
+
+    /// Removes a key from the map, returning the value at the key if the key
+    /// was previously in the map.
+    fn pop(&mut self, k: &K) -> Option<V>;
+
+    /// Return a mutable reference to the value corresponding to the key
+    fn find_mut<'a>(&'a mut self, key: &K) -> Option<&'a mut V>;
+}
+
+/// A set is a group of objects which are each distinct from one another. This
+/// trait represents actions which can be performed on sets to iterate over
+/// them.
+pub trait Set<T>: Collection {
+    /// Return true if the set contains a value
+    fn contains(&self, value: &T) -> bool;
+
+    /// Return true if the set has no elements in common with `other`.
+    /// This is equivalent to checking for an empty intersection.
+    fn is_disjoint(&self, other: &Self) -> bool;
+
+    /// Return true if the set is a subset of another
+    fn is_subset(&self, other: &Self) -> bool;
+
+    /// Return true if the set is a superset of another
+    fn is_superset(&self, other: &Self) -> bool {
+        other.is_subset(self)
     }
+
+    // FIXME #8154: Add difference, sym. difference, intersection and union iterators
+}
+
+/// This trait represents actions which can be performed on sets to mutate
+/// them.
+pub trait MutableSet<T>: Set<T> + Mutable {
+    /// Add a value to the set. Return true if the value was not already
+    /// present in the set.
+    fn insert(&mut self, value: T) -> bool;
+
+    /// Remove a value from the set. Return true if the value was
+    /// present in the set.
+    fn remove(&mut self, value: &T) -> bool;
+}
+
+/// A double-ended sequence that allows querying, insertion and deletion at both
+/// ends.
+pub trait Deque<T> : Mutable {
+    /// Provide a reference to the front element, or None if the sequence is
+    /// empty
+    fn front<'a>(&'a self) -> Option<&'a T>;
+
+    /// Provide a mutable reference to the front element, or None if the
+    /// sequence is empty
+    fn front_mut<'a>(&'a mut self) -> Option<&'a mut T>;
+
+    /// Provide a reference to the back element, or None if the sequence is
+    /// empty
+    fn back<'a>(&'a self) -> Option<&'a T>;
+
+    /// Provide a mutable reference to the back element, or None if the sequence
+    /// is empty
+    fn back_mut<'a>(&'a mut self) -> Option<&'a mut T>;
+
+    /// Insert an element first in the sequence
+    fn push_front(&mut self, elt: T);
+
+    /// Insert an element last in the sequence
+    fn push_back(&mut self, elt: T);
+
+    /// Remove the last element and return it, or None if the sequence is empty
+    fn pop_back(&mut self) -> Option<T>;
+
+    /// Remove the first element and return it, or None if the sequence is empty
+    fn pop_front(&mut self) -> Option<T>;
 }
 
 // FIXME(#14344) this shouldn't be necessary

src/libcollections/priority_queue.rs

@@ -17,6 +17,7 @@ use core::prelude::*;
 use core::mem::{zeroed, replace, swap};
 use core::ptr;
 
+use {Collection, Mutable};
 use slice;
 use vec::Vec;
 

src/libcollections/ringbuf.rs

@@ -11,15 +11,15 @@
 //! A double-ended queue implemented as a circular buffer
 //!
 //! RingBuf implements the trait Deque. It should be imported with `use
-//! collections::deque::Deque`.
+//! collections::Deque`.
 
 use core::prelude::*;
 
 use core::cmp;
 use core::fmt;
 use core::iter::RandomAccessIterator;
 
-use deque::Deque;
+use {Deque, Collection, Mutable};
 use vec::Vec;
 
 static INITIAL_CAPACITY: uint = 8u; // 2^3
@@ -415,7 +415,7 @@ mod tests {
     use test::Bencher;
     use test;
 
-    use deque::Deque;
+    use {Deque, Mutable};
     use super::RingBuf;
     use vec::Vec;
 

src/libcollections/slice.rs

@@ -109,6 +109,8 @@ use core::mem::transmute;
 use core::mem;
 use core::ptr;
 use core::iter::{range_step, MultiplicativeIterator};
+
+use Collection;
 use vec::Vec;
 
 pub use core::slice::{ref_slice, mut_ref_slice, Splits, Windows};
@@ -296,9 +298,9 @@ impl<'a, T: Clone> CloneableVector<T> for &'a [T] {
 
         let len = self.len();
         let data_size = len.checked_mul(&mem::size_of::<T>());
-        let data_size = ::expect(data_size, "overflow in to_owned()");
+        let data_size = data_size.expect("overflow in to_owned()");
         let size = mem::size_of::<RawVec<()>>().checked_add(&data_size);
-        let size = ::expect(size, "overflow in to_owned()");
+        let size = size.expect("overflow in to_owned()");
 
         unsafe {
             // this should pass the real required alignment
@@ -865,6 +867,7 @@ mod tests {
     use std::rt;
     use slice::*;
 
+    use Mutable;
     use vec::Vec;
 
     fn square(n: uint) -> uint { n * n }

src/libcollections/smallintmap.rs

@@ -21,6 +21,7 @@ use core::fmt;
 use core::iter::{Enumerate, FilterMap};
 use core::mem::replace;
 
+use {Collection, Mutable, Map, MutableMap};
 use {vec, slice};
 use vec::Vec;
 
@@ -123,7 +124,7 @@ impl<V> SmallIntMap<V> {
     }
 
     pub fn get<'a>(&'a self, key: &uint) -> &'a V {
-        ::expect(self.find(key), "key not present")
+        self.find(key).expect("key not present")
     }
 
     /// An iterator visiting all key-value pairs in ascending order by the keys.
@@ -264,6 +265,7 @@ double_ended_iterator!(impl MutEntries -> (uint, &'a mut T), get_mut_ref)
 mod test_map {
     use std::prelude::*;
 
+    use {Map, MutableMap, Mutable};
     use super::SmallIntMap;
 
     #[test]

src/libcollections/str.rs

@@ -76,6 +76,7 @@ use core::cmp;
 use core::iter::AdditiveIterator;
 use core::mem;
 
+use Collection;
 use hash;
 use string::String;
 use vec::Vec;

src/libcollections/string.rs

@@ -18,6 +18,7 @@ use core::mem;
 use core::ptr;
 use core::raw::Slice;
 
+use {Collection, Mutable};
 use hash;
 use str;
 use str::{CharRange, StrAllocating};
@@ -356,6 +357,7 @@ mod tests {
     use std::prelude::*;
     use test::Bencher;
 
+    use Mutable;
     use str::{Str, StrSlice};
     use super::String;
 

src/libcollections/treemap.rs

@@ -22,6 +22,7 @@ use core::iter;
 use core::mem::{replace, swap};
 use core::ptr;
 
+use {Collection, Mutable, Set, MutableSet, MutableMap, Map};
 use vec::Vec;
 
 // This is implemented as an AA tree, which is a simplified variation of
@@ -1006,6 +1007,7 @@ mod test_treemap {
     use std::rand::Rng;
     use std::rand;
 
+    use {Map, MutableMap, Mutable};
     use super::{TreeMap, TreeNode};
 
     #[test]
@@ -1437,7 +1439,6 @@ mod test_treemap {
 
 #[cfg(test)]
 mod bench {
-    use std::prelude::*;
     use test::Bencher;
 
     use super::TreeMap;
@@ -1500,6 +1501,7 @@ mod bench {
 mod test_set {
     use std::prelude::*;
 
+    use {Set, MutableSet, Mutable, MutableMap};
     use super::{TreeMap, TreeSet};
 
     #[test]