1 use crate::actually_private::Private; 2 use alloc::borrow::Cow; 3 use alloc::string::String; 4 use core::cmp::Ordering; 5 use core::fmt::{self, Debug, Display}; 6 use core::hash::{Hash, Hasher}; 7 use core::marker::{PhantomData, PhantomPinned}; 8 use core::mem::MaybeUninit; 9 use core::pin::Pin; 10 use core::slice; 11 use core::str::{self, Utf8Error}; 12 13 extern "C" { 14 #[link_name = "cxxbridge1$cxx_string$init"] string_init(this: &mut MaybeUninit<CxxString>, ptr: *const u8, len: usize)15 fn string_init(this: &mut MaybeUninit<CxxString>, ptr: *const u8, len: usize); 16 #[link_name = "cxxbridge1$cxx_string$destroy"] string_destroy(this: &mut MaybeUninit<CxxString>)17 fn string_destroy(this: &mut MaybeUninit<CxxString>); 18 #[link_name = "cxxbridge1$cxx_string$data"] string_data(this: &CxxString) -> *const u819 fn string_data(this: &CxxString) -> *const u8; 20 #[link_name = "cxxbridge1$cxx_string$length"] string_length(this: &CxxString) -> usize21 fn string_length(this: &CxxString) -> usize; 22 #[link_name = "cxxbridge1$cxx_string$push"] string_push(this: Pin<&mut CxxString>, ptr: *const u8, len: usize)23 fn string_push(this: Pin<&mut CxxString>, ptr: *const u8, len: usize); 24 } 25 26 /// Binding to C++ `std::string`. 27 /// 28 /// # Invariants 29 /// 30 /// As an invariant of this API and the static analysis of the cxx::bridge 31 /// macro, in Rust code we can never obtain a `CxxString` by value. C++'s string 32 /// requires a move constructor and may hold internal pointers, which is not 33 /// compatible with Rust's move behavior. Instead in Rust code we will only ever 34 /// look at a CxxString through a reference or smart pointer, as in `&CxxString` 35 /// or `UniquePtr<CxxString>`. 36 #[repr(C)] 37 pub struct CxxString { 38 _private: [u8; 0], 39 _pinned: PhantomData<PhantomPinned>, 40 } 41 42 /// Construct a C++ std::string on the Rust stack. 43 /// 44 /// # Syntax 45 /// 46 /// In statement position: 47 /// 48 /// ``` 49 /// # use cxx::let_cxx_string; 50 /// # let expression = ""; 51 /// let_cxx_string!(var = expression); 52 /// ``` 53 /// 54 /// The `expression` may have any type that implements `AsRef<[u8]>`. Commonly 55 /// it will be a string literal, but for example `&[u8]` and `String` would work 56 /// as well. 57 /// 58 /// The macro expands to something resembling `let $var: Pin<&mut CxxString> = 59 /// /*???*/;`. The resulting [`Pin`] can be deref'd to `&CxxString` as needed. 60 /// 61 /// # Example 62 /// 63 /// ``` 64 /// use cxx::{let_cxx_string, CxxString}; 65 /// 66 /// fn f(s: &CxxString) {/* ... */} 67 /// 68 /// fn main() { 69 /// let_cxx_string!(s = "example"); 70 /// f(&s); 71 /// } 72 /// ``` 73 #[macro_export] 74 macro_rules! let_cxx_string { 75 ($var:ident = $value:expr $(,)?) => { 76 let mut cxx_stack_string = $crate::private::StackString::new(); 77 #[allow(unused_mut, unused_unsafe)] 78 let mut $var = match $value { 79 let_cxx_string => unsafe { cxx_stack_string.init(let_cxx_string) }, 80 }; 81 }; 82 } 83 84 impl CxxString { 85 /// `CxxString` is not constructible via `new`. Instead, use the 86 /// [`let_cxx_string!`] macro. new<T: Private>() -> Self87 pub fn new<T: Private>() -> Self { 88 unreachable!() 89 } 90 91 /// Returns the length of the string in bytes. 92 /// 93 /// Matches the behavior of C++ [std::string::size][size]. 94 /// 95 /// [size]: https://en.cppreference.com/w/cpp/string/basic_string/size len(&self) -> usize96 pub fn len(&self) -> usize { 97 unsafe { string_length(self) } 98 } 99 100 /// Returns true if `self` has a length of zero bytes. 101 /// 102 /// Matches the behavior of C++ [std::string::empty][empty]. 103 /// 104 /// [empty]: https://en.cppreference.com/w/cpp/string/basic_string/empty is_empty(&self) -> bool105 pub fn is_empty(&self) -> bool { 106 self.len() == 0 107 } 108 109 /// Returns a byte slice of this string's contents. as_bytes(&self) -> &[u8]110 pub fn as_bytes(&self) -> &[u8] { 111 let data = self.as_ptr(); 112 let len = self.len(); 113 unsafe { slice::from_raw_parts(data, len) } 114 } 115 116 /// Produces a pointer to the first character of the string. 117 /// 118 /// Matches the behavior of C++ [std::string::data][data]. 119 /// 120 /// Note that the return type may look like `const char *` but is not a 121 /// `const char *` in the typical C sense, as C++ strings may contain 122 /// internal null bytes. As such, the returned pointer only makes sense as a 123 /// string in combination with the length returned by [`len()`][len]. 124 /// 125 /// [data]: https://en.cppreference.com/w/cpp/string/basic_string/data 126 /// [len]: #method.len as_ptr(&self) -> *const u8127 pub fn as_ptr(&self) -> *const u8 { 128 unsafe { string_data(self) } 129 } 130 131 /// Validates that the C++ string contains UTF-8 data and produces a view of 132 /// it as a Rust &str, otherwise an error. to_str(&self) -> Result<&str, Utf8Error>133 pub fn to_str(&self) -> Result<&str, Utf8Error> { 134 str::from_utf8(self.as_bytes()) 135 } 136 137 /// If the contents of the C++ string are valid UTF-8, this function returns 138 /// a view as a Cow::Borrowed &str. Otherwise replaces any invalid UTF-8 139 /// sequences with the U+FFFD [replacement character] and returns a 140 /// Cow::Owned String. 141 /// 142 /// [replacement character]: https://doc.rust-lang.org/std/char/constant.REPLACEMENT_CHARACTER.html to_string_lossy(&self) -> Cow<str>143 pub fn to_string_lossy(&self) -> Cow<str> { 144 String::from_utf8_lossy(self.as_bytes()) 145 } 146 147 /// Appends a given string slice onto the end of this C++ string. push_str(self: Pin<&mut Self>, s: &str)148 pub fn push_str(self: Pin<&mut Self>, s: &str) { 149 self.push_bytes(s.as_bytes()); 150 } 151 152 /// Appends arbitrary bytes onto the end of this C++ string. push_bytes(self: Pin<&mut Self>, bytes: &[u8])153 pub fn push_bytes(self: Pin<&mut Self>, bytes: &[u8]) { 154 unsafe { string_push(self, bytes.as_ptr(), bytes.len()) } 155 } 156 } 157 158 impl Display for CxxString { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result159 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 160 Display::fmt(self.to_string_lossy().as_ref(), f) 161 } 162 } 163 164 impl Debug for CxxString { fmt(&self, f: &mut fmt::Formatter) -> fmt::Result165 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 166 Debug::fmt(self.to_string_lossy().as_ref(), f) 167 } 168 } 169 170 impl PartialEq for CxxString { eq(&self, other: &Self) -> bool171 fn eq(&self, other: &Self) -> bool { 172 self.as_bytes() == other.as_bytes() 173 } 174 } 175 176 impl PartialEq<CxxString> for str { eq(&self, other: &CxxString) -> bool177 fn eq(&self, other: &CxxString) -> bool { 178 self.as_bytes() == other.as_bytes() 179 } 180 } 181 182 impl PartialEq<str> for CxxString { eq(&self, other: &str) -> bool183 fn eq(&self, other: &str) -> bool { 184 self.as_bytes() == other.as_bytes() 185 } 186 } 187 188 impl Eq for CxxString {} 189 190 impl PartialOrd for CxxString { partial_cmp(&self, other: &Self) -> Option<Ordering>191 fn partial_cmp(&self, other: &Self) -> Option<Ordering> { 192 self.as_bytes().partial_cmp(other.as_bytes()) 193 } 194 } 195 196 impl Ord for CxxString { cmp(&self, other: &Self) -> Ordering197 fn cmp(&self, other: &Self) -> Ordering { 198 self.as_bytes().cmp(other.as_bytes()) 199 } 200 } 201 202 impl Hash for CxxString { hash<H: Hasher>(&self, state: &mut H)203 fn hash<H: Hasher>(&self, state: &mut H) { 204 self.as_bytes().hash(state); 205 } 206 } 207 208 #[doc(hidden)] 209 #[repr(C)] 210 pub struct StackString { 211 // Static assertions in cxx.cc validate that this is large enough and 212 // aligned enough. 213 space: MaybeUninit<[usize; 8]>, 214 } 215 216 impl StackString { new() -> Self217 pub fn new() -> Self { 218 StackString { 219 space: MaybeUninit::uninit(), 220 } 221 } 222 init(&mut self, value: impl AsRef<[u8]>) -> Pin<&mut CxxString>223 pub unsafe fn init(&mut self, value: impl AsRef<[u8]>) -> Pin<&mut CxxString> { 224 let value = value.as_ref(); 225 let this = &mut *self.space.as_mut_ptr().cast::<MaybeUninit<CxxString>>(); 226 string_init(this, value.as_ptr(), value.len()); 227 Pin::new_unchecked(&mut *this.as_mut_ptr()) 228 } 229 } 230 231 impl Drop for StackString { drop(&mut self)232 fn drop(&mut self) { 233 unsafe { 234 let this = &mut *self.space.as_mut_ptr().cast::<MaybeUninit<CxxString>>(); 235 string_destroy(this); 236 } 237 } 238 } 239