Struct schnellru::LruMap

pub struct LruMap<K, V, L = ByLength, S = RandomState>where
    L: Limiter<K, V>,{ /* private fields */ }

An LRU hash map.

Implementations

impl<K, V, L> LruMap<K, V, L, RandomState>where
    K: Hash + PartialEq,
    L: Limiter<K, V>,

pub fn new(limiter: L) -> Self

Creates a new empty map with a given limiter.

pub const fn with_seed(limiter: L, seed: [u64; 4]) -> Self

Creates a new empty map with a given limiter and a non-randomized hasher.

impl<K, V, S> LruMap<K, V, ByMemoryUsage, S>where
    K: Hash + PartialEq,
    S: BuildHasher,

pub const fn with_memory_budget_and_hasher(
    memory_budget: usize,
    hasher: S
) -> Self

Creates a new empty map with a given memory_budget and hasher.

This will configure the limiter so that the map can use at most memory_budget bytes of memory.

This does not preallocate any memory.

impl<K, V> LruMap<K, V, ByMemoryUsage, RandomState>where
    K: Hash + PartialEq,

pub fn with_memory_budget(memory_budget: usize) -> Self

Creates a new empty map with a given memory_budget.

This will configure the limiter so that the map can use at most memory_budget bytes of memory.

This does not preallocate any memory.

impl<K, V, L, S> LruMap<K, V, L, S>where
    K: Hash + PartialEq,
    S: BuildHasher,
    L: Limiter<K, V>,

pub const fn with_hasher(limiter: L, hasher: S) -> Self

Creates a new map with a given limiter and hasher.

pub fn reserve_or_panic(&mut self, additional: usize)

Ensures that at least additional items can be inserted into the table without reallocation.

Panics

Will panic if the total number of elements is too big or the memory couldn’t be allocated.

pub fn guaranteed_capacity(&self) -> usize

Returns the current guaranteed capacity of the map.

This specifies how many elements the map is guaranteed to be able to hold without allocating any memory. This is a lower bound; it’s possible that the map can hold more elements than this.

This value will change as elements are added and removed. In particular, in might go down when an element is removed from the map.

This is independent of the cap imposed by the limiter.

pub fn memory_usage_for_memory_budget(memory_budget: usize) -> usize

Returns an estimated memory usage this map will have with a given memory_budget.

pub fn memory_usage(&self) -> usize

Returns the current memory usage of the map, in bytes.

pub fn len(&self) -> usize

Returns the number of elements in the map.

pub fn is_empty(&self) -> bool

Returns whether the map is empty or not.

pub fn get(&mut self, key: &impl Hash + PartialEq<K> + ?Sized) -> Option<&mut V>

Returns a reference to the value for a given key and promotes that element to be the most recently used.

pub fn get_by_hash(
    &mut self,
    hash: u64,
    is_eq: impl FnMut(&K, &V) -> bool
) -> Option<&mut V>

Returns a reference to the value for a given hash and for which is_eq returns true. Promotes that element to be the most recently used.

pub fn get_or_insert<'a>(
    &mut self,
    key: impl Into<L::KeyToInsert<'a>> + Hash + PartialEq<K> + ?Sized,
    get: impl FnOnce() -> V
) -> Option<&mut V>where
    L::KeyToInsert<'a>: Hash + PartialEq<K>,

Tries to get the value for a given key or insert a new value if there’s no element in the map which matches that key.

If present the element will be promoted to be the most recently used.

pub fn get_or_insert_fallible<'a, E>(
    &mut self,
    key: impl Into<L::KeyToInsert<'a>> + Hash + PartialEq<K> + ?Sized,
    get: impl FnOnce() -> Result<V, E>
) -> Result<Option<&mut V>, E>where
    L::KeyToInsert<'a>: Hash + PartialEq<K>,

Same as Self::get_or_insert, just with a fallible callback.

pub fn peek<'a>(
    &'a self,
    key: &impl Hash + PartialEq<K> + ?Sized
) -> Option<&'a V>

Returns a reference to the value for a given key. Does not change the order of the elements.

pub fn peek_mut<'a>(
    &'a mut self,
    key: &impl Hash + PartialEq<K> + ?Sized
) -> Option<&'a mut V>

Returns a mutable reference to the value for a given key. Does not change the order of the elements.

pub fn peek_by_hash(
    &self,
    hash: u64,
    is_eq: impl FnMut(&K, &V) -> bool
) -> Option<&V>

Returns a reference to the value for a given hash and for which is_eq returns true. Does not change the order of the elements.

pub fn peek_by_hash_mut(
    &mut self,
    hash: u64,
    is_eq: impl FnMut(&K, &V) -> bool
) -> Option<&mut V>

Returns a mutable reference to the value for a given hash and for which is_eq returns true. Does not change the order of the elements.

pub fn remove(&mut self, key: &impl Hash + PartialEq<K> + ?Sized) -> Option<V>

Removes an element from the map.

pub fn insert<'a>(&mut self, key: L::KeyToInsert<'a>, value: V) -> boolwhere
    L::KeyToInsert<'a>: Hash + PartialEq<K>,

Inserts a new element into the map.

Can fail if the element is rejected by the limiter or if we fail to grow an empty map.

Returns true if the element was inserted; false otherwise.

pub fn clear(&mut self)

Clears the map.

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

Removes the least recently accessed element and returns it.

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

Removes the most recently accessed element and returns it.

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

Returns the most recently used (inserted or accessed) element of the map. Does not change the order of the elements.

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

Returns the least recently used (inserted or accessed) element of the map. Does not change the order of the elements.

pub fn iter(&self) -> Iter<'_, K, V, L>

An iterator over all of the elements in the most recently used order.

pub fn drain(&mut self) -> Drain<'_, K, V, L, S>

Drains the map of all of its elements in the most recently used order.

When the iterator is dropped the map will be automatically cleared.

pub fn limiter(&self) -> &L

Returns a reference to the map’s limiter.

pub fn limiter_mut(&mut self) -> &mut L

Returns a mutable reference to the map’s limiter.

Trait Implementations

impl<K: Clone, V: Clone, L, S: Clone> Clone for LruMap<K, V, L, S>where
    L: Limiter<K, V> + Clone,
    L::LinkType: Clone,

fn clone(&self) -> LruMap<K, V, L, S>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<K, V, L, S> Default for LruMap<K, V, L, S>where
    K: Hash + PartialEq,
    S: BuildHasher + Default,
    L: Limiter<K, V> + Default,

fn default() -> Self

Returns the “default value” for a type.