Type Definition ext_php_rs::types::ZendStr

pub type ZendStr = zend_string;

A borrowed Zend string.

Although this object does implement Sized, it is in fact not sized. As C cannot represent unsized types, an array of size 1 is used at the end of the type to represent the contents of the string, therefore this type is actually unsized. All constructors return ZBox<ZendStr>, the owned variant.

Once the ptr_metadata feature lands in stable rust, this type can potentially be changed to a DST using slices and metadata. See the tracking issue here: https://github.com/rust-lang/rust/issues/81513

Implementations

impl ZendStr

pub fn new(str: impl AsRef<[u8]>, persistent: bool) -> ZBox<Self>

Creates a new Zend string from a slice of bytes.

Parameters

• str - String content.
• persistent - Whether the string should persist through the request boundary.

Panics

Panics if the function was unable to allocate memory for the Zend string.

Safety

When passing persistent as false, the caller must ensure that the object does not attempt to live after the request finishes. When a request starts and finishes in PHP, the Zend heap is deallocated and a new one is created, which would leave a dangling pointer in the ZBox.

Example

use ext_php_rs::types::ZendStr;

let s = ZendStr::new("Hello, world!", false);
let php = ZendStr::new([80, 72, 80], false);

pub fn from_c_str(str: &CStr, persistent: bool) -> ZBox<Self>

Creates a new Zend string from a CStr.

Parameters

• str - String content.
• persistent - Whether the string should persist through the request boundary.

Panics

Panics if the function was unable to allocate memory for the Zend string.

Safety

When passing persistent as false, the caller must ensure that the object does not attempt to live after the request finishes. When a request starts and finishes in PHP, the Zend heap is deallocated and a new one is created, which would leave a dangling pointer in the ZBox.

Example

use ext_php_rs::types::ZendStr;
use std::ffi::CString;

let c_s = CString::new("Hello world!").unwrap();
let s = ZendStr::from_c_str(&c_s, false);

pub fn new_interned(str: impl AsRef<[u8]>, persistent: bool) -> ZBox<Self>

Creates a new interned Zend string from a slice of bytes.

An interned string is only ever stored once and is immutable. PHP stores the string in an internal hashtable which stores the interned strings.

As Zend hashtables are not thread-safe, a mutex is used to prevent two interned strings from being created at the same time.

Interned strings are not used very often. You should almost always use a regular zend string, except in the case that you know you will use a string that PHP will already have interned, such as “PHP”.

Parameters

• str - String content.
• persistent - Whether the string should persist through the request boundary.

Panics

Panics under the following circumstances:

• The function used to create interned strings has not been set.
• The function could not allocate enough memory for the Zend string.

Safety

When passing persistent as false, the caller must ensure that the object does not attempt to live after the request finishes. When a request starts and finishes in PHP, the Zend heap is deallocated and a new one is created, which would leave a dangling pointer in the ZBox.

Example

use ext_php_rs::types::ZendStr;

let s = ZendStr::new_interned("PHP", true);

pub fn interned_from_c_str(str: &CStr, persistent: bool) -> ZBox<Self>

Creates a new interned Zend string from a CStr.

An interned string is only ever stored once and is immutable. PHP stores the string in an internal hashtable which stores the interned strings.

As Zend hashtables are not thread-safe, a mutex is used to prevent two interned strings from being created at the same time.

Interned strings are not used very often. You should almost always use a regular zend string, except in the case that you know you will use a string that PHP will already have interned, such as “PHP”.

Parameters

• str - String content.
• persistent - Whether the string should persist through the request boundary.

Panics

Panics under the following circumstances:

• The function used to create interned strings has not been set.
• The function could not allocate enough memory for the Zend string.

Safety

When passing persistent as false, the caller must ensure that the object does not attempt to live after the request finishes. When a request starts and finishes in PHP, the Zend heap is deallocated and a new one is created, which would leave a dangling pointer in the ZBox.

Example

use ext_php_rs::types::ZendStr;
use std::ffi::CString;

let c_s = CString::new("PHP").unwrap();
let s = ZendStr::interned_from_c_str(&c_s, true);

pub fn len(&self) -> usize

Returns the length of the string.

Example

use ext_php_rs::types::ZendStr;

let s = ZendStr::new("hello, world!", false);
assert_eq!(s.len(), 13);

pub fn is_empty(&self) -> bool

Returns true if the string is empty, false otherwise.

Example

use ext_php_rs::types::ZendStr;

let s = ZendStr::new("hello, world!", false);
assert_eq!(s.is_empty(), false);

pub fn as_c_str(&self) -> Result<&CStr>

Attempts to return a reference to the underlying bytes inside the Zend string as a CStr.

Returns an Error::InvalidCString variant if the string contains null bytes.

pub fn as_str(&self) -> Result<&str>

Attempts to return a reference to the underlying bytes inside the Zend string.

Returns an Error::InvalidUtf8 variant if the str contains non-UTF-8 characters.

Example

use ext_php_rs::types::ZendStr;

let s = ZendStr::new("hello, world!", false);
assert!(s.as_str().is_ok());

pub fn as_bytes(&self) -> &[u8]

Returns a reference to the underlying bytes inside the Zend string.

pub fn as_ptr(&self) -> *const ZendStr

Returns a raw pointer to this object

pub fn as_mut_ptr(&mut self) -> *mut ZendStr

Returns a mutable pointer to this object

Trait Implementations

impl AsRef<[u8]> for ZendStr

fn as_ref(&self) -> &[u8]

Converts this type into a shared reference of the (usually inferred) input type.

impl Debug for ZendStr

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

Formats the value using the given formatter.

impl<T> PartialEq<T> for ZendStrwhere
    T: AsRef<[u8]>,

fn eq(&self, other: &T) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl ToOwned for ZendStr

type Owned = ZBox<_zend_string>

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 ZendStr

fn free(&mut self)

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