Clean up API in preparation for future 2.0 release (#15)

* Rename num_entries to len, and evict_all to clear

Change the names of these methods to be more consistent with other Rust
libraries.  The old names are still available but marked as deprecated.
They will be removed in the next major release.

* Deprecate `front` and `front_mut`.

These methods are not useful for external code, and will be made private
in the next major release.

* Bump version to 1.1.0

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "uluru"
-version = "1.0.0"
+version = "1.1.0"
 authors = ["The Servo Project Developers", "Matt Brubeck <mbrubeck@limpet.net>"]
 license = "MPL-2.0"
 description = "A simple, fast, LRU cache implementation"

lib.rs

@@ -108,16 +108,25 @@ where
     A: Array<Item = Entry<T>>,
 {
     /// Returns the number of elements in the cache.
-    pub fn num_entries(&self) -> usize {
+    pub fn len(&self) -> usize {
         self.entries.len()
     }
 
+    /// Returns the number of elements in the cache.
+    #[inline]
+    #[deprecated = "Use the 'len' method instead."]
+    pub fn num_entries(&self) -> usize {
+        self.len()
+    }
+
     /// Returns the front entry in the list (most recently used).
+    #[deprecated = "Private implementation detail. Will be removed in a future release."]
     pub fn front(&self) -> Option<&T> {
         self.entries.get(self.head as usize).map(|e| &e.val)
     }
 
     /// Returns a mutable reference to the front entry in the list (most recently used).
+    #[deprecated = "Private implementation detail. Will be removed in a future release."]
     pub fn front_mut(&mut self) -> Option<&mut T> {
         self.entries.get_mut(self.head as usize).map(|e| &mut e.val)
     }
@@ -169,6 +178,7 @@ where
         F: FnMut(&T) -> bool,
     {
         if self.touch(pred) {
+            #[allow(deprecated)]
             self.front_mut()
         } else {
             None
@@ -200,10 +210,17 @@ where
     }
 
     /// Evict all elements from the cache.
-    pub fn evict_all(&mut self) {
+    pub fn clear(&mut self) {
         self.entries.clear();
     }
 
+    /// Evict all elements from the cache.
+    #[inline]
+    #[deprecated = "Use the 'clear' method instead."]
+    pub fn evict_all(&mut self) {
+        self.clear();
+    }
+
     /// Iterate mutably over the contents of this cache.
     fn iter_mut(&mut self) -> IterMut<A> {
         IterMut {

tests.rs

@@ -22,29 +22,29 @@ where
 #[test]
 fn empty() {
     let mut cache = TestCache::default();
-    assert_eq!(cache.num_entries(), 0);
+    assert_eq!(cache.len(), 0);
     assert_eq!(items(&mut cache), []);
 }
 
 #[test]
 fn insert() {
     let mut cache = TestCache::default();
     cache.insert(1);
-    assert_eq!(cache.num_entries(), 1);
+    assert_eq!(cache.len(), 1);
     cache.insert(2);
-    assert_eq!(cache.num_entries(), 2);
+    assert_eq!(cache.len(), 2);
     cache.insert(3);
-    assert_eq!(cache.num_entries(), 3);
+    assert_eq!(cache.len(), 3);
     cache.insert(4);
-    assert_eq!(cache.num_entries(), 4);
+    assert_eq!(cache.len(), 4);
     assert_eq!(
         items(&mut cache),
         [4, 3, 2, 1],
         "Ordered from most- to least-recent."
     );
 
     cache.insert(5);
-    assert_eq!(cache.num_entries(), 4);
+    assert_eq!(cache.len(), 4);
     assert_eq!(
         items(&mut cache),
         [5, 4, 3, 2],
@@ -85,18 +85,18 @@ fn lookup() {
 }
 
 #[test]
-fn evict_all() {
+fn clear() {
     let mut cache = TestCache::default();
     cache.insert(1);
-    cache.evict_all();
+    cache.clear();
     assert_eq!(items(&mut cache), [], "all items evicted");
 
     cache.insert(1);
     cache.insert(2);
     cache.insert(3);
     cache.insert(4);
     assert_eq!(items(&mut cache), [4, 3, 2, 1]);
-    cache.evict_all();
+    cache.clear();
     assert_eq!(items(&mut cache), [], "all items evicted again");
 }
 
@@ -163,6 +163,7 @@ fn find(num: i32) {
 }
 
 #[quickcheck]
+#[allow(deprecated)]
 fn front(num: i32) {
     let first = num;
     let second = num + 1;