lru-rs

Use these methods to inspect or modify the cache constraints:

• len(): Returns the current number of key-value pairs.
• is_empty(): Returns true if the cache contains no items.
• cap(): Returns the maximum capacity (NonZeroUsize).
• resize(new_cap): Changes the capacity. If the new capacity is smaller than the current size, excess entries are evicted starting from the LRU position.

use lru::LruCache;
use std::num::NonZeroUsize;
let mut cache: LruCache<isize, &str> = LruCache::new(NonZeroUsize::new(2).unwrap());

cache.put(1, "a");
cache.resize(NonZeroUsize::new(4).unwrap());
assert_eq!(cache.cap().get(), 4);

The LruCache supports several iteration patterns:

• iter(): Returns an iterator over (&K, &V) pairs, typically from MRU to LRU.
• iter_mut(): Returns an iterator over (&K, &mut V) pairs.
• into_iter(): Consumes the cache and returns an iterator over (K, V) pairs.
• next_back(): Available on iterators to traverse in reverse order (LRU to MRU).

let mut cache = LruCache::new(NonZeroUsize::new(3).unwrap());
cache.put("a", 1);
cache.put("b", 2);

for (key, value) in cache.iter() {
    println!("{}: {}", key, value);
}

To remove items based on their usage order:

• pop_lru(): Removes and returns the least recently used item (the oldest).
• pop_mru(): Removes and returns the most recently used item (the newest).

let mut cache = LruCache::new(NonZeroUsize::new(2).unwrap());
cache.put(1, "a");
cache.put(2, "b");

let oldest = cache.pop_lru(); // Some((1, "a"))
let newest = cache.pop_mru(); // Some((2, "b"))

Access values in the cache without changing their LRU position using get(&key). To modify a value in place, use get_mut(&key). Both methods return an Option containing a reference to the value. Note that get and get_mut do not change the order of elements in the LRU list; use peek or find_and_promote if you need to change the order.

let mut cache = LruCache::new(NonZeroUsize::new(2).unwrap());
cache.put("apple", 1);

// Read access
let val = cache.get(&"apple"); // Some(&1)

// Mutable access
if let Some(v) = cache.get_mut(&"apple") {
    *v = 2;
}

The try_get_or_insert_mut_ref method allows querying the cache using a borrowed type Q that can be converted into the owned key type K. If the key is missing, the provided closure f is called to produce a value. This method is efficient for types like Rc<String> because it minimizes cloning of the key.

use lru::LruCache;
use std::num::NonZeroUsize;
use std::rc::Rc;

let key2 = Rc::new("2".to_owned());
let mut cache = LruCache::<Rc<String>, String>::new(NonZeroUsize::new(2).unwrap());
let b = || -> Result<String, ()> { Ok("Two".to_owned()) };

if let Ok(v) = cache.try_get_or_insert_mut_ref(&key2, b) {
    *v = "New two".to_owned();
}

You can manually manipulate the LRU order of specific keys:

• promote(&k): Moves the key to the most recently used position. Returns true if the key existed and was promoted.
• demote(&k): Moves the key to the least recently used position. Returns true if the key existed and was demoted.

use lru::LruCache;
use std::num::NonZeroUsize;
let mut cache = LruCache::new(NonZeroUsize::new(3).unwrap());

cache.put(1, "a");
cache.put(2, "b");
cache.put(3, "c");

assert!(cache.promote(&3)); // 3 is now MRU
assert!(cache.demote(&1)); // 1 is now LRU

Use pop(&key) to remove a specific key and return its value. Use pop_entry(&key) to remove a specific key and return both the key and the value as a tuple. Both methods return an Option.

let mut cache = LruCache::new(NonZeroUsize::new(2).unwrap());
cache.put("apple", "red");

let val = cache.pop(&"apple"); // Some("red")
let entry = cache.pop_entry(&"apple"); // Some(("apple", "red"))

Several methods allow removing items from the cache:

• pop(&k): Removes and returns the value Option<V> for the given key.
• pop_entry(&k): Removes and returns both the key and value Option<(K, V)> for the given key.
• pop_lru(): Removes and returns the least recently used key-value pair Option<(K, V)>.
• pop_mru(): Removes and returns the most recently used key-value pair Option<(K, V)>.
• clear(): Removes all entries from the cache.

use lru::LruCache;
use std::num::NonZeroUsize;
let mut cache = LruCache::new(NonZeroUsize::new(2).unwrap());

cache.put(2, "a");
assert_eq!(cache.pop(&2), Some("a"));
assert_eq!(cache.pop(&2), None);

If a key is missing from the cache, try_get_or_insert_mut_with_key uses a provided closure to generate a value. The closure receives a reference to the key. If the closure succeeds, the new value is inserted into the cache and a mutable reference is returned. If the closure returns an error, the error is returned. If the key already exists, it is moved to the head of the LRU list and a mutable reference to the existing value is returned.

use lru::LruCache;
use std::num::NonZeroUsize;
let mut cache = LruCache::new(NonZeroUsize::new(2).unwrap());

cache.put("Two", 3);

let len = |k: &&str| -> Result<usize, String> { Ok(k.len()) };
assert_eq!(cache.try_get_or_insert_mut_with_key("Two", len), Ok(&mut 3));