use crate::actually_private::Private;
use alloc::borrow::Cow;
use alloc::string::String;
use core::fmt::{self, Debug, Display};
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<CxxString>, ptr: *const u8, len: usize);
#[link_name = "cxxbridge1$cxx_string$destroy"]
fn string_destroy(this: &mut MaybeUninit<CxxString>);
#[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<CxxString>`.
#[repr(C)]
pub struct CxxString {
_private: [u8; 0],
_pinned: PhantomData<PhantomPinned>,
}
/// 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 $var = $crate::private::StackString::new();
#[allow(unused_mut, unused_unsafe)]
let mut $var = unsafe { $var.init($value) };
};
}
impl CxxString {
/// `CxxString` is not constructible via `new`. Instead, use the
/// [`let_cxx_string!`] macro.
pub fn new<T: Private>() -> 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<str> {
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: &CxxString) -> bool {
self.as_bytes() == other.as_bytes()
}
}
impl PartialEq<CxxString> for str {
fn eq(&self, other: &CxxString) -> bool {
self.as_bytes() == other.as_bytes()
}
}
impl PartialEq<str> for CxxString {
fn eq(&self, other: &str) -> bool {
self.as_bytes() == other.as_bytes()
}
}
#[doc(hidden)]
#[repr(C)]
pub struct StackString {
// Static assertions in cxx.cc validate that this is large enough and
// aligned enough.
space: MaybeUninit<[*const (); 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::<MaybeUninit<CxxString>>();
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::<MaybeUninit<CxxString>>();
string_destroy(this);
}
}
}