ext_php_rs/describe/
abi.rs

1//! ABI-stable standard library types.
2//!
3//! The description module is used by the `cargo-php` sub-command to retrieve
4//! information about the extension. As Rust does not have a stable ABI, it is
5//! not as simple as working in the Rust domain, as if the CLI and extension
6//! Rust versions do not match, it cannot be assumed that the types have the
7//! same memory layout.
8//!
9//! This module contains thin wrappers around standard library types used by the
10//! describe function to provide some sort of ABI-stability.
11//!
12//! As a general rule of thumb, no Rust type is ABI-stable. Strictly speaking,
13//! [`usize`] should not be in use, but rather `size_t` or a similar type,
14//! however these are currently unstable.
15
16use std::{fmt::Display, ops::Deref, vec::Vec as StdVec};
17
18/// An immutable, ABI-stable [`Vec`][std::vec::Vec].
19#[repr(C)]
20#[derive(Debug)]
21pub struct Vec<T> {
22    ptr: *mut T,
23    len: usize,
24}
25
26impl<T> Deref for Vec<T> {
27    type Target = [T];
28
29    fn deref(&self) -> &Self::Target {
30        unsafe { std::slice::from_raw_parts(self.ptr, self.len) }
31    }
32}
33
34impl<T> Drop for Vec<T> {
35    fn drop(&mut self) {
36        unsafe {
37            let _ = Box::from_raw(std::ptr::slice_from_raw_parts_mut(self.ptr, self.len));
38        };
39    }
40}
41
42impl<T> From<StdVec<T>> for Vec<T> {
43    fn from(vec: StdVec<T>) -> Self {
44        let vec = vec.into_boxed_slice();
45        let len = vec.len();
46        let ptr = Box::into_raw(vec).cast::<T>();
47
48        Self { ptr, len }
49    }
50}
51
52impl<T> PartialEq for Vec<T>
53where
54    T: PartialEq,
55{
56    fn eq(&self, other: &Self) -> bool {
57        self.len == other.len && self.as_ref() == other.as_ref()
58    }
59}
60
61/// An immutable, ABI-stable borrowed [`&'static str`][str].
62#[repr(C)]
63#[derive(Debug)]
64pub struct Str {
65    ptr: *const u8,
66    len: usize,
67}
68
69impl Str {
70    /// Returns the string as a string slice.
71    ///
72    /// The lifetime is `'static` and can outlive the [`Str`] object, as you can
73    /// only initialize a [`Str`] through a static reference.
74    #[must_use]
75    pub fn str(&self) -> &'static str {
76        unsafe { std::str::from_utf8_unchecked(std::slice::from_raw_parts(self.ptr, self.len)) }
77    }
78}
79
80impl From<&'static str> for Str {
81    fn from(val: &'static str) -> Self {
82        let ptr = val.as_ptr();
83        let len = val.len();
84        Self { ptr, len }
85    }
86}
87
88impl AsRef<str> for Str {
89    fn as_ref(&self) -> &str {
90        self.str()
91    }
92}
93
94impl Display for Str {
95    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
96        self.str().fmt(f)
97    }
98}
99
100impl PartialEq for Str {
101    fn eq(&self, other: &Self) -> bool {
102        self.len == other.len && self.str() == other.str()
103    }
104}
105
106/// An ABI-stable String
107#[repr(C)]
108#[derive(Debug, PartialEq)]
109pub struct RString {
110    inner: Vec<u8>,
111}
112
113impl RString {
114    /// Returns the string as a string slice.
115    ///
116    /// # Panics
117    ///
118    /// * If the string is not valid UTF-8
119    #[must_use]
120    pub fn as_str(&self) -> &str {
121        std::str::from_utf8(&self.inner).expect("RString value is not valid UTF-8")
122    }
123}
124
125impl From<&str> for RString {
126    fn from(s: &str) -> Self {
127        Self {
128            inner: s.as_bytes().to_vec().into(),
129        }
130    }
131}
132
133impl From<String> for RString {
134    fn from(s: String) -> Self {
135        Self {
136            inner: s.into_bytes().into(),
137        }
138    }
139}
140
141impl AsRef<str> for RString {
142    fn as_ref(&self) -> &str {
143        self.as_str()
144    }
145}
146
147impl Display for RString {
148    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
149        self.as_str().fmt(f)
150    }
151}
152
153/// An ABI-stable [`Option`][std::option::Option].
154#[repr(C, u8)]
155#[derive(Debug)]
156pub enum Option<T> {
157    /// [`Option::Some`][std::option::Option::Some] variant.
158    Some(T),
159    /// [`Option::None`][std::option::Option::None] variant.
160    None,
161}
162
163impl<T> From<std::option::Option<T>> for Option<T> {
164    fn from(opt: std::option::Option<T>) -> Self {
165        match opt {
166            Some(val) => Self::Some(val),
167            None => Self::None,
168        }
169    }
170}
171
172impl<T> PartialEq for Option<T>
173where
174    T: PartialEq,
175{
176    fn eq(&self, other: &Self) -> bool {
177        match (self, other) {
178            (Self::Some(a), Self::Some(b)) => a == b,
179            (Self::None, Self::None) => true,
180            _ => false,
181        }
182    }
183}
ext_php_rs/describe/abi.rs

ext_php_rs/describe/
abi.rs
