Type Definition ext_php_rs::types::ZendHashTable[−][src]

pub type ZendHashTable = HashTable;

Expand description

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));

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_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 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 sucessfully 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 iter(&self) -> Iter<'_>

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 (idx, key, val) in ht.iter() {
//   ^ Index if inserted at an index.
//        ^ Optional string key, if inserted like a hashtable.
//             ^ Inserted value.

    dbg!(idx, key, val);
}

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);
}

Trait Implementations

impl Debug for ZendHashTable

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

Formats the value using the given formatter. Read more

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

const TYPE: DataType

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. Read more

impl ToOwned for ZendHashTable

type Owned = ZBox<ZendHashTable>

The resulting type after obtaining ownership.

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

Creates owned data from borrowed data, usually by cloning. Read more

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

🔬 This is a nightly-only experimental API. (toowned_clone_into)

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

impl ZBoxable for ZendHashTable

fn free(&mut self)

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