use crate::actually_private::Private; use alloc::borrow::Cow; use alloc::string::String; use core::cmp::Ordering; use core::fmt::{self, Debug, Display}; use core::hash::{Hash, Hasher}; use core::marker::{PhantomData, PhantomPinned}; use core::mem::MaybeUninit; use core::pin::Pin; use core::slice; use core::str::{self, Utf8Error}; extern "C" { #[link_name = "cxxbridge1$cxx_string$init"] fn string_init(this: &mut MaybeUninit, ptr: *const u8, len: usize); #[link_name = "cxxbridge1$cxx_string$destroy"] fn string_destroy(this: &mut MaybeUninit); #[link_name = "cxxbridge1$cxx_string$data"] fn string_data(this: &CxxString) -> *const u8; #[link_name = "cxxbridge1$cxx_string$length"] fn string_length(this: &CxxString) -> usize; #[link_name = "cxxbridge1$cxx_string$push"] fn string_push(this: Pin<&mut CxxString>, ptr: *const u8, len: usize); } /// Binding to C++ `std::string`. /// /// # Invariants /// /// As an invariant of this API and the static analysis of the cxx::bridge /// macro, in Rust code we can never obtain a `CxxString` by value. C++'s string /// requires a move constructor and may hold internal pointers, which is not /// compatible with Rust's move behavior. Instead in Rust code we will only ever /// look at a CxxString through a reference or smart pointer, as in `&CxxString` /// or `UniquePtr`. #[repr(C)] pub struct CxxString { _private: [u8; 0], _pinned: PhantomData, } /// Construct a C++ std::string on the Rust stack. /// /// # Syntax /// /// In statement position: /// /// ``` /// # use cxx::let_cxx_string; /// # let expression = ""; /// let_cxx_string!(var = expression); /// ``` /// /// The `expression` may have any type that implements `AsRef<[u8]>`. Commonly /// it will be a string literal, but for example `&[u8]` and `String` would work /// as well. /// /// The macro expands to something resembling `let $var: Pin<&mut CxxString> = /// /*???*/;`. The resulting [`Pin`] can be deref'd to `&CxxString` as needed. /// /// # Example /// /// ``` /// use cxx::{let_cxx_string, CxxString}; /// /// fn f(s: &CxxString) {/* ... */} /// /// fn main() { /// let_cxx_string!(s = "example"); /// f(&s); /// } /// ``` #[macro_export] macro_rules! let_cxx_string { ($var:ident = $value:expr $(,)?) => { let mut cxx_stack_string = $crate::private::StackString::new(); #[allow(unused_mut, unused_unsafe)] let mut $var = match $value { let_cxx_string => unsafe { cxx_stack_string.init(let_cxx_string) }, }; }; } impl CxxString { /// `CxxString` is not constructible via `new`. Instead, use the /// [`let_cxx_string!`] macro. pub fn new() -> Self { unreachable!() } /// Returns the length of the string in bytes. /// /// Matches the behavior of C++ [std::string::size][size]. /// /// [size]: https://en.cppreference.com/w/cpp/string/basic_string/size pub fn len(&self) -> usize { unsafe { string_length(self) } } /// Returns true if `self` has a length of zero bytes. /// /// Matches the behavior of C++ [std::string::empty][empty]. /// /// [empty]: https://en.cppreference.com/w/cpp/string/basic_string/empty pub fn is_empty(&self) -> bool { self.len() == 0 } /// Returns a byte slice of this string's contents. pub fn as_bytes(&self) -> &[u8] { let data = self.as_ptr(); let len = self.len(); unsafe { slice::from_raw_parts(data, len) } } /// Produces a pointer to the first character of the string. /// /// Matches the behavior of C++ [std::string::data][data]. /// /// Note that the return type may look like `const char *` but is not a /// `const char *` in the typical C sense, as C++ strings may contain /// internal null bytes. As such, the returned pointer only makes sense as a /// string in combination with the length returned by [`len()`][len]. /// /// [data]: https://en.cppreference.com/w/cpp/string/basic_string/data /// [len]: #method.len pub fn as_ptr(&self) -> *const u8 { unsafe { string_data(self) } } /// Validates that the C++ string contains UTF-8 data and produces a view of /// it as a Rust &str, otherwise an error. pub fn to_str(&self) -> Result<&str, Utf8Error> { str::from_utf8(self.as_bytes()) } /// If the contents of the C++ string are valid UTF-8, this function returns /// a view as a Cow::Borrowed &str. Otherwise replaces any invalid UTF-8 /// sequences with the U+FFFD [replacement character] and returns a /// Cow::Owned String. /// /// [replacement character]: https://doc.rust-lang.org/std/char/constant.REPLACEMENT_CHARACTER.html pub fn to_string_lossy(&self) -> Cow { String::from_utf8_lossy(self.as_bytes()) } /// Appends a given string slice onto the end of this C++ string. pub fn push_str(self: Pin<&mut Self>, s: &str) { self.push_bytes(s.as_bytes()); } /// Appends arbitrary bytes onto the end of this C++ string. pub fn push_bytes(self: Pin<&mut Self>, bytes: &[u8]) { unsafe { string_push(self, bytes.as_ptr(), bytes.len()) } } } impl Display for CxxString { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { Display::fmt(self.to_string_lossy().as_ref(), f) } } impl Debug for CxxString { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { Debug::fmt(self.to_string_lossy().as_ref(), f) } } impl PartialEq for CxxString { fn eq(&self, other: &Self) -> bool { self.as_bytes() == other.as_bytes() } } impl PartialEq for str { fn eq(&self, other: &CxxString) -> bool { self.as_bytes() == other.as_bytes() } } impl PartialEq for CxxString { fn eq(&self, other: &str) -> bool { self.as_bytes() == other.as_bytes() } } impl Eq for CxxString {} impl PartialOrd for CxxString { fn partial_cmp(&self, other: &Self) -> Option { self.as_bytes().partial_cmp(other.as_bytes()) } } impl Ord for CxxString { fn cmp(&self, other: &Self) -> Ordering { self.as_bytes().cmp(other.as_bytes()) } } impl Hash for CxxString { fn hash(&self, state: &mut H) { self.as_bytes().hash(state); } } #[doc(hidden)] #[repr(C)] pub struct StackString { // Static assertions in cxx.cc validate that this is large enough and // aligned enough. space: MaybeUninit<[usize; 8]>, } impl StackString { pub fn new() -> Self { StackString { space: MaybeUninit::uninit(), } } pub unsafe fn init(&mut self, value: impl AsRef<[u8]>) -> Pin<&mut CxxString> { let value = value.as_ref(); let this = &mut *self.space.as_mut_ptr().cast::>(); string_init(this, value.as_ptr(), value.len()); Pin::new_unchecked(&mut *this.as_mut_ptr()) } } impl Drop for StackString { fn drop(&mut self) { unsafe { let this = &mut *self.space.as_mut_ptr().cast::>(); string_destroy(this); } } }