robinxx_map 0.1.0

//! Safe traversal iterators: `Iter`, `IterMut`, `Keys`, `Values`, `Drain`.
//!
//! Guarantees yield-safe iteration over `SoA` blocks with invariant-checked traversal state.
//! Iterators hold internal `MutexGuard` to block concurrent mutation during traversal.

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

/// Iterator over immutable key-value pairs.
///
/// # Summary
/// Yields `(&K, &V)` for all occupied slots.
///
/// # Description
/// Traverses metadata array linearly, yielding initialized entries.
/// Order is undefined and may vary across runs.
///
/// # Examples
/// ```
/// use robinxx_map::RobinHoodMap;
/// let map = RobinHoodMap::new();
/// map.insert(1, "a");
/// for (k, v) in map.iter() {
///     println!("{}: {}", k, v);
/// }
/// ```
///
/// # Panics
/// Never panics.
///
/// # Errors
/// Not applicable.
///
/// # Safety
/// Iterator borrows lock. Thread-safe.
///
/// # See Also
/// - [`IterMut`]
pub struct Iter<'a, K: RobinHoodKey + PartialEq, V> {
    guard: MutexGuard<'a, RawTable<K, V>>,
    idx: usize,
    remaining: usize,
    _marker: PhantomData<(K, V)>,
}

impl<'a, K: RobinHoodKey + PartialEq, V> Iter<'a, K, V> {
    /// Creates a new immutable iterator over the map.
    ///
    /// # Summary
    /// Initializes traversal state from a locked `RawTable`.
    ///
    /// # Description
    /// Stores the mutex guard and resets the cursor to index 0. Used internally
    /// by `RobinHoodMap::iter()`.
    ///
    /// # Examples
    /// Internal use only.
    ///
    /// # Panics
    /// Never panics.
    ///
    /// # Errors
    /// Not applicable.
    ///
    /// # Safety
    /// Caller must provide an active `MutexGuard` to prevent concurrent mutation.
    ///
    /// # See Also
    /// - [`RobinHoodMap::iter`](crate::map::RobinHoodMap::iter)
    #[inline]
    pub(crate) fn new(guard: MutexGuard<'a, RawTable<K, V>>) -> Self {
        let remaining = guard.size();
        Self {
            guard,
            idx: 0,
            remaining,
            _marker: PhantomData,
        }
    }
}

impl<'a, K: RobinHoodKey + PartialEq, V> Iterator for Iter<'a, K, V> {
    type Item = (&'a K, &'a V);
    fn next(&mut self) -> Option<Self::Item> {
        while self.remaining > 0 {
            let meta = unsafe { *self.guard.meta_ptr.add(self.idx) };
            if meta != 0 {
                let k = unsafe { &*self.guard.keys_ptr.add(self.idx) };
                let v = unsafe { &*self.guard.vals_ptr.add(self.idx) };
                self.idx += 1;
                self.remaining -= 1;
                return Some((k, v));
            }
            self.idx += 1;
        }
        None
    }
}

/// Iterator over mutable values.
///
/// # Summary
/// Yields `&mut V` for all occupied slots.
///
/// # Description
/// Allows in-place mutation while preserving key stability.
///
/// # Examples
/// ```
/// use robinxx_map::RobinHoodMap;
/// let map = RobinHoodMap::new();
/// map.insert(1, 0);
/// for v in map.iter_mut() { *v = 42; }
/// ```
///
/// # Panics
/// Never panics.
///
/// # Errors
/// Not applicable.
///
/// # Safety
/// Not applicable. This is a safe function, thread-safety is guaranteed
/// internally by `SpinMutex` acquisition.
///
/// # See Also
/// - [`Iter`]
pub struct IterMut<'a, K: RobinHoodKey + PartialEq, V> {
    guard: MutexGuard<'a, RawTable<K, V>>,
    idx: usize,
    remaining: usize,
    _marker: PhantomData<K>,
}

impl<'a, K: RobinHoodKey + PartialEq, V> IterMut<'a, K, V> {
    /// Creates a new mutable iterator over the map.
    ///
    /// # Summary
    /// Initializes traversal state from a locked `RawTable`.
    ///
    /// # Description
    /// Stores the mutex guard and resets the cursor to index 0. Used internally
    /// by `RobinHoodMap::iter_mut()`.
    ///
    /// # Examples
    /// Internal use only.
    ///
    /// # Panics
    /// Never panics.
    ///
    /// # Errors
    /// Not applicable.
    ///
    /// # Safety
    /// Caller must provide an active `MutexGuard` to ensure exclusive access.
    ///
    /// # See Also
    /// - [`RobinHoodMap::iter_mut`](crate::map::RobinHoodMap::iter_mut)
    #[inline]
    pub(crate) fn new(guard: MutexGuard<'a, RawTable<K, V>>) -> Self {
        let remaining = guard.size();
        Self {
            guard,
            idx: 0,
            remaining,
            _marker: PhantomData,
        }
    }
}

impl<'a, K: RobinHoodKey + PartialEq, V> Iterator for IterMut<'a, K, V> {
    type Item = &'a mut V;
    fn next(&mut self) -> Option<Self::Item> {
        while self.remaining > 0 {
            let meta = unsafe { *self.guard.meta_ptr.add(self.idx) };
            if meta != 0 {
                let v = unsafe { &mut *self.guard.vals_ptr.add(self.idx) };
                self.idx += 1;
                self.remaining -= 1;
                return Some(v);
            }
            self.idx += 1;
        }
        None
    }
}

/// Iterator over immutable keys.
///
/// # Summary
/// Yields `&K` for all occupied slots.
///
/// # Description
/// Projects key component from `Iter`.
///
/// # Examples
/// ```
/// use robinxx_map::RobinHoodMap;
/// let map = RobinHoodMap::new();
/// map.insert(1, "a");
/// for k in map.keys() { println!("{}", k); }
/// ```
///
/// # Panics
/// Never panics.
///
/// # Errors
/// Not applicable.
///
/// # Safety
/// Not applicable. This is a safe function, thread-safety is guaranteed
/// internally by `SpinMutex` acquisition.
///
/// # See Also
/// - [`Iter`]
pub struct Keys<'a, K: RobinHoodKey + PartialEq, V> {
    inner: Iter<'a, K, V>,
}

impl<'a, K: RobinHoodKey + PartialEq, V> Keys<'a, K, V> {
    /// Creates a new keys iterator.
    ///
    /// # Summary
    /// Wraps `Iter` to yield only keys.
    ///
    /// # Description
    /// Delegates traversal to the inner `Iter` instance. Used internally
    /// by `RobinHoodMap::keys()`.
    ///
    /// # Examples
    /// Internal use only.
    ///
    /// # Panics
    /// Never panics.
    ///
    /// # Errors
    /// Not applicable.
    ///
    /// # Safety
    /// Inherits lock guarantees from `Iter`.
    ///
    /// # See Also
    /// - [`RobinHoodMap::keys`](crate::map::RobinHoodMap::keys)
    #[inline]
    pub(crate) fn new(guard: MutexGuard<'a, RawTable<K, V>>) -> Self {
        Self {
            inner: Iter::new(guard),
        }
    }
}

impl<'a, K: RobinHoodKey + PartialEq, V> Iterator for Keys<'a, K, V> {
    type Item = &'a K;
    fn next(&mut self) -> Option<Self::Item> {
        self.inner.next().map(|(k, _)| k)
    }
}

/// Iterator over immutable values.
///
/// # Summary
/// Yields `&V` for all occupied slots.
///
/// # Description
/// Projects value component from `Iter`.
///
/// # Examples
/// ```
/// use robinxx_map::RobinHoodMap;
/// let map = RobinHoodMap::new();
/// map.insert(1, "a");
/// for v in map.values() { println!("{}", v); }
/// ```
///
/// # Panics
/// Never panics.
///
/// # Errors
/// Not applicable.
///
/// # Safety
/// Not applicable. This is a safe function, thread-safety is guaranteed
/// internally by `SpinMutex` acquisition.
///
/// # See Also
/// - [`Iter`]
pub struct Values<'a, K: RobinHoodKey + PartialEq, V> {
    inner: Iter<'a, K, V>,
}

impl<'a, K: RobinHoodKey + PartialEq, V> Values<'a, K, V> {
    /// Creates a new values iterator.
    ///
    /// # Summary
    /// Wraps `Iter` to yield only values.
    ///
    /// # Description
    /// Delegates traversal to the inner `Iter` instance. Used internally
    /// by `RobinHoodMap::values()`.
    ///
    /// # Examples
    /// Internal use only.
    ///
    /// # Panics
    /// Never panics.
    ///
    /// # Errors
    /// Not applicable.
    ///
    /// # Safety
    /// Inherits lock guarantees from `Iter`.
    ///
    /// # See Also
    /// - [`RobinHoodMap::values`](crate::map::RobinHoodMap::values)
    #[inline]
    pub(crate) fn new(guard: MutexGuard<'a, RawTable<K, V>>) -> Self {
        Self {
            inner: Iter::new(guard),
        }
    }
}

impl<'a, K: RobinHoodKey + PartialEq, V> Iterator for Values<'a, K, V> {
    type Item = &'a V;
    fn next(&mut self) -> Option<Self::Item> {
        self.inner.next().map(|(_, v)| v)
    }
}

/// Iterator that clears and yields owned elements.
///
/// # Summary
/// Yields `(K, V)` while dropping from map.
///
/// # Description
/// Drains all occupied slots, dropping each after yield. Capacity retained.
///
/// # Examples
/// ```
/// use robinxx_map::RobinHoodMap;
/// let map = RobinHoodMap::new();
/// map.insert(1, "a");
/// let items: Vec<_> = map.drain().collect();
/// assert_eq!(items.len(), 1);
/// ```
///
/// # Panics
/// Never panics.
///
/// # Errors
/// Not applicable.
///
/// # Safety
/// Drops elements safely under lock.
///
/// # See Also
/// - [`clear`](crate::map::RobinHoodMap::clear)
pub struct Drain<'a, K: RobinHoodKey + PartialEq, V> {
    guard: MutexGuard<'a, RawTable<K, V>>,
    idx: usize,
    remaining: usize,
    _marker: PhantomData<(K, V)>,
}

impl<'a, K: RobinHoodKey + PartialEq, V> Drain<'a, K, V> {
    /// Creates a new draining iterator.
    ///
    /// # Summary
    /// Initializes traversal state for owned element extraction.
    ///
    /// # Description
    /// Stores the mutex guard and captures current size. Used internally
    /// by `RobinHoodMap::drain()`.
    ///
    /// # Examples
    /// Internal use only.
    ///
    /// # Panics
    /// Never panics.
    ///
    /// # Errors
    /// Not applicable.
    ///
    /// # Safety
    /// Caller must provide an active `MutexGuard` to prevent concurrent mutation
    /// during drain operation.
    ///
    /// # See Also
    /// - [`RobinHoodMap::drain`](crate::map::RobinHoodMap::drain)
    #[inline]
    pub(crate) fn new(guard: MutexGuard<'a, RawTable<K, V>>) -> Self {
        let remaining = (*guard).size();
        Self {
            guard,
            idx: 0,
            remaining,
            _marker: PhantomData,
        }
    }
}

impl<K: RobinHoodKey + PartialEq, V> Iterator for Drain<'_, K, V> {
    type Item = (K, V);
    fn next(&mut self) -> Option<Self::Item> {
        while self.remaining > 0 {
            let meta = unsafe { *self.guard.meta_ptr.add(self.idx) };
            if meta != 0 {
                let k = unsafe { ptr::read(self.guard.keys_ptr.add(self.idx)) };
                let v = unsafe { ptr::read(self.guard.vals_ptr.add(self.idx)) };
                unsafe {
                    *self.guard.meta_ptr.add(self.idx) = 0;
                };
                (*self.guard).decrement_size();
                self.idx += 1;
                self.remaining -= 1;
                return Some((k, v));
            }
            self.idx += 1;
        }
        None
    }
}