Struct OverlayMap

pub struct OverlayMap<K, V, S = DefaultHashBuilder>
where
    K: Eq + Hash,
{ /* private fields */ }

A two-layered map where each key has a mutable foreground and an optional background value.

When inserting a new value for a key, the previous value (if any) is automatically moved to the background. Background values are preserved but not cloned.

This map is not thread-safe for mutation. It may be shared across threads for read-only access.

Implementations

impl<K, V, S> OverlayMap<K, V, S>

where K: Eq + Hash, S: BuildHasher + Default,

pub fn new() -> Self

Creates a new, empty OverlayMap with the default hasher.

pub fn with_capacity(capacity: usize) -> Self

Creates an empty OverlayMap with the specified capacity and default hasher.

pub fn with_hasher(hasher: S) -> Self

Creates an empty OverlayMap that will use the given hasher.

pub fn with_capacity_and_hasher(capacity: usize, hasher: S) -> Self

Creates an empty OverlayMap with the specified capacity and hasher.

pub fn len(&self) -> usize

Number of unique keys in the map.

pub fn is_empty(&self) -> bool

Check if the map is empty.

pub fn fg(&self, key: &K) -> Option<&V>

Get an immutable reference to the value associated with the key.

Returns None if the key was not found in the map.

pub fn bg(&self, key: &K) -> Option<&V>

Get an immutable reference to the value associated with the key in the background layer.

Returns None if the key was not found in the background layer.

pub fn push(&mut self, key: K, value: V) -> bool

Push a value into the foreground layer, preserving the previous value in the background.

If the key was already present, the current foreground is moved to the background slot, and the new value becomes the new foreground. No cloning occurs. The old background value is dropped if it was present.

Returns true if there was already a foreground value (i.e. a background now definitely exists).

pub fn push_if<F>(&mut self, key: &K, predicate: F) -> bool

where F: FnOnce(&V) -> Option<V>,

Conditionally push a new value into the foreground based on the current value.

If the key exists, the current foreground value is passed to the predicate. If the predicate returns Some(new_val), the new value is pushed and the old one is preserved in the background. If it returns None, nothing is changed.

Returns true if a new value was pushed.

pub fn pull(&mut self, key: &K) -> Option<V>

Pulls the foreground value for a key, promoting the background to foreground if present.

This removes and returns the current foreground value for the given key. If a background value exists, it is promoted to foreground. If the key has no background after the pull, the key is removed from the map entirely.

Returns

• Some(value) if the key existed and a foreground value was pulled.
• None if the key did not exist.

Invariants

• After this operation, the key is only retained if a background value was available to promote.
• Keys in the map always have at least one value (foreground), unless removed by pull.

Example

use overlay_map::OverlayMap;

let mut map = OverlayMap::<&str, i32>::new();
map.push("key", 1);
map.push("key", 2);

assert_eq!(map.fg(&"key"), Some(&2));
assert_eq!(map.bg(&"key"), Some(&1));

let pulled = map.pull(&"key");
assert_eq!(pulled, Some(2));
assert_eq!(map.fg(&"key"), Some(&1)); // background promoted

let pulled = map.pull(&"key");
assert_eq!(pulled, Some(1));
assert_eq!(map.fg(&"key"), None); // entry removed

pub fn pull_if<F>(&mut self, key: &K, predicate: F) -> Option<V>

where F: FnOnce(&V) -> bool,

Conditionally pulls the foreground value for a key, promoting the background if present.

If the key exists and the provided predicate returns true for the current foreground, this removes and returns the foreground value. The background (if any) is promoted to foreground, and the key is removed from the map if no background remains.

If the predicate returns false or the key does not exist, the map is left unchanged.

Returns

• Some(value) if the predicate matched and the foreground was pulled.
• None if the key was not found or the predicate returned false.

Invariants

• After this operation, the key is only retained if a background value was available to promote.
• Keys in the map always have at least one value (foreground), unless removed by pull_if.

Example

use overlay_map::OverlayMap;

let mut map = OverlayMap::<&str, i32>::new();
map.push("key", 10);
map.push("key", 20);

// Only pull if the foreground is 20
let pulled = map.pull_if(&"key", |v| *v == 20);
assert_eq!(pulled, Some(20));
assert_eq!(map.fg(&"key"), Some(&10));

// Predicate does not match: nothing is pulled
let pulled = map.pull_if(&"key", |v| *v == 999);
assert_eq!(pulled, None);
assert_eq!(map.fg(&"key"), Some(&10));

// Pull remaining value, removing the key
let pulled = map.pull_if(&"key", |_| true);
assert_eq!(pulled, Some(10));
assert_eq!(map.fg(&"key"), None);

pub fn swap(&mut self, key: K, value: V) -> Option<V>

Swap a value into the foreground layer, preserving the previous value in the background, and returning the evicted background value if present.

If the key was already present, the current foreground is moved to the background slot, and the new value becomes the new foreground. No cloning occurs. The old background value is returned if present.

pub fn swap_if<F>(&mut self, key: &K, predicate: F) -> Option<V>

where F: FnOnce(&V) -> Option<V>,

Conditionally swap a new value into the foreground based on the current value.

If the key exists, the current foreground value is passed to the predicate. If the predicate returns Some(new_val), the new value is pushed and the old one is preserved in the background. If it returns None, nothing is changed.

The evicted background value is returned if present.

pub fn overlay<I>(&mut self, iter: I) -> usize

where I: IntoIterator<Item = (K, V)>,

Overlay multiple values onto the map.

Each key-value pair is pushed into the foreground layer. If the key was already present, the existing foreground value is moved to the background. This does not clone or retain old values beyond the background layer.

Returns the number of keys that already existed (i.e. pushes that replaced a foreground).

Trait Implementations

impl<K, V: Debug, S: Debug> Debug for OverlayMap<K, V, S>

where K: Eq + Hash + Debug,

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

Formats the value using the given formatter.

impl<K, V: Default, S: Default> Default for OverlayMap<K, V, S>

where K: Eq + Hash + Default,

fn default() -> OverlayMap<K, V, S>

Returns the “default value” for a type.

impl<K, V, S> Sync for OverlayMap<K, V, S>

where K: Eq + Hash + Sync, S: Sync,