Type Alias ZendHashTable

pub type ZendHashTable = HashTable;

A PHP hashtable.

In PHP, arrays are represented as hashtables. This allows you to push values onto the end of the array like a vector, while also allowing you to insert at arbitrary string key indexes.

A PHP hashtable stores values as Zvals. This allows you to insert different types into the same hashtable. Types must implement IntoZval to be able to be inserted into the hashtable.

Examples

use ext_php_rs::types::ZendHashTable;

let mut ht = ZendHashTable::new();
ht.push(1);
ht.push("Hello, world!");
ht.insert("Like", "Hashtable");

assert_eq!(ht.len(), 3);
assert_eq!(ht.get_index(0).and_then(|zv| zv.long()), Some(1));

Aliased Type

struct ZendHashTable {
    pub gc: _zend_refcounted_h,
    pub u: _zend_array__bindgen_ty_1,
    pub nTableMask: u32,
    pub __bindgen_anon_1: _zend_array__bindgen_ty_2,
    pub nNumUsed: u32,
    pub nNumOfElements: u32,
    pub nTableSize: u32,
    pub nInternalPointer: u32,
    pub nNextFreeElement: i64,
    pub pDestructor: Option<unsafe extern "C" fn(_: *mut _zval_struct)>,
}

Fields

gc: _zend_refcounted_h

u: _zend_array__bindgen_ty_1

nTableMask: u32

__bindgen_anon_1: _zend_array__bindgen_ty_2

nNumUsed: u32

nNumOfElements: u32

nTableSize: u32

nInternalPointer: u32

nNextFreeElement: i64

pDestructor: Option<unsafe extern "C" fn(_: *mut _zval_struct)>

Implementations

impl ZendHashTable

pub fn new() -> ZBox<Self>

Creates a new, empty, PHP hashtable, returned inside a ZBox.

Example

use ext_php_rs::types::ZendHashTable;

let ht = ZendHashTable::new();

Panics

Panics if memory for the hashtable could not be allocated.

pub fn with_capacity(size: u32) -> ZBox<Self>

Creates a new, empty, PHP hashtable with an initial size, returned inside a ZBox.

Parameters

• size - The size to initialize the array with.

Example

use ext_php_rs::types::ZendHashTable;

let ht = ZendHashTable::with_capacity(10);

Panics

Panics if memory for the hashtable could not be allocated.

pub fn len(&self) -> usize

Returns the current number of elements in the array.

Example

use ext_php_rs::types::ZendHashTable;

let mut ht = ZendHashTable::new();

ht.push(1);
ht.push("Hello, world");

assert_eq!(ht.len(), 2);

pub fn is_empty(&self) -> bool

Returns whether the hash table is empty.

Example

use ext_php_rs::types::ZendHashTable;

let mut ht = ZendHashTable::new();

assert_eq!(ht.is_empty(), true);

ht.push(1);
ht.push("Hello, world");

assert_eq!(ht.is_empty(), false);

pub fn clear(&mut self)

Clears the hash table, removing all values.

Example

use ext_php_rs::types::ZendHashTable;

let mut ht = ZendHashTable::new();

ht.insert("test", "hello world");
assert_eq!(ht.is_empty(), false);

ht.clear();
assert_eq!(ht.is_empty(), true);

pub fn get(&self, key: &str) -> Option<&Zval>

Attempts to retrieve a value from the hash table with a string key.

Parameters

• key - The key to search for in the hash table.

Returns

• Some(&Zval) - A reference to the zval at the position in the hash table.
• None - No value at the given position was found.

Example

use ext_php_rs::types::ZendHashTable;

let mut ht = ZendHashTable::new();

ht.insert("test", "hello world");
assert_eq!(ht.get("test").and_then(|zv| zv.str()), Some("hello world"));

pub fn get_mut(&self, key: &str) -> Option<&mut Zval>

Attempts to retrieve a value from the hash table with a string key.

Parameters

• key - The key to search for in the hash table.

Returns

• Some(&Zval) - A reference to the zval at the position in the hash table.
• None - No value at the given position was found.

Example

use ext_php_rs::types::ZendHashTable;

let mut ht = ZendHashTable::new();

ht.insert("test", "hello world");
assert_eq!(ht.get("test").and_then(|zv| zv.str()), Some("hello world"));

pub fn get_index(&self, key: u64) -> Option<&Zval>

Attempts to retrieve a value from the hash table with an index.

Parameters

• key - The key to search for in the hash table.

Returns

• Some(&Zval) - A reference to the zval at the position in the hash table.
• None - No value at the given position was found.

Example

use ext_php_rs::types::ZendHashTable;

let mut ht = ZendHashTable::new();

ht.push(100);
assert_eq!(ht.get_index(0).and_then(|zv| zv.long()), Some(100));

pub fn get_index_mut(&self, key: u64) -> Option<&mut Zval>

Attempts to retrieve a value from the hash table with an index.

Parameters

• key - The key to search for in the hash table.

Returns

• Some(&Zval) - A reference to the zval at the position in the hash table.
• None - No value at the given position was found.

Example

use ext_php_rs::types::ZendHashTable;

let mut ht = ZendHashTable::new();

ht.push(100);
assert_eq!(ht.get_index(0).and_then(|zv| zv.long()), Some(100));

pub fn remove(&mut self, key: &str) -> Option<()>

Attempts to remove a value from the hash table with a string key.

Parameters

• key - The key to remove from the hash table.

Returns

• Some(()) - Key was successfully removed.
• None - No key was removed, did not exist.

Example

use ext_php_rs::types::ZendHashTable;

let mut ht = ZendHashTable::new();

ht.insert("test", "hello world");
assert_eq!(ht.len(), 1);

ht.remove("test");
assert_eq!(ht.len(), 0);

pub fn remove_index(&mut self, key: u64) -> Option<()>

Attempts to remove a value from the hash table with a string key.

Parameters

• key - The key to remove from the hash table.

Returns

• Ok(()) - Key was successfully removed.
• None - No key was removed, did not exist.

Example

use ext_php_rs::types::ZendHashTable;

let mut ht = ZendHashTable::new();

ht.push("hello");
assert_eq!(ht.len(), 1);

ht.remove_index(0);
assert_eq!(ht.len(), 0);

pub fn insert<V>(&mut self, key: &str, val: V) -> Result<()>

where V: IntoZval,

Attempts to insert an item into the hash table, or update if the key already exists. Returns nothing in a result if successful.

Parameters

• key - The key to insert the value at in the hash table.
• value - The value to insert into the hash table.

Returns

Returns nothing in a result on success. Returns an error if the key could not be converted into a CString, or converting the value into a Zval failed.

Example

use ext_php_rs::types::ZendHashTable;

let mut ht = ZendHashTable::new();

ht.insert("a", "A");
ht.insert("b", "B");
ht.insert("c", "C");
assert_eq!(ht.len(), 3);

pub fn insert_at_index<V>(&mut self, key: u64, val: V) -> Result<()>

where V: IntoZval,

Inserts an item into the hash table at a specified index, or updates if the key already exists. Returns nothing in a result if successful.

Parameters

• key - The index at which the value should be inserted.
• val - The value to insert into the hash table.

Returns

Returns nothing in a result on success. Returns an error if converting the value into a Zval failed.

Example

use ext_php_rs::types::ZendHashTable;

let mut ht = ZendHashTable::new();

ht.insert_at_index(0, "A");
ht.insert_at_index(5, "B");
ht.insert_at_index(0, "C"); // notice overriding index 0
assert_eq!(ht.len(), 2);

pub fn push<V>(&mut self, val: V) -> Result<()>

where V: IntoZval,

Pushes an item onto the end of the hash table. Returns a result containing nothing if the element was successfully inserted.

Parameters

• val - The value to insert into the hash table.

Returns

Returns nothing in a result on success. Returns an error if converting the value into a Zval failed.

Example

use ext_php_rs::types::ZendHashTable;

let mut ht = ZendHashTable::new();

ht.push("a");
ht.push("b");
ht.push("c");
assert_eq!(ht.len(), 3);

pub fn has_numerical_keys(&self) -> bool

Checks if the hashtable only contains numerical keys.

Returns

True if all keys on the hashtable are numerical.

Example

use ext_php_rs::types::ZendHashTable;

let mut ht = ZendHashTable::new();

ht.push(0);
ht.push(3);
ht.push(9);
assert!(ht.has_numerical_keys());

ht.insert("obviously not numerical", 10);
assert!(!ht.has_numerical_keys());

pub fn has_sequential_keys(&self) -> bool

Checks if the hashtable has numerical, sequential keys.

Returns

True if all keys on the hashtable are numerical and are in sequential order (i.e. starting at 0 and not skipping any keys).

Example

use ext_php_rs::types::ZendHashTable;

let mut ht = ZendHashTable::new();

ht.push(0);
ht.push(3);
ht.push(9);
assert!(ht.has_sequential_keys());

ht.insert_at_index(90, 10);
assert!(!ht.has_sequential_keys());

pub fn values(&self) -> Values<'_>

Returns an iterator over the values contained inside the hashtable, as if it was a set or list.

Example

use ext_php_rs::types::ZendHashTable;

let mut ht = ZendHashTable::new();

for val in ht.values() {
    dbg!(val);
}

pub fn iter(&self) -> Iter<'_>

Returns an iterator over the key(s) and value contained inside the hashtable.

Example

use ext_php_rs::types::{ZendHashTable, ArrayKey};

let mut ht = ZendHashTable::new();

for (key, val) in ht.iter() {
    match &key {
        ArrayKey::Long(index) => {
        }
        ArrayKey::String(key) => {
        }
    }
    dbg!(key, val);
}

Trait Implementations

impl Debug for ZendHashTable

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

Formats the value using the given formatter.

impl<'a> FromZval<'a> for &'a ZendHashTable

const TYPE: DataType = DataType::Array

The corresponding type of the implemented value in PHP.

fn from_zval(zval: &'a Zval) -> Option<Self>

Attempts to retrieve an instance of Self from a reference to a Zval.

impl<'a> IntoIterator for &'a ZendHashTable

fn into_iter(self) -> Self::IntoIter

Returns an iterator over the key(s) and value contained inside the hashtable.

Example

use ext_php_rs::types::ZendHashTable;

let mut ht = ZendHashTable::new();

for (key, val) in ht.iter() {
//   ^ Index if inserted at an index.
//        ^ Optional string key, if inserted like a hashtable.
//             ^ Inserted value.

    dbg!(key, val);
}

type Item = (ArrayKey, &'a _zval_struct)

The type of the elements being iterated over.

type IntoIter = Iter<'a>

Which kind of iterator are we turning this into?

impl ToOwned for ZendHashTable

type Owned = ZBox<_zend_array>

The resulting type after obtaining ownership.

fn to_owned(&self) -> Self::Owned

Creates owned data from borrowed data, usually by cloning.

fn clone_into(&self, target: &mut Self::Owned)

Uses borrowed data to replace owned data, usually by cloning.

impl ZBoxable for ZendHashTable

fn free(&mut self)

Frees the memory pointed to by self, calling any destructors required in the process.