Type Alias ext_php_rs::types::ZendStr
source · pub type ZendStr = zend_string;
Expand description
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
Aliased Type§
struct ZendStr {
pub gc: _zend_refcounted_h,
pub h: u64,
pub len: usize,
pub val: [i8; 1],
}
Fields§
§gc: _zend_refcounted_h
§h: u64
§len: usize
§val: [i8; 1]
Implementations§
source§impl ZendStr
impl ZendStr
sourcepub fn new(str: impl AsRef<[u8]>, persistent: bool) -> ZBox<Self>
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);
sourcepub fn from_c_str(str: &CStr, persistent: bool) -> ZBox<Self>
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);
sourcepub fn new_interned(str: impl AsRef<[u8]>, persistent: bool) -> ZBox<Self>
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);
sourcepub fn interned_from_c_str(str: &CStr, persistent: bool) -> ZBox<Self>
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);
sourcepub fn len(&self) -> usize
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);
sourcepub fn is_empty(&self) -> bool
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);
sourcepub fn as_c_str(&self) -> Result<&CStr>
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.
sourcepub fn as_str(&self) -> Result<&str>
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());
sourcepub fn as_bytes(&self) -> &[u8] ⓘ
pub fn as_bytes(&self) -> &[u8] ⓘ
Returns a reference to the underlying bytes inside the Zend string.
sourcepub fn as_mut_ptr(&mut self) -> *mut ZendStr
pub fn as_mut_ptr(&mut self) -> *mut ZendStr
Returns a mutable pointer to this object