From ca1af85ba62a0708fcb2d46d782dd197268e26d4 Mon Sep 17 00:00:00 2001
From: Matt Brubeck <mbrubeck@limpet.net>
Date: Fri, 5 Feb 2021 13:36:59 -0800
Subject: [PATCH] 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 |  2 +-
 lib.rs     | 21 +++++++++++++++++++--
 tests.rs   | 19 ++++++++++---------
 3 files changed, 30 insertions(+), 12 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index e7d9ada..341cddd 100644
--- a/Cargo.toml
+++ b/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"
diff --git a/lib.rs b/lib.rs
index 5956bd0..cdb2611 100644
--- a/lib.rs
+++ b/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 {
diff --git a/tests.rs b/tests.rs
index 516144b..0196f82 100644
--- a/tests.rs
+++ b/tests.rs
@@ -22,7 +22,7 @@ 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), []);
 }
 
@@ -30,13 +30,13 @@ fn empty() {
 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],
@@ -44,7 +44,7 @@ fn insert() {
     );
 
     cache.insert(5);
-    assert_eq!(cache.num_entries(), 4);
+    assert_eq!(cache.len(), 4);
     assert_eq!(
         items(&mut cache),
         [5, 4, 3, 2],
@@ -85,10 +85,10 @@ 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);
@@ -96,7 +96,7 @@ fn evict_all() {
     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;