21330140731

Committed 25 Jan 2026 09:08AM UTC coverage: 35.88% (+0.9%) from 34.976%

Build # 21330140731

Build Type

Pull #611

github

Committed by

web-flow

Commit Message

Merge 876e7a6d0 into 6013c2e62

Pull Request Pull Request #611: feat(array): Entry API (Issue #525)

Coverage Stats

62 of 100 new or added lines in 2 files covered. (62.0%)

59 existing lines in 1 file now uncovered.

1907 of 5315 relevant lines covered (35.88%)

14.4 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

60.71

/src/types/array/entry.rs

//! Entry API for [`ZendHashTable`], similar to Rust's `std::collections::hash_map::Entry`.
//!
//! This module provides an ergonomic API for working with entries in a PHP
//! hashtable, allowing conditional insertion or modification based on whether
//! a key already exists.
//!
//! # Examples
//!
//! ```no_run
//! use ext_php_rs::types::ZendHashTable;
//!
//! let mut ht = ZendHashTable::new();
//!
//! // Insert a default value if the key doesn't exist
//! ht.entry("counter").or_insert(0i64);
//!
//! // Modify the value if it exists
//! ht.entry("counter").and_modify(|v| {
//!     if let Some(n) = v.long() {
//!         v.set_long(n + 1);
//!     }
//! });
//!
//! // Or use or_insert_with for lazy initialization
//! ht.entry("computed").or_insert_with(|| "computed value");
//! ```

use std::ffi::CString;

use super::{ArrayKey, ZendHashTable};
use crate::{
    convert::IntoZval,
    error::{Error, Result},
    ffi::{
        zend_hash_index_find, zend_hash_index_update, zend_hash_str_find, zend_hash_str_update,
        zend_ulong,
    },
    types::Zval,
};

/// A view into a single entry in a [`ZendHashTable`], which may either be vacant or
/// occupied.
///
/// This enum is constructed from the [`entry`] method on [`ZendHashTable`].
///
/// [`entry`]: ZendHashTable::entry
pub enum Entry<'a, 'k> {
    /// An occupied entry.
    Occupied(OccupiedEntry<'a, 'k>),
    /// A vacant entry.
    Vacant(VacantEntry<'a, 'k>),
}

/// A view into an occupied entry in a [`ZendHashTable`].
///
/// It is part of the [`Entry`] enum.
pub struct OccupiedEntry<'a, 'k> {
    ht: &'a mut ZendHashTable,
    key: ArrayKey<'k>,
}

/// A view into a vacant entry in a [`ZendHashTable`].
///
/// It is part of the [`Entry`] enum.
pub struct VacantEntry<'a, 'k> {
    ht: &'a mut ZendHashTable,
    key: ArrayKey<'k>,
}

impl<'a, 'k> Entry<'a, 'k> {
    /// Ensures a value is in the entry by inserting the default if empty, and
    /// returns a mutable reference to the value in the entry.
    ///
    /// # Parameters
    ///
    /// * `default` - The default value to insert if the entry is vacant.
    ///
    /// # Returns
    ///
    /// A result containing a mutable reference to the value, or an error if
    /// the insertion failed.
    ///
    /// # Errors
    ///
    /// Returns an error if the value conversion to [`Zval`] fails or if
    /// the key contains a null byte (for string keys).
    ///
    /// # Example
    ///
    /// ```no_run
    /// use ext_php_rs::types::ZendHashTable;
    ///
    /// let mut ht = ZendHashTable::new();
    /// ht.entry("key").or_insert("default value");
    /// assert_eq!(ht.get("key").and_then(|v| v.str()), Some("default value"));
    /// ```
    pub fn or_insert<V: IntoZval>(self, default: V) -> Result<&'a mut Zval> {
        match self {
            Entry::Occupied(entry) => entry.into_mut(),
            Entry::Vacant(entry) => entry.insert(default),
        }
    }

    /// Ensures a value is in the entry by inserting the result of the default
    /// function if empty, and returns a mutable reference to the value in the
    /// entry.
    ///
    /// # Parameters
    ///
    /// * `default` - A function that returns the default value to insert.
    ///
    /// # Returns
    ///
    /// A result containing a mutable reference to the value, or an error if
    /// the insertion failed.
    ///
    /// # Errors
    ///
    /// Returns an error if the value conversion to [`Zval`] fails or if
    /// the key contains a null byte (for string keys).
    ///
    /// # Example
    ///
    /// ```no_run
    /// use ext_php_rs::types::ZendHashTable;
    ///
    /// let mut ht = ZendHashTable::new();
    /// ht.entry("key").or_insert_with(|| "computed value");
    /// ```
    pub fn or_insert_with<V: IntoZval, F: FnOnce() -> V>(self, default: F) -> Result<&'a mut Zval> {
        match self {
            Entry::Occupied(entry) => entry.into_mut(),
            Entry::Vacant(entry) => entry.insert(default()),
        }
    }

    /// Ensures a value is in the entry by inserting the result of the default
    /// function if empty. The function receives a reference to the key.
    ///
    /// # Parameters
    ///
    /// * `default` - A function that takes the key and returns the default value.
    ///
    /// # Returns
    ///
    /// A result containing a mutable reference to the value, or an error if
    /// the insertion failed.
    ///
    /// # Errors
    ///
    /// Returns an error if the value conversion to [`Zval`] fails or if
    /// the key contains a null byte (for string keys).
    ///
    /// # Example
    ///
    /// ```no_run
    /// use ext_php_rs::types::ZendHashTable;
    ///
    /// let mut ht = ZendHashTable::new();
    /// ht.entry("key").or_insert_with_key(|k| format!("value for {}", k));
    /// ```
    pub fn or_insert_with_key<V: IntoZval, F: FnOnce(&ArrayKey<'k>) -> V>(
        self,
        default: F,
    ) -> Result<&'a mut Zval> {
        match self {
            Entry::Occupied(entry) => entry.into_mut(),
            Entry::Vacant(entry) => {
                let value = default(entry.key());
                entry.insert(value)
            }
        }
    }

    /// Returns a reference to this entry's key.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use ext_php_rs::types::{ZendHashTable, ArrayKey};
    ///
    /// let mut ht = ZendHashTable::new();
    /// assert_eq!(ht.entry("key").key(), &ArrayKey::Str("key"));
    /// ```
    #[must_use]
    pub fn key(&self) -> &ArrayKey<'k> {
        match self {
            Entry::Occupied(entry) => entry.key(),
            Entry::Vacant(entry) => entry.key(),
        }
    }

    /// Provides in-place mutable access to an occupied entry before any
    /// potential inserts into the map.
    ///
    /// # Parameters
    ///
    /// * `f` - A function that modifies the value in place.
    ///
    /// # Returns
    ///
    /// The entry, allowing for method chaining.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use ext_php_rs::types::ZendHashTable;
    ///
    /// let mut ht = ZendHashTable::new();
    /// ht.insert("counter", 0i64);
    ///
    /// ht.entry("counter")
    ///     .and_modify(|v| {
    ///         if let Some(n) = v.long() {
    ///             v.set_long(n + 1);
    ///         }
    ///     })
    ///     .or_insert(0i64);
    /// ```
    #[must_use]
    pub fn and_modify<F: FnOnce(&mut Zval)>(self, f: F) -> Self {
        match self {
            Entry::Occupied(mut entry) => {
                if let Ok(value) = entry.get_mut() {
                    f(value);
                }
                Entry::Occupied(entry)
            }
            Entry::Vacant(entry) => Entry::Vacant(entry),
        }
    }
}

impl<'a, 'k> Entry<'a, 'k>
where
    'k: 'a,
{
    /// Ensures a value is in the entry by inserting the default value if empty,
    /// and returns a mutable reference to the value in the entry.
    ///
    /// This is a convenience method that uses `Default::default()` as the
    /// default value.
    ///
    /// # Returns
    ///
    /// A result containing a mutable reference to the value, or an error if
    /// the insertion failed.
    ///
    /// # Errors
    ///
    /// Returns an error if the key contains a null byte (for string keys).
    ///
    /// # Example
    ///
    /// ```no_run
    /// use ext_php_rs::types::ZendHashTable;
    ///
    /// let mut ht = ZendHashTable::new();
    /// // Inserts a null Zval if the key doesn't exist
    /// ht.entry("key").or_default();
    /// ```
    pub fn or_default(self) -> Result<&'a mut Zval> {
        match self {
            Entry::Occupied(entry) => entry.into_mut(),
            Entry::Vacant(entry) => entry.insert(Zval::new()),
        }
    }
}

impl<'a, 'k> OccupiedEntry<'a, 'k> {
    /// Creates a new occupied entry.
    pub(super) fn new(ht: &'a mut ZendHashTable, key: ArrayKey<'k>) -> Self {
        Self { ht, key }
    }

    /// Gets a reference to the key in the entry.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use ext_php_rs::types::{ZendHashTable, ArrayKey};
    ///
    /// let mut ht = ZendHashTable::new();
    /// ht.insert("key", "value");
    ///
    /// if let ext_php_rs::types::array::Entry::Occupied(entry) = ht.entry("key") {
    ///     assert_eq!(entry.key(), &ArrayKey::Str("key"));
    /// }
    /// ```
    #[must_use]
    pub fn key(&self) -> &ArrayKey<'k> {
        &self.key
    }

    /// Gets a reference to the value in the entry.
    ///
    /// # Returns
    ///
    /// A result containing a reference to the value, or an error if
    /// the key conversion failed.
    ///
    /// # Errors
    ///
    /// Returns an error if the key contains a null byte (for string keys).
    ///
    /// # Example
    ///
    /// ```no_run
    /// use ext_php_rs::types::ZendHashTable;
    ///
    /// let mut ht = ZendHashTable::new();
    /// ht.insert("key", "value");
    ///
    /// if let ext_php_rs::types::array::Entry::Occupied(entry) = ht.entry("key") {
    ///     assert_eq!(entry.get().ok().and_then(|v| v.str()), Some("value"));
    /// }
    /// ```
    pub fn get(&self) -> Result<&Zval> {
        get_value(&self.key, self.ht).ok_or(Error::InvalidCString)
    }

    /// Gets a mutable reference to the value in the entry.
    ///
    /// # Returns
    ///
    /// A result containing a mutable reference to the value, or an error if
    /// the key conversion failed.
    ///
    /// # Errors
    ///
    /// Returns an error if the key contains a null byte (for string keys).
    ///
    /// # Example
    ///
    /// ```no_run
    /// use ext_php_rs::types::ZendHashTable;
    ///
    /// let mut ht = ZendHashTable::new();
    /// ht.insert("counter", 0i64);
    ///
    /// if let ext_php_rs::types::array::Entry::Occupied(mut entry) = ht.entry("counter") {
    ///     if let Ok(v) = entry.get_mut() {
    ///         if let Some(n) = v.long() {
    ///             v.set_long(n + 1);
    ///         }
    ///     }
    /// }
    /// ```
    pub fn get_mut(&mut self) -> Result<&mut Zval> {
        get_value_mut(&self.key, self.ht).ok_or(Error::InvalidCString)
    }

    /// Converts the entry into a mutable reference to the value.
    ///
    /// If you need multiple references to the `OccupiedEntry`, see [`get_mut`].
    ///
    /// [`get_mut`]: OccupiedEntry::get_mut
    ///
    /// # Returns
    ///
    /// A result containing a mutable reference to the value with the entry's
    /// lifetime, or an error if the key conversion failed.
    ///
    /// # Errors
    ///
    /// Returns an error if the key contains a null byte (for string keys).
    ///
    /// # Example
    ///
    /// ```no_run
    /// use ext_php_rs::types::ZendHashTable;
    ///
    /// let mut ht = ZendHashTable::new();
    /// ht.insert("key", "value");
    ///
    /// if let ext_php_rs::types::array::Entry::Occupied(entry) = ht.entry("key") {
    ///     let value = entry.into_mut().unwrap();
    ///     // value has the lifetime of the hashtable borrow
    /// }
    /// ```
    pub fn into_mut(self) -> Result<&'a mut Zval> {
        get_value_mut(&self.key, self.ht).ok_or(Error::InvalidCString)
    }

    /// Sets the value of the entry, returning the old value.
    ///
    /// # Parameters
    ///
    /// * `value` - The new value to set.
    ///
    /// # Returns
    ///
    /// A result containing the old value (shallow cloned), or an error if the
    /// insertion failed.
    ///
    /// # Errors
    ///
    /// Returns an error if the value conversion to [`Zval`] fails or if
    /// the key contains a null byte (for string keys).
    ///
    /// # Example
    ///
    /// ```no_run
    /// use ext_php_rs::types::ZendHashTable;
    ///
    /// let mut ht = ZendHashTable::new();
    /// ht.insert("key", "old");
    ///
    /// if let ext_php_rs::types::array::Entry::Occupied(mut entry) = ht.entry("key") {
    ///     let old = entry.insert("new").unwrap();
    ///     assert_eq!(old.str(), Some("old"));
    /// }
    /// ```
    pub fn insert<V: IntoZval>(&mut self, value: V) -> Result<Zval> {
        let old = self.get()?.shallow_clone();
        insert_value(&self.key, self.ht, value)?;
        Ok(old)
    }

    /// Takes ownership of the key and value from the entry, removing it from
    /// the hashtable.
    ///
    /// # Returns
    ///
    /// A result containing a tuple of the key and the removed value (shallow
    /// cloned), or an error if the removal failed.
    ///
    /// # Errors
    ///
    /// Returns an error if the key contains a null byte (for string keys).
    ///
    /// # Example
    ///
    /// ```no_run
    /// use ext_php_rs::types::ZendHashTable;
    ///
    /// let mut ht = ZendHashTable::new();
    /// ht.insert("key", "value");
    ///
    /// if let ext_php_rs::types::array::Entry::Occupied(entry) = ht.entry("key") {
    ///     let (key, value) = entry.remove_entry().unwrap();
    ///     assert!(ht.get("key").is_none());
    /// }
    /// ```
    pub fn remove_entry(self) -> Result<(ArrayKey<'k>, Zval)> {
        let value = self.get()?.shallow_clone();
        self.ht.remove(self.key.clone());
        Ok((self.key, value))
    }

    /// Removes the value from the entry, returning it.
    ///
    /// # Returns
    ///
    /// A result containing the removed value (shallow cloned), or an error if
    /// the removal failed.
    ///
    /// # Errors
    ///
    /// Returns an error if the key contains a null byte (for string keys).
    ///
    /// # Example
    ///
    /// ```no_run
    /// use ext_php_rs::types::ZendHashTable;
    ///
    /// let mut ht = ZendHashTable::new();
    /// ht.insert("key", "value");
    ///
    /// if let ext_php_rs::types::array::Entry::Occupied(entry) = ht.entry("key") {
    ///     let value = entry.remove().unwrap();
    ///     assert_eq!(value.str(), Some("value"));
    /// }
    /// ```
    pub fn remove(self) -> Result<Zval> {
        let value = self.get()?.shallow_clone();
        self.ht.remove(self.key);
        Ok(value)
    }
}

impl<'a, 'k> VacantEntry<'a, 'k> {
    /// Creates a new vacant entry.
    pub(super) fn new(ht: &'a mut ZendHashTable, key: ArrayKey<'k>) -> Self {
        Self { ht, key }
    }

    /// Gets a reference to the key that would be used when inserting a value
    /// through the `VacantEntry`.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use ext_php_rs::types::{ZendHashTable, ArrayKey};
    ///
    /// let mut ht = ZendHashTable::new();
    ///
    /// if let ext_php_rs::types::array::Entry::Vacant(entry) = ht.entry("key") {
    ///     assert_eq!(entry.key(), &ArrayKey::Str("key"));
    /// }
    /// ```
    #[must_use]
    pub fn key(&self) -> &ArrayKey<'k> {
        &self.key
    }

    /// Take ownership of the key.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use ext_php_rs::types::{ZendHashTable, ArrayKey};
    ///
    /// let mut ht = ZendHashTable::new();
    ///
    /// if let ext_php_rs::types::array::Entry::Vacant(entry) = ht.entry("key") {
    ///     let key = entry.into_key();
    ///     assert_eq!(key, ArrayKey::Str("key"));
    /// }
    /// ```
    #[must_use]
    pub fn into_key(self) -> ArrayKey<'k> {
        self.key
    }

    /// Sets the value of the entry with the `VacantEntry`'s key, and returns
    /// a mutable reference to it.
    ///
    /// # Parameters
    ///
    /// * `value` - The value to insert.
    ///
    /// # Returns
    ///
    /// A result containing a mutable reference to the inserted value, or an
    /// error if the insertion failed.
    ///
    /// # Errors
    ///
    /// Returns an error if the value conversion to [`Zval`] fails or if
    /// the key contains a null byte (for string keys).
    ///
    /// # Example
    ///
    /// ```no_run
    /// use ext_php_rs::types::ZendHashTable;
    ///
    /// let mut ht = ZendHashTable::new();
    ///
    /// if let ext_php_rs::types::array::Entry::Vacant(entry) = ht.entry("key") {
    ///     entry.insert("value");
    /// }
    /// assert_eq!(ht.get("key").and_then(|v| v.str()), Some("value"));
    /// ```
    pub fn insert<V: IntoZval>(self, value: V) -> Result<&'a mut Zval> {
        insert_value(&self.key, self.ht, value)?;
        get_value_mut(&self.key, self.ht).ok_or(Error::InvalidCString)
    }
}

/// Helper function to get a value from the hashtable by key.
fn get_value<'a>(key: &ArrayKey<'_>, ht: &'a ZendHashTable) -> Option<&'a Zval> {
    match key {
        ArrayKey::Long(index) => unsafe {
            #[allow(clippy::cast_sign_loss)]
            zend_hash_index_find(ht, *index as zend_ulong).as_ref()
        },
        ArrayKey::String(key) => unsafe {
            zend_hash_str_find(ht, CString::new(key.as_str()).ok()?.as_ptr(), key.len()).as_ref()
        },
        ArrayKey::Str(key) => unsafe {
            zend_hash_str_find(ht, CString::new(*key).ok()?.as_ptr(), key.len()).as_ref()
        },
    }
}

/// Helper function to get a mutable value from the hashtable by key.
fn get_value_mut<'a>(key: &ArrayKey<'_>, ht: &'a mut ZendHashTable) -> Option<&'a mut Zval> {
    match key {
        ArrayKey::Long(index) => unsafe {
            #[allow(clippy::cast_sign_loss)]
            zend_hash_index_find(ht, *index as zend_ulong).as_mut()
        },
        ArrayKey::String(key) => unsafe {
            zend_hash_str_find(
                ht,
                CString::new(key.as_str()).ok()?.as_ptr(),
                key.len() as _,
            )
            .as_mut()
        },
        ArrayKey::Str(key) => unsafe {
            zend_hash_str_find(ht, CString::new(*key).ok()?.as_ptr(), key.len() as _).as_mut()
        },
    }
}

/// Helper function to insert a value into the hashtable by key.
fn insert_value<V: IntoZval>(key: &ArrayKey<'_>, ht: &mut ZendHashTable, value: V) -> Result<()> {
    let mut val = value.into_zval(false)?;
    match key {
        ArrayKey::Long(index) => {
            unsafe {
                #[allow(clippy::cast_sign_loss)]
                zend_hash_index_update(ht, *index as zend_ulong, &raw mut val)
            };
        }
        ArrayKey::String(key) => {
            unsafe {
                zend_hash_str_update(
                    ht,
                    CString::new(key.as_str())?.as_ptr(),
                    key.len(),
                    &raw mut val,
                )
            };
        }
        ArrayKey::Str(key) => {
            unsafe {
                zend_hash_str_update(ht, CString::new(*key)?.as_ptr(), key.len(), &raw mut val)
            };
        }
    }
    val.release();
    Ok(())
}

#[cfg(test)]
#[cfg(feature = "embed")]
mod tests {
    use super::*;
    use crate::embed::Embed;

    #[test]
    fn test_entry_or_insert() {
        Embed::run(|| {
            let mut ht = ZendHashTable::new();

            // Insert into vacant entry
            let result = ht.entry("key").or_insert("value");
            assert!(result.is_ok());
            assert_eq!(ht.get("key").and_then(|v| v.str()), Some("value"));

            // Entry already exists, should return existing value
            let result = ht.entry("key").or_insert("other");
            assert!(result.is_ok());
            assert_eq!(ht.get("key").and_then(|v| v.str()), Some("value"));
        });
    }

    #[test]
    fn test_entry_or_insert_with() {
        Embed::run(|| {
            let mut ht = ZendHashTable::new();

            let result = ht.entry("key").or_insert_with(|| "computed");
            assert!(result.is_ok());
            assert_eq!(ht.get("key").and_then(|v| v.str()), Some("computed"));
        });
    }

    #[test]
    fn test_entry_and_modify() {
        Embed::run(|| {
            let mut ht = ZendHashTable::new();
            let _ = ht.insert("counter", 5i64);

            let result = ht
                .entry("counter")
                .and_modify(|v| {
                    if let Some(n) = v.long() {
                        v.set_long(n + 1);
                    }
                })
                .or_insert(0i64);

            assert!(result.is_ok());
            assert_eq!(ht.get("counter").and_then(Zval::long), Some(6));
        });
    }

    #[test]
    fn test_entry_and_modify_vacant() {
        Embed::run(|| {
            let mut ht = ZendHashTable::new();

            // and_modify on vacant entry should be a no-op
            let result = ht
                .entry("key")
                .and_modify(|v| {
                    v.set_long(100);
                })
                .or_insert(42i64);

            assert!(result.is_ok());
            assert_eq!(ht.get("key").and_then(Zval::long), Some(42));
        });
    }

    #[test]
    fn test_occupied_entry_insert() {
        Embed::run(|| {
            let mut ht = ZendHashTable::new();
            let _ = ht.insert("key", "old");

            if let Entry::Occupied(mut entry) = ht.entry("key") {
                let old = entry.insert("new").expect("insert should succeed");
                assert_eq!(old.str(), Some("old"));
            }
            assert_eq!(ht.get("key").and_then(|v| v.str()), Some("new"));
        });
    }

    #[test]
    fn test_occupied_entry_remove() {
        Embed::run(|| {
            let mut ht = ZendHashTable::new();
            let _ = ht.insert("key", "value");

            if let Entry::Occupied(entry) = ht.entry("key") {
                let value = entry.remove().expect("remove should succeed");
                assert_eq!(value.str(), Some("value"));
            }
            assert!(ht.get("key").is_none());
        });
    }

    #[test]
    fn test_entry_with_numeric_key() {
        Embed::run(|| {
            let mut ht = ZendHashTable::new();

            let result = ht.entry(42i64).or_insert("value");
            assert!(result.is_ok());
            assert_eq!(ht.get_index(42).and_then(|v| v.str()), Some("value"));
        });
    }

    #[test]
    fn test_vacant_entry_into_key() {
        Embed::run(|| {
            let mut ht = ZendHashTable::new();

            if let Entry::Vacant(entry) = ht.entry("my_key") {
                let key = entry.into_key();
                assert_eq!(key, ArrayKey::Str("my_key"));
            }
        });
    }
}

extphprs / ext-php-rs / 21330140731

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous