Struct LruHashMap

Source

pub struct LruHashMap<K, V> { /* private fields */ }

Expand description

A Least Recently Used (LRU) cache implemented on top of HashMap and DoublyLinkedList list.

The LruHashMap maintains a maximum number of entries. When the cache is full and a new entry is inserted, the least recently used entry is removed.

§Type Parameters

K: The type of keys in the cache. Must implement Hash and Eq.
V: The type of values in the cache.

§Examples

use lru_st::collections::LruHashMap;

let mut cache = LruHashMap::with_max_entries(2);
cache.insert("a", 1);
cache.insert("b", 2);
assert_eq!(cache.get(&"a"), Some(&1));
cache.insert("c", 3);
assert_eq!(cache.get(&"a"), Some(&1));
assert_eq!(cache.get(&"b"), None); // "b" was evicted

Implementations§

Source §

impl<K, V> LruHashMap<K, V>
where K: Hash + Eq,

Source

pub fn with_max_entries(max_entries: usize) -> Self

Creates a new, empty LruHashMap with the specified maximum number of entries.

§Arguments

max_entries - The maximum number of entries the cache can hold.

§Examples

use lru_st::collections::LruHashMap;

let mut cache = LruHashMap::with_max_entries(2);
cache.insert("a", 1);
cache.insert("b", 2);
assert_eq!(cache.get(&"a"), Some(&1));
cache.insert("c", 3);
assert_eq!(cache.get(&"a"), Some(&1));
assert_eq!(cache.get(&"b"), None); // "b" was evicted

Source

pub fn get(&mut self, k: &K) -> Option<&V>

Returns a reference to the value associated with the given key, if it exists. The key is moved to the front of the LRU list.

§Arguments

k - The key to look up.

§Returns

Some(&V) if the key exists, None otherwise.

§Examples

use lru_st::collections::LruHashMap;

let mut cache = LruHashMap::with_max_entries(2);
cache.insert("a", 1);
assert_eq!(cache.get(&"a"), Some(&1));

Source

pub fn get_mut(&mut self, k: &K) -> Option<&mut V>

Returns a mutable reference to the value associated with the given key, if it exists. The key is moved to the front of the LRU list.

§Arguments

k - The key to look up.

§Returns

Some(&mut V) if the key exists, None otherwise.

§Examples

use lru_st::collections::LruHashMap;

let mut cache = LruHashMap::with_max_entries(2);
cache.insert("a", 1);
if let Some(v) = cache.get_mut(&"a") {
    *v = 2;
}
assert_eq!(cache.get(&"a"), Some(&2));

Source

pub fn items(&self) -> LruHashmapIter<'_, K, V> ⓘ

Returns an iterator over the key-value pairs in the LruHashMap, ordered from most recently used to least recently used.

§Returns

An iterator yielding (Rc<K>, &V) pairs.

§Examples

use lru_st::collections::LruHashMap;

#[cfg(not(feature = "sync"))]
use std::rc::Rc;

#[cfg(feature = "sync")]
use std::sync::Arc as Rc;

let mut cache = LruHashMap::with_max_entries(2);
cache.insert("a", 1);
cache.insert("b", 2);

let mut iter = cache.items();
assert_eq!(iter.next(), Some((Rc::new("b"), &2)));
assert_eq!(iter.next(), Some((Rc::new("a"), &1)));
assert_eq!(iter.next(), None);

Source

pub fn keys(&self) -> impl DoubleEndedIterator<Item = Rc<K>> + use<'_, K, V>

Returns an iterator over the keys in the LruHashMap, ordered from most recently used to least recently used.

§Returns

An iterator yielding Rc<K> keys.

§Examples

use lru_st::collections::LruHashMap;
#[cfg(not(feature = "sync"))]
use std::rc::Rc;

#[cfg(feature = "sync")]
use std::sync::Arc as Rc;

let mut cache = LruHashMap::with_max_entries(2);
cache.insert("a", 1);
cache.insert("b", 2);

let mut keys = cache.keys();
assert_eq!(keys.next(), Some(Rc::new("b")));
assert_eq!(keys.next(), Some(Rc::new("a")));
assert_eq!(keys.next(), None);

Source

pub fn values(&self) -> impl DoubleEndedIterator<Item = &V> + use<'_, K, V>

Returns an iterator over the values in the LruHashMap, ordered from most recently used to least recently used.

§Returns

An iterator yielding &V values.

§Examples

use lru_st::collections::LruHashMap;

let mut cache = LruHashMap::with_max_entries(2);
cache.insert("a", 1);
cache.insert("b", 2);

let mut values = cache.values();
assert_eq!(values.next(), Some(&2));
assert_eq!(values.next(), Some(&1));
assert_eq!(values.next(), None);

Source

pub fn contains_key(&mut self, k: &K) -> bool

Checks if the cache contains the given key.

§Arguments

k - The key to check.

§Returns

true if the key exists, false otherwise.

§Examples

use lru_st::collections::LruHashMap;

let mut cache = LruHashMap::with_max_entries(2);
cache.insert("a", 1);
assert!(cache.contains_key(&"a"));
assert!(!cache.contains_key(&"b"));

Source

pub fn insert(&mut self, k: K, v: V) -> Option<(K, V)>

Inserts a key-value pair into the cache. If the cache is full, the least recently used entry is removed and returned.

§Arguments

k - The key to insert.
v - The value to insert.

§Returns

Some((K, V)) if an entry was evicted, None otherwise.

§Examples

use lru_st::collections::LruHashMap;

let mut cache = LruHashMap::with_max_entries(1);
cache.insert("a", 1);
let evicted = cache.insert("b", 2);
assert_eq!(evicted, Some(("a", 1)));

Source

pub fn remove(&mut self, k: &K) -> Option<V>

Removes the entry associated with the given key from the cache.

§Arguments

k - The key to remove.

§Returns

Some(V) if the key existed, None otherwise.

§Examples

use lru_st::collections::LruHashMap;

let mut cache = LruHashMap::with_max_entries(2);
cache.insert("a", 1);
assert_eq!(cache.remove(&"a"), Some(1));
assert_eq!(cache.remove(&"b"), None);

Source

pub fn pop_lru(&mut self) -> Option<(K, V)>

Removes and returns the least recently used entry from the cache.

This function removes the key-value pair at the back of the LRU list (the least recently used entry) and returns it. If the cache is empty, it returns None.

§Returns

Some((K, V)) if an entry was removed, None if the cache is empty.

§Examples

use lru_st::collections::LruHashMap;

let mut cache = LruHashMap::with_max_entries(2);
cache.insert("a", 1);
cache.insert("b", 2);
assert_eq!(cache.pop_lru(), Some(("a", 1)));
assert_eq!(cache.len(), 1);
assert_eq!(cache.pop_lru(), Some(("b", 2)));
assert_eq!(cache.pop_lru(), None);

Source

pub fn len(&self) -> usize

Returns the number of entries in the cache.

§Examples

use lru_st::collections::LruHashMap;

let mut cache = LruHashMap::with_max_entries(2);
assert_eq!(cache.len(), 0);
cache.insert("a", 1);
assert_eq!(cache.len(), 1);

Source

pub fn cap(&self) -> usize

Returns the maximum number of entries the cache can hold.

§Examples

use lru_st::collections::LruHashMap;

let mut cache = LruHashMap::with_max_entries(2);
cache.insert("a", 1);
assert_eq!(cache.cap(), 2);

Source

pub fn is_empty(&self) -> bool

Checks if the cache is empty.

§Examples

use lru_st::collections::LruHashMap;

let mut cache = LruHashMap::with_max_entries(2);
assert!(cache.is_empty());
cache.insert("a", 1);
assert!(!cache.is_empty());