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    #[inline]
120    #[must_use]
121    pub fn as_str(&self) -> &str {
122        std::str::from_utf8(&self.inner).expect("RString value is not valid UTF-8")
123    }
124}
125
126impl From<&str> for RString {
127    fn from(s: &str) -> Self {
128        Self {
129            inner: s.as_bytes().to_vec().into(),
130        }
131    }
132}
133
134impl From<String> for RString {
135    fn from(s: String) -> Self {
136        Self {
137            inner: s.into_bytes().into(),
138        }
139    }
140}
141
142impl AsRef<str> for RString {
143    fn as_ref(&self) -> &str {
144        self.as_str()
145    }
146}
147
148impl Display for RString {
149    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
150        self.as_str().fmt(f)
151    }
152}
153
154/// An ABI-stable [`Option`][std::option::Option].
155#[repr(C, u8)]
156#[derive(Debug)]
157pub enum Option<T> {
158    /// [`Option::Some`][std::option::Option::Some] variant.
159    Some(T),
160    /// [`Option::None`][std::option::Option::None] variant.
161    None,
162}
163
164impl<T> From<std::option::Option<T>> for Option<T> {
165    fn from(opt: std::option::Option<T>) -> Self {
166        match opt {
167            Some(val) => Self::Some(val),
168            None => Self::None,
169        }
170    }
171}
172
173impl<T> PartialEq for Option<T>
174where
175    T: PartialEq,
176{
177    fn eq(&self, other: &Self) -> bool {
178        match (self, other) {
179            (Self::Some(a), Self::Some(b)) => a == b,
180            (Self::None, Self::None) => true,
181            _ => false,
182        }
183    }
184}
ext_php_rs/describe/abi.rs

ext_php_rs/describe/
abi.rs
