Added keys, values, and items to allow iteration

3 files changed, 58 insertions, 1 deletions

diff --git a/README.txt b/README.txt
index 6e3b0c3..d2466cb 100644
--- a/README.txt
+++ b/README.txt
@@ -24,6 +24,10 @@ An LRU cache object has a dictionary like interface and can be used in the same
     value = cache[key]  # Lookup a value given its key
     del cache[key]      # Remove a value given its key
 
+    cache.keys()        # Returns the keys in the cache *
+    cache.values()      # Returns the values in the cache *
+    cache.items()       # Returns the key, value pairs in the cache *
+
     cache.size()        # Returns the size of the cache
     cache.size(x)       # Changes the size of the cache. x MUST be greater than
                         # zero.
@@ -33,6 +37,8 @@ An LRU cache object has a dictionary like interface and can be used in the same
 
     cache.clear()       # Remove all elements from the cache.
 
+* These calls have no effect on the cache order.
+
 The lrucache takes an optional callback function as a second argument. Since the cache has a fixed size some operations, such as an insertion, may cause a key/value pair to be ejected. If the optional callback function is given it will be called when this occurs. For example::
 
     import pylru
@@ -91,3 +97,17 @@ PyLRU also provides a function decorator::
         return x*x
 
     # Now results of the square function are cached for future lookup.
+
+To iterate over the cache elements, use .items()::
+
+    import pylru
+
+    cache = pylru.lrucache(size, callback)
+
+    # items() returns a list of key, value pairs without modifying order.
+    for key, val in cache.items():
+      print key, val
+
+    # WARNING: while keys() does not modify order, the cache[key] call does!
+    for key in cache.keys():
+      print key, cache[key]
diff --git a/pylru.py b/pylru.py
index 8015f37..55e4b67 100644
--- a/pylru.py
+++ b/pylru.py
@@ -178,7 +178,23 @@ class lrucache(object):
         self.mtf(node)
         self.head = node.next
 
+    def items(self):
 
+        # return the (key, value) pairs (from most recent to least)
+        # without modifying the cache order
+        return zip(self.keys(), self.values())
+
+    def keys(self):
+
+        # return the keys (from most recent to least) in the cache
+        # does not modify the cache order
+        return self.table.keys()
+
+    def values(self):
+
+        # return the values in the cache (from most recent to least)
+        # does not modify the cache order
+        return [node.obj for node in self.table.values()]
 
     def size(self, size=None):
 
@@ -324,7 +340,6 @@ class lruwrap(object):
             except KeyError:
                 pass
 
-
     def sync(self):
         if self.writeback:
             for key in self.dirty:
diff --git a/test.py b/test.py
index ca107f4..a6d0be3 100644
--- a/test.py
+++ b/test.py
@@ -158,7 +158,28 @@ def testDecorator():
         assert square(x) == x*x
 
 
+def testItems():
+    a = lrucache(128)
+    b = simplelrucache(128)
+
+    for i in range(1000):
+        x = random.randint(0, 512)
+        y = random.randint(0, 512)
+        a[x] = y
+        b[x] = y
+
+    for k, v in a.items():
+        assert k in a
+        assert a[k] == v
+        assert b[k] == v
+
+    # ensure the order returned in items() is correct.
+    items = a.items()
+    for k, v in reversed(items):
+        a[k] = v
 
+    # test the order is returned correctly.
+    assert items == a.items()
 
 
 if __name__ == '__main__':
@@ -172,5 +193,6 @@ if __name__ == '__main__':
         wraptest2()
         wraptest3()
         testDecorator()
+        testItems()