robinxx_map 0.1.0

//! Entry API for in-place modification and conditional insertion.
//!
//! Provides `Entry`, `OccupiedEntry`, and `VacantEntry` matching `std::collections` ergonomics.
//! Entry variants retain the internal spinlock guard to ensure atomicity during
//! complex insertion or modification patterns.
//!
//! # Lifetime Semantics
//! References returned by Entry methods (e.g., `into_mut`, `insert`) are tied to the
//! original `&RobinHoodMap` borrow that created the Entry, not to the Entry itself.
//! The `MutexGuard` ensures exclusive access while obtaining the reference; once
//! returned, the lock is released but the reference remains valid for lifetime `'a`.
//! Callers must uphold aliasing rules: no other mutable references to the same key
//! may exist while the returned reference is held.

use crate::hash::RobinHoodKey;
use crate::sync::MutexGuard;
use crate::table::RawTable;
use core::marker::PhantomData;

/// View into a single entry in a map, which may be occupied or vacant.
///
/// # Summary
/// Enumerates possible states for a map key during conditional operations.
///
/// # Description
/// Returned by `RobinHoodMap::entry()`. Holds the internal spinlock guard
/// until the variant is consumed or dropped. Enables `or_insert`, `and_modify`,
/// and `or_default` patterns without double lookups.
///
/// # Examples
/// ```
/// use robinxx_map::RobinHoodMap;
/// let map = RobinHoodMap::new();
/// map.entry("key").or_insert(0);
/// ```
///
/// # Panics
/// None.
///
/// # Errors
/// Not applicable.
///
/// # Safety
/// Not applicable. This is a safe function, thread-safety is guaranteed
/// internally by `SpinMutex` acquisition.
///
/// # See Also
/// - [`OccupiedEntry`]
/// - [`VacantEntry`]
pub enum Entry<'a, K, V> {
    /// Key exists in the map.
    Occupied(OccupiedEntry<'a, K, V>),
    /// Key does not exist.
    Vacant(VacantEntry<'a, K, V>),
}

impl<'a, K: RobinHoodKey + PartialEq + Clone, V> Entry<'a, K, V> {
    /// Inserts value if vacant, otherwise returns occupied reference.
    ///
    /// # Summary
    /// Returns mutable reference to the value at the entry.
    ///
    /// # Description
    /// If `Vacant`, inserts `default` and returns `&mut V`. If `Occupied`,
    /// returns reference to existing value.
    ///
    /// # Examples
    /// ```
    /// use robinxx_map::RobinHoodMap;
    /// let map = RobinHoodMap::new();
    /// let v = map.entry("a").or_insert(1);
    /// *v = 2;
    /// ```
    ///
    /// # Panics
    /// Panics on allocation failure if vacant and insert triggers resize.
    ///
    /// # Errors
    /// Not applicable.
    ///
    /// # Safety
    /// Not applicable. This is a safe function, thread-safety is guaranteed
    /// internally by `SpinMutex` acquisition.
    ///
    /// # See Also
    /// - [`or_insert`](Self::or_insert)
    #[inline]
    pub fn or_insert(self, default: V) -> &'a mut V
    where
        K: Clone,
    {
        match self {
            Entry::Occupied(e) => e.into_mut(),
            Entry::Vacant(e) => e.insert(default),
        }
    }

    /// Inserts value computed by closure if vacant.
    ///
    /// # Summary
    /// Evaluates `f()` and inserts result if key absent.
    ///
    /// # Description
    /// Lazy evaluation avoids unnecessary allocation or computation when key exists.
    ///
    /// # Examples
    /// ```
    /// use robinxx_map::RobinHoodMap;
    /// let map = RobinHoodMap::new();
    /// map.entry("x").or_insert_with(|| 42);
    /// ```
    ///
    /// # Panics
    /// Panics if `f()` panics or allocation fails during insert.
    ///
    /// # Errors
    /// Not applicable.
    ///
    /// # Safety
    /// Not applicable. This is a safe function, thread-safety is guaranteed
    /// internally by `SpinMutex` acquisition.
    ///
    /// # See Also
    /// - [`or_insert`](Self::or_insert)
    #[inline]
    pub fn or_insert_with<F: FnOnce() -> V>(self, f: F) -> &'a mut V
    where
        K: Clone,
    {
        match self {
            Entry::Occupied(e) => e.into_mut(),
            Entry::Vacant(e) => e.insert(f()),
        }
    }

    /// Modifies occupied value, or returns vacant entry.
    ///
    /// # Summary
    /// Applies closure to occupied value, leaves vacant untouched.
    ///
    /// # Description
    /// Useful for updating counters or aggregating without replacing.
    ///
    /// # Examples
    /// ```
    /// use robinxx_map::RobinHoodMap;
    /// let map = RobinHoodMap::new();
    /// map.insert("c", 0);
    /// map.entry("c").and_modify(|e| *e += 1);
    /// ```
    ///
    /// # Panics
    /// Panics if closure `f` panics.
    ///
    /// # Errors
    /// Not applicable.
    ///
    /// # Safety
    /// Not applicable. This is a safe function, thread-safety is guaranteed
    /// internally by `SpinMutex` acquisition.
    ///
    /// # See Also
    /// - [`or_insert`](Self::or_insert)
    #[inline]
    #[must_use]
    pub fn and_modify<F: FnOnce(&mut V)>(mut self, f: F) -> Self {
        if let Entry::Occupied(ref mut e) = self {
            f(e.get_mut());
        }
        self
    }
}

/// An occupied entry in a `RobinHoodMap`.
///
/// # Summary
/// View into an existing key-value pair.
///
/// # Description
/// Allows reading, mutating, or removing the value without re-probing.
///
/// # Examples
/// ```
/// use robinxx_map::RobinHoodMap;
/// let map = RobinHoodMap::new();
/// map.insert(1, "a");
/// if let robinxx_map::entry::Entry::Occupied(e) = map.entry(1) {
///     assert_eq!(e.get(), &"a");
/// }
/// ```
///
/// # Panics
/// None.
///
/// # Errors
/// Not applicable.
///
/// # Safety
/// Not applicable. This is a safe function, thread-safety is guaranteed
/// internally by `SpinMutex` acquisition.
///
/// # See Also
/// - [`Entry`]
pub struct OccupiedEntry<'a, K, V> {
    guard: MutexGuard<'a, RawTable<K, V>>,
    key: K,
    _marker: PhantomData<&'a V>,
}

impl<'a, K: RobinHoodKey + PartialEq, V> OccupiedEntry<'a, K, V> {
    /// Internal constructor for crate use only.
    ///
    /// # Summary
    /// Builds an `OccupiedEntry` from a locked guard and existing key.
    ///
    /// # Description
    /// Used internally by `RobinHoodMap::entry()`. Not intended for direct public use.
    ///
    /// # Examples
    /// Internal use only.
    ///
    /// # Panics
    /// Never panics.
    ///
    /// # Errors
    /// Not applicable.
    ///
    /// # Safety
    /// Caller must guarantee the key actually exists in the guarded table.
    ///
    /// # See Also
    /// - [`RobinHoodMap::entry`](crate::map::RobinHoodMap::entry)
    #[inline]
    pub(crate) fn new(guard: MutexGuard<'a, RawTable<K, V>>, key: K) -> Self {
        Self {
            guard,
            key,
            _marker: PhantomData,
        }
    }

    /// Returns immutable reference to the stored value.
    ///
    /// # Summary
    /// Retrieves `&V` for the occupied key.
    ///
    /// # Description
    /// Direct access without additional lookup cost.
    ///
    /// # Examples
    /// ```
    /// use robinxx_map::RobinHoodMap;
    /// let map = RobinHoodMap::new();
    /// map.insert(1, "x");
    /// if let robinxx_map::entry::Entry::Occupied(e) = map.entry(1) {
    ///     assert_eq!(*e.get(), "x");
    /// }
    /// ```
    ///
    /// # Panics
    /// Panics if the occupied invariant is violated. This indicates an internal bug
    /// in `robinxx_map` and should never occur under correct usage.
    ///
    /// # Errors
    /// Not applicable.
    ///
    /// # Safety
    /// Not applicable. This is a safe function, thread-safety is guaranteed
    /// internally by `SpinMutex` acquisition.
    ///
    /// # See Also
    /// - [`get_mut`](Self::get_mut)
    #[inline]
    pub fn get(&self) -> &V {
        self.guard
            .get(&self.key)
            .expect("occupied invariant violated")
    }

    /// Returns mutable reference to the stored value.
    ///
    /// # Summary
    /// Retrieves `&mut V` for the occupied key.
    ///
    /// # Description
    /// Allows in-place mutation while preserving entry ownership.
    ///
    /// # Examples
    /// ```
    /// use robinxx_map::RobinHoodMap;
    /// let map = RobinHoodMap::new();
    /// map.insert(1, 0);
    /// if let robinxx_map::entry::Entry::Occupied(mut e) = map.entry(1) {
    ///     *e.get_mut() += 5;
    /// }
    /// ```
    ///
    /// # Panics
    /// Panics if the occupied invariant is violated. This indicates an internal bug
    /// in `robinxx_map` and should never occur under correct usage.
    ///
    /// # Errors
    /// Not applicable.
    ///
    /// # Safety
    /// Not applicable. This is a safe function, thread-safety is guaranteed
    /// internally by `SpinMutex` acquisition.
    ///
    /// # See Also
    /// - [`get`](Self::get)
    #[inline]
    pub fn get_mut(&mut self) -> &mut V {
        self.guard
            .get_mut(&self.key)
            .expect("occupied invariant violated")
    }

    /// Replaces value and returns old value.
    ///
    /// # Summary
    /// Swaps existing value with new one.
    ///
    /// # Description
    /// Useful when old value must be consumed or inspected.
    ///
    /// # Examples
    /// ```
    /// use robinxx_map::RobinHoodMap;
    /// let map = RobinHoodMap::new();
    /// map.insert(1, "old");
    /// if let robinxx_map::entry::Entry::Occupied(mut e) = map.entry(1) {
    ///     assert_eq!(e.insert("new"), "old");
    /// }
    /// ```
    ///
    /// # Panics
    /// Never panics.
    ///
    /// # Errors
    /// Not applicable.
    ///
    /// # Safety
    /// Not applicable. This is a safe function, thread-safety is guaranteed
    /// internally by `SpinMutex` acquisition.
    ///
    /// # See Also
    /// - [`get_mut`](Self::get_mut)
    #[inline]
    pub fn insert(&mut self, value: V) -> V {
        let old = self.get_mut();
        core::mem::replace(old, value)
    }

    /// Removes entry and returns owned value.
    ///
    /// # Summary
    /// Deletes key and yields `V`.
    ///
    /// # Description
    /// Applies backward shift deletion internally.
    ///
    /// # Examples
    /// ```
    /// use robinxx_map::RobinHoodMap;
    /// let map = RobinHoodMap::new();
    /// map.insert(1, "val");
    /// if let robinxx_map::entry::Entry::Occupied(e) = map.entry(1) {
    ///     assert_eq!(e.remove(), "val");
    /// }
    /// assert!(map.is_empty());
    /// ```
    ///
    /// # Panics
    /// Never panics.
    ///
    /// # Errors
    /// Not applicable.
    ///
    /// # Safety
    /// Not applicable. This is a safe function, thread-safety is guaranteed
    /// internally by `SpinMutex` acquisition.
    ///
    /// # See Also
    /// - [`get`](Self::get)
    #[inline]
    pub fn remove(self) -> V
    where
        V: Clone,
    {
        let value = self.get().clone();
        let mut guard = self.guard;
        guard.remove(&self.key);
        value
    }

    /// Consumes entry and returns mutable reference to value.
    ///
    /// # Summary
    /// Yields `&mut V` with entry lifetime.
    ///
    /// # Description
    /// Finalizes entry access for mutation without removing.
    ///
    /// # Examples
    /// ```
    /// use robinxx_map::RobinHoodMap;
    /// let map = RobinHoodMap::new();
    /// map.insert(1, 10);
    /// if let robinxx_map::entry::Entry::Occupied(e) = map.entry(1) {
    ///     *e.into_mut() *= 2;
    /// }
    /// ```
    ///
    /// # Panics
    /// Panics if the occupied invariant is violated. This indicates an internal bug
    /// in `robinxx_map` and should never occur under correct usage.
    ///
    /// # Errors
    /// Not applicable.
    ///
    /// # Safety
    /// Not applicable. This is a safe function, thread-safety is guaranteed
    /// internally by `SpinMutex` acquisition.
    ///
    /// # See Also
    /// - [`get_mut`](Self::get_mut)
    #[inline]
    pub fn into_mut(mut self) -> &'a mut V {
        let ptr = core::ptr::from_mut::<V>(
            self.guard
                .get_mut(&self.key)
                .expect("occupied invariant violated"),
        );
        // SAFETY:
        // 1. `ptr` points to a valid `V` inside the `RawTable` owned by `RobinHoodMap`.
        // 2. The lifetime `'a` is tied to the original `&RobinHoodMap` borrow that
        //    created the Entry, not to the Entry or guard itself.
        // 3. The guard ensures exclusive access while obtaining the pointer; once
        //    returned, the lock is released but the reference remains sound.
        // 4. Caller must uphold aliasing rules: no other mutable references to the
        //    same key may exist while this reference is held.
        unsafe { &mut *ptr }
    }
}

/// A vacant entry in a `RobinHoodMap`.
///
/// # Summary
/// View into a missing key, ready for insertion.
///
/// # Description
/// Holds lock and key. Calling `insert()` resolves to `Occupied` state.
///
/// # Examples
/// ```
/// use robinxx_map::RobinHoodMap;
/// let map = RobinHoodMap::new();
/// if let robinxx_map::entry::Entry::Vacant(e) = map.entry("new") {
///     e.insert(42);
/// }
/// ```
///
/// # Panics
/// None.
///
/// # Errors
/// Not applicable.
///
/// # Safety
/// Not applicable. This is a safe function, thread-safety is guaranteed
/// internally by `SpinMutex` acquisition.
///
/// # See Also
/// - [`Entry`]
pub struct VacantEntry<'a, K, V> {
    guard: MutexGuard<'a, RawTable<K, V>>,
    key: K,
    _marker: PhantomData<&'a V>,
}

impl<'a, K: RobinHoodKey + PartialEq + Clone, V> VacantEntry<'a, K, V> {
    /// Internal constructor for crate use only.
    ///
    /// # Summary
    /// Builds a `VacantEntry` from a locked guard and missing key.
    ///
    /// # Description
    /// Used internally by `RobinHoodMap::entry()`. Not intended for direct public use.
    ///
    /// # Examples
    /// Internal use only.
    ///
    /// # Panics
    /// Never panics.
    ///
    /// # Errors
    /// Not applicable.
    ///
    /// # Safety
    /// Caller must guarantee the key does not exist in the guarded table.
    ///
    /// # See Also
    /// - [`RobinHoodMap::entry`](crate::map::RobinHoodMap::entry)
    #[inline]
    pub(crate) fn new(guard: MutexGuard<'a, RawTable<K, V>>, key: K) -> Self {
        Self {
            guard,
            key,
            _marker: PhantomData,
        }
    }

    /// Inserts value and returns mutable reference.
    ///
    /// # Summary
    /// Stores `value` at vacant key.
    ///
    /// # Description
    /// Triggers resize if 80% LF reached. Returns `&mut V`.
    /// The returned reference is valid for lifetime `'a`, tied to the original
    /// `&RobinHoodMap` borrow.
    ///
    /// # Examples
    /// ```
    /// use robinxx_map::RobinHoodMap;
    /// let map = RobinHoodMap::new();
    /// if let robinxx_map::entry::Entry::Vacant(e) = map.entry("k") {
    ///     *e.insert(1) += 1;
    /// }
    /// ```
    ///
    /// # Panics
    /// Panics on allocation failure during resize.
    ///
    /// # Errors
    /// Not applicable.
    ///
    /// # Safety
    /// - The returned reference is valid for lifetime `'a`, tied to the original
    ///   `&RobinHoodMap` borrow, not to the Entry or guard.
    /// - Caller must not create aliasing mutable references to the same key.
    /// - This method requires `K: Clone` to clone the key before moving it into
    ///   the table, enabling safe re-probing for the mutable reference.
    ///
    /// # See Also
    /// - [`Entry::or_insert`]
    #[inline]
    pub fn insert(mut self, value: V) -> &'a mut V {
        // Clone the key before moving it into insert()
        let key_clone = self.key.clone();
        // Insert the key-value pair into the table
        let inserted = self.guard.insert(self.key, value);
        debug_assert!(inserted, "VacantEntry::insert called on occupied key");
        // Re-probe to get mutable reference to the newly inserted value.
        // We use the cloned key since the original was moved.
        let ptr = core::ptr::from_mut::<V>(
            self.guard
                .get_mut(&key_clone)
                .expect("insert failed to place value at expected location"),
        );
        // SAFETY:
        // 1. `ptr` points to a valid `V` inside the `RawTable` owned by `RobinHoodMap`.
        // 2. The lifetime `'a` is tied to the original `&RobinHoodMap` borrow that
        //    created the Entry, not to the Entry or guard itself.
        // 3. The guard ensures exclusive access while obtaining the pointer; once
        //    returned, the lock is released but the reference remains sound.
        // 4. Caller must uphold aliasing rules: no other mutable references to the
        //    same key may exist while this reference is held.
        unsafe { &mut *ptr }
    }
}