Struct TimedMap 

pub struct TimedMap<K, V, C = StdClock> { /* private fields */ }

Associates keys of type K with values of type V. Each entry may optionally expire after a specified duration.

Mutable functions automatically clears expired entries when called.

If no expiration is set, the entry remains constant.

Implementations

impl<K, V> TimedMap<K, V, StdClock>

where K: GenericKey,

pub fn new() -> Self

Creates an empty map.

pub fn new_with_map_kind(map_kind: MapKind) -> Self

Creates an empty map based on the chosen map implementation specified by MapKind.

impl<K, V, C> TimedMap<K, V, C>

where C: Clock, K: GenericKey,

pub fn expiration_tick_cap(self, expiration_tick_cap: u16) -> Self

Configures expiration_tick_cap, which sets how often TimedMap::drop_expired_entries is automatically called. The default value is 1.

On each insert (excluding unchecked ones), an internal counter expiration_tick is incremented. When expiration_tick meets or exceeds expiration_tick_cap, TimedMap::drop_expired_entries is triggered to remove expired entries.

Use this to control cleanup frequency and optimize performance. For example, if your workload involves about 100 inserts within couple seconds, setting expiration_tick_cap to 100 can improve the performance significantly.

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

Returns the associated value if present and not expired.

To retrieve the value without checking expiration, use TimedMap::get_unchecked.

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

Returns a mutable reference to the value corresponding to the key.

To retrieve the value without checking expiration, use TimedMap::get_mut_unchecked.

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

Returns the associated value if present, regardless of whether it is expired.

If you only want non-expired entries, use TimedMap::get instead.

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

Returns a mutable reference to the associated value if present, regardless of whether it is expired.

If you only want non-expired entries, use TimedMap::get_mut instead.

pub fn get_remaining_duration(&self, k: &K) -> Option<Duration>

Returns the associated value’s Duration if present and not expired.

Returns None if the entry does not exist or is constant.

pub fn len(&self) -> usize

Returns the number of unexpired elements in the map.

See TimedMap::len_expired and TimedMap::len_unchecked for other usages.

pub fn len_expired(&self) -> usize

Returns the number of expired elements in the map.

See TimedMap::len and TimedMap::len_unchecked for other usages.

pub fn len_unchecked(&self) -> usize

Returns the total number of elements (including expired ones) in the map.

See TimedMap::len and TimedMap::len_expired for other usages.

pub fn keys(&self) -> Vec<K>

Returns keys of the map

pub fn is_empty(&self) -> bool

Returns true if the map contains no elements.

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

Inserts a key-value pair with an expiration duration, and then drops the expired entries.

If a value already exists for the given key, it will be updated and then the old one will be returned.

If you don’t want to the check expired entries, consider using TimedMap::insert_expirable_unchecked instead.

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

Inserts a key-value pair with an expiration duration, without checking the expired entries.

If a value already exists for the given key, it will be updated and then the old one will be returned.

If you want to check the expired entries, consider using TimedMap::insert_expirable instead.

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

Inserts a key-value pair with that doesn’t expire, and then drops the expired entries.

If a value already exists for the given key, it will be updated and then the old one will be returned.

If you don’t want to check the expired entries, consider using TimedMap::insert_constant_unchecked instead.

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

Inserts a key-value pair with that doesn’t expire without checking the expired entries.

If a value already exists for the given key, it will be updated and then the old one will be returned.

If you want to check the expired entries, consider using TimedMap::insert_constant instead.

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

Removes a key-value pair from the map and returns the associated value if present and not expired.

If you want to retrieve the entry after removal even if it is expired, consider using TimedMap::remove_unchecked.

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

Removes a key-value pair from the map and returns the associated value if present, regardless of expiration status.

If you only want the entry when it is not expired, consider using TimedMap::remove.

pub fn clear(&mut self)

Clears the map, removing all elements.

pub fn iter(&self) -> impl Iterator<Item = (&K, &V)>

Returns an iterator over non-expired key-value pairs.

pub fn iter_unchecked(&self) -> impl Iterator<Item = (&K, &V)>

Returns an iterator over all key-value pairs, including expired ones.

pub fn iter_mut(&mut self) -> impl Iterator<Item = (&K, &mut V)>

Returns a mutable iterator over non-expired key-value pairs.

pub fn iter_mut_unchecked(&mut self) -> impl Iterator<Item = (&K, &mut V)>

Returns a mutable iterator over all key-value pairs, including expired ones.

pub fn update_expiration_status( &mut self, key: K, duration: Duration, ) -> Result<Option<EntryStatus>, &'static str>

Updates the expiration status of an entry and returns the old status.

If the entry does not exist, returns Err. If the entry’s old status is EntryStatus::Constant, returns None.

pub fn drop_expired_entries(&mut self) -> Vec<(K, V)>

Clears expired entries from the map and returns them.

Call this function when using *_unchecked inserts, as these do not automatically clear expired entries.

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

Returns true if the map contains a non-expired value for the given key.

To include expired entries as well, use TimedMap::contains_key_unchecked.

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

Returns true if the map contains a value for the given key regardless of expiration status.

To exclude expired entries, use TimedMap::contains_key instead.

Trait Implementations

impl<K: Clone, V: Clone, C: Clone> Clone for TimedMap<K, V, C>

fn clone(&self) -> TimedMap<K, V, C>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<K: Debug, V: Debug, C: Debug> Debug for TimedMap<K, V, C>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<K, V, C> Default for TimedMap<K, V, C>

where C: Default,

fn default() -> Self

Returns the “default value” for a type.

impl<'a, K, V, C> IntoIterator for &'a TimedMap<K, V, C>

where K: GenericKey, C: Clock,

type Item = (&'a K, &'a V)

The type of the elements being iterated over.

type IntoIter = IntoIter<(&'a K, &'a V)>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, K, V, C> IntoIterator for &'a mut TimedMap<K, V, C>

where K: GenericKey, C: Clock,

type Item = (&'a K, &'a mut V)

The type of the elements being iterated over.

type IntoIter = IntoIter<(&'a K, &'a mut V)>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<K, V, C> IntoIterator for TimedMap<K, V, C>

where K: GenericKey, C: Clock,

type Item = (K, V)

The type of the elements being iterated over.

type IntoIter = IntoIter<(K, V)>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.