support/cc_std/string.rs - crubit - Git at Google

 // Part of the Crubit project, under the Apache License v2.0 with LLVM
 // Exceptions. See /LICENSE for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

 extern crate alloc;

 use crate::crubit_cc_std_internal::conversion_function_helpers;
 use alloc::string::String;
 use alloc::vec::Vec;
 use bridge_rust::{CrubitAbi, Decoder, Encoder};
 use core::clone::Clone;
 use core::cmp::Eq;
 use core::cmp::PartialEq;
 use core::ffi::c_void;
 use core::mem::{ManuallyDrop, MaybeUninit};
 use core::ops::Deref;
 use core::ptr::NonNull;

 /// An owned C++ string. The pointer is guaranteed to be a non-null C++
 /// allocated pointer to std::string.
 ///
 /// We make sure that conversion between `string` and `std::string` is O(1), but
 /// conversion between `string` and other types like `&str` or `String` can be
 /// O(n).
 // TODO: Make it mutable?.
 // TODO: add a depedency on `crubit_annotate` to use that directly rather than doc attributes.
 #[doc = "CRUBIT_ANNOTATE: cpp_type=std::string"]
 #[doc = "CRUBIT_ANNOTATE: include_path=<string>"]
 #[doc = "CRUBIT_ANNOTATE: cpp_to_rust_converter=cpp_string_to_rust_string"]
 #[doc = "CRUBIT_ANNOTATE: rust_to_cpp_converter=rust_string_to_cpp_string"]
 #[allow(non_snake_case)]
 #[repr(C)]
 pub struct string {
     owned_cpp_string: NonNull<c_void>,
 }

 impl string {
     pub fn as_slice(&self) -> &[u8] {
         self.as_ref()
     }

     /// Returns a `*const c_void` pointing to the underlying C++
     /// `std::string` object.
     ///
     /// The caller must ensure that the `string` outlives the pointer.
     ///
     /// This method guarantees that for the purpose of the aliasing
     /// model, this method does not materialize a reference to the
     /// underlying data the string owns, and thus the returned
     /// pointer will remain valid when mixed with other calls to
     /// `as_void_ptr` and `as_mut_void_ptr`.
     pub fn as_void_ptr(&self) -> *const c_void {
         self.owned_cpp_string.as_ptr() as *const _
     }

     /// Returns a `*mut c_void` pointing to the underlying C++
     /// `std::string` object.
     ///
     /// The caller must ensure that the `string` outlives the pointer.
     ///
     /// This method guarantees that for the purpose of the aliasing
     /// model, this method does not materialize a reference to the
     /// underlying data the string owns, and thus the returned
     /// pointer will remain valid when mixed with other calls to
     /// `as_void_ptr` and `as_mut_void_ptr`.
     ///
     /// However, note that writing to the pointer will invalidate references to
     /// the underlying data. For example, the behavior is undefined if the
     /// underlying string is mutated through this pointer during the lifetime
     /// of a slice as returned by `as_slice`.
     pub fn as_mut_void_ptr(&mut self) -> *mut c_void {
         self.owned_cpp_string.as_ptr()
     }

     /// Returns an object that implements `Display` for safely printing paths that may contain
     /// non-Unicode data. This may perform lossy conversion, depending on the underlying data.
     pub fn display(&self) -> Display<'_> {
         Display(self.as_slice())
     }
 }

 impl PartialEq for string {
     fn eq(&self, other: &Self) -> bool {
         unsafe {
             // SAFETY: `owned_cpp_string` is guaranteed to be a non-null C++ allocated
             // pointer to std::string.
             conversion_function_helpers::StringEqual(
                 self.owned_cpp_string.as_ptr(),
                 other.owned_cpp_string.as_ptr(),
             )
         }
     }
 }

 impl Eq for string {}

 impl Default for string {
     fn default() -> Self {
         "".into()
     }
 }

 impl Clone for string {
     fn clone(&self) -> Self {
         // SAFETY: `owned_cpp_string` is guaranteed to be a non-null C++ allocated
         // pointer to std::string.
         let raw_string = unsafe {
             conversion_function_helpers::StringCopyOwnedPtr(self.owned_cpp_string.as_ptr())
         };
         if let Some(ptr) = NonNull::new(raw_string) {
             Self { owned_cpp_string: ptr }
         } else {
             panic!("Failed to copy string");
         }
     }
 }

 impl Drop for string {
     fn drop(&mut self) {
         unsafe {
             // SAFETY: `owned_cpp_string` is guaranteed to be a non-null C++ allocated
             // pointer to std::string.
             conversion_function_helpers::StringDelete(self.owned_cpp_string.as_ptr());
         }
     }
 }

 impl From<String> for string {
     fn from(s: String) -> Self {
         s.as_bytes().into()
     }
 }

 impl From<&String> for string {
     fn from(s: &String) -> Self {
         s.as_bytes().into()
     }
 }

 impl From<&Vec<u8>> for string {
     fn from(s: &Vec<u8>) -> Self {
         s.as_slice().into()
     }
 }

 impl From<&str> for string {
     fn from(s: &str) -> Self {
         s.as_bytes().into()
     }
 }

 impl From<&[u8]> for string {
     fn from(s: &[u8]) -> Self {
         // SAFETY: Rust slice returns a valid pointer to a buffer of bytes.
         let raw_string = unsafe {
             conversion_function_helpers::StringCreateFromBuffer(s.as_ptr() as _, s.len())
         };
         if let Some(ptr) = NonNull::new(raw_string) {
             Self { owned_cpp_string: ptr }
         } else {
             panic!("Failed to create string");
         }
     }
 }

 impl Deref for string {
     type Target = [u8];
     fn deref(&self) -> &Self::Target {
         let ptr = self.owned_cpp_string.as_ptr();
         // SAFETY:
         //
         // * `owned_cpp_string` is guaranteed to be a non-null C++ allocated pointer to
         //   std::string so `ptr` is non-null.
         // * `StringGetData` returns the pointer of the C++ `std::string::data()`, which
         //   is guaranteed to be non-null and point to a continuous memory region. Every
         //   byte in [ptr, ptr + len)) is intialized. (See https://en.cppreference.com/w/cpp/string/basic_string/data)
         // * The data is guaranteed to be not mutated because we don't ever mutate
         //   data() except when accessed via &mut self, which is blocked by Rust borrow
         //   checker.
         // * `len` is guaranteed to be less than `isize::MAX` because C++
         //   implementations guarantee in practice that the object won't go past the end
         //   of the address space.
         unsafe {
             let len = conversion_function_helpers::StringGetSize(ptr);
             core::slice::from_raw_parts(conversion_function_helpers::StringGetData(ptr) as _, len)
         }
     }
 }

 impl core::convert::AsRef<[u8]> for string {
     fn as_ref(&self) -> &[u8] {
         &*self
     }
 }

 impl core::fmt::Debug for string {
     // TODO(b/351976622): Make a pretty Debug like std::string(b"\xffhello\xde") or
     // similar.
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         write!(f, "cc_std::string({:?})", self.as_slice())
     }
 }

 impl core::fmt::Display for string {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         self.display().fmt(f)
     }
 }

 // Allow converting a cc_std::std::string reference to a "real" C++ string pointer.

 type StringSymbol = forward_declare::symbol!(
     "std :: basic_string < char , std :: char_traits < char >, std :: allocator < char >>"
 );

 impl<'a, Crate> forward_declare::CppCast<*const forward_declare::Incomplete<StringSymbol, Crate>>
     for &'a string
 {
     fn cpp_cast(self) -> *const forward_declare::Incomplete<StringSymbol, Crate> {
         self.owned_cpp_string.as_ptr() as *const _ as *const _
     }
 }

 impl<'a, Crate> forward_declare::CppCast<*mut forward_declare::Incomplete<StringSymbol, Crate>>
     for &'a mut string
 {
     fn cpp_cast(self) -> *mut forward_declare::Incomplete<StringSymbol, Crate> {
         self.owned_cpp_string.as_ptr() as *mut _
     }
 }

 /// Helper struct for safely printing C++ string data with `format!` and `{}`.
 ///
 /// A string from C++ might contain non-Unicode data. This struct implements the Display trait in a
 /// way that mitigates that. It is created by the display method on `string`. This may perform lossy
 /// conversion, depending on the underlying data.
 pub struct Display<'a>(&'a [u8]);

 impl<'a> core::fmt::Display for Display<'a> {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         use core::fmt::Write;
         for chunk in self.0.utf8_chunks() {
             f.write_str(chunk.valid())?;
             if !chunk.invalid().is_empty() {
                 f.write_char(core::char::REPLACEMENT_CHARACTER)?;
             }
         }
         Ok(())
     }
 }

 /// The Crubit ABI for C++ `std::string`. It is specified as one pointer.
 ///
 /// This pointer should point to a heap allocated `std::string` object, where the pointer is the
 /// owner of the allocation. Alternatively, the pointer can be null if and only if the allocation
 /// failed, in which case it's okay to panic.
 pub struct BoxedCppStringAbi;

 unsafe impl CrubitAbi for BoxedCppStringAbi {
     type Value = string;

     const SIZE: usize = core::mem::size_of::<*mut c_void>();

     fn encode(value: Self::Value, encoder: &mut Encoder) {
         encoder.encode_transmute(ManuallyDrop::new(value).as_mut_void_ptr());
     }

     unsafe fn decode(decoder: &mut Decoder) -> Self::Value {
         // SAFETY: the caller guarantees that the buffer contains an allocated or null pointer to a
         // C++ `std::string` object.
         let ptr: *mut c_void = unsafe { decoder.decode_transmute() };

         Self::Value {
             owned_cpp_string: NonNull::new(ptr).expect("Boxing a std::string shouldn't fail"),
         }
     }
 }

 // Void pointer converters are needed for cc_bindings_from_rs.

 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn rust_string_to_cpp_string(input: *const c_void, output: *mut c_void) {
     // SAFETY:
     // * `input` is a valid `string`.
     // * `input.owned_cpp_string` is guaranteed to be a non-null C++ allocated
     //   pointer to std::string.
     // * `output` is a valid C++ `std::string`.
     unsafe {
         let input = &*(input as *const string);
         conversion_function_helpers::StringCreateInPlace(output, input.owned_cpp_string.as_ptr());
     }
 }

 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn cpp_string_to_rust_string(input: *mut c_void, output: *mut c_void) {
     // SAFETY: `input` is a valid `std::string` so it can be safely moved.
     let owned_cpp_string = unsafe { conversion_function_helpers::StringMoveOwnedPtr(input) };
     if let Some(ptr) = NonNull::new(owned_cpp_string) {
         let output = &mut *(output as *mut MaybeUninit<string>);
         output.as_mut_ptr().write(string { owned_cpp_string: ptr });
     } else {
         panic!("Failed to create owned string");
     }
 }
	// Part of the Crubit project, under the Apache License v2.0 with LLVM
	// Exceptions. See /LICENSE for license information.
	// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

	extern crate alloc;

	use crate::crubit_cc_std_internal::conversion_function_helpers;
	use alloc::string::String;
	use alloc::vec::Vec;
	use bridge_rust::{CrubitAbi, Decoder, Encoder};
	use core::clone::Clone;
	use core::cmp::Eq;
	use core::cmp::PartialEq;
	use core::ffi::c_void;
	use core::mem::{ManuallyDrop, MaybeUninit};
	use core::ops::Deref;
	use core::ptr::NonNull;

	/// An owned C++ string. The pointer is guaranteed to be a non-null C++
	/// allocated pointer to std::string.
	///
	/// We make sure that conversion between `string` and `std::string` is O(1), but
	/// conversion between `string` and other types like `&str` or `String` can be
	/// O(n).
	// TODO: Make it mutable?.
	// TODO: add a depedency on `crubit_annotate` to use that directly rather than doc attributes.
	#[doc = "CRUBIT_ANNOTATE: cpp_type=std::string"]
	#[doc = "CRUBIT_ANNOTATE: include_path=<string>"]
	#[doc = "CRUBIT_ANNOTATE: cpp_to_rust_converter=cpp_string_to_rust_string"]
	#[doc = "CRUBIT_ANNOTATE: rust_to_cpp_converter=rust_string_to_cpp_string"]
	#[allow(non_snake_case)]
	#[repr(C)]
	pub struct string {
	owned_cpp_string: NonNull<c_void>,
	}

	impl string {
	pub fn as_slice(&self) -> &[u8] {
	self.as_ref()
	}

	/// Returns a `*const c_void` pointing to the underlying C++
	/// `std::string` object.
	///
	/// The caller must ensure that the `string` outlives the pointer.
	///
	/// This method guarantees that for the purpose of the aliasing
	/// model, this method does not materialize a reference to the
	/// underlying data the string owns, and thus the returned
	/// pointer will remain valid when mixed with other calls to
	/// `as_void_ptr` and `as_mut_void_ptr`.
	pub fn as_void_ptr(&self) -> *const c_void {
	self.owned_cpp_string.as_ptr() as *const _
	}

	/// Returns a `*mut c_void` pointing to the underlying C++
	/// `std::string` object.
	///
	/// The caller must ensure that the `string` outlives the pointer.
	///
	/// This method guarantees that for the purpose of the aliasing
	/// model, this method does not materialize a reference to the
	/// underlying data the string owns, and thus the returned
	/// pointer will remain valid when mixed with other calls to
	/// `as_void_ptr` and `as_mut_void_ptr`.
	///
	/// However, note that writing to the pointer will invalidate references to
	/// the underlying data. For example, the behavior is undefined if the
	/// underlying string is mutated through this pointer during the lifetime
	/// of a slice as returned by `as_slice`.
	pub fn as_mut_void_ptr(&mut self) -> *mut c_void {
	self.owned_cpp_string.as_ptr()
	}

	/// Returns an object that implements `Display` for safely printing paths that may contain
	/// non-Unicode data. This may perform lossy conversion, depending on the underlying data.
	pub fn display(&self) -> Display<'_> {
	Display(self.as_slice())
	}
	}

	impl PartialEq for string {
	fn eq(&self, other: &Self) -> bool {
	unsafe {
	// SAFETY: `owned_cpp_string` is guaranteed to be a non-null C++ allocated
	// pointer to std::string.
	conversion_function_helpers::StringEqual(
	self.owned_cpp_string.as_ptr(),
	other.owned_cpp_string.as_ptr(),
	)
	}
	}
	}

	impl Eq for string {}

	impl Default for string {
	fn default() -> Self {
	"".into()
	}
	}

	impl Clone for string {
	fn clone(&self) -> Self {
	// SAFETY: `owned_cpp_string` is guaranteed to be a non-null C++ allocated
	// pointer to std::string.
	let raw_string = unsafe {
	conversion_function_helpers::StringCopyOwnedPtr(self.owned_cpp_string.as_ptr())
	};
	if let Some(ptr) = NonNull::new(raw_string) {
	Self { owned_cpp_string: ptr }
	} else {
	panic!("Failed to copy string");
	}
	}
	}

	impl Drop for string {
	fn drop(&mut self) {
	unsafe {
	// SAFETY: `owned_cpp_string` is guaranteed to be a non-null C++ allocated
	// pointer to std::string.
	conversion_function_helpers::StringDelete(self.owned_cpp_string.as_ptr());
	}
	}
	}

	impl From<String> for string {
	fn from(s: String) -> Self {
	s.as_bytes().into()
	}
	}

	impl From<&String> for string {
	fn from(s: &String) -> Self {
	s.as_bytes().into()
	}
	}

	impl From<&Vec<u8>> for string {
	fn from(s: &Vec<u8>) -> Self {
	s.as_slice().into()
	}
	}

	impl From<&str> for string {
	fn from(s: &str) -> Self {
	s.as_bytes().into()
	}
	}

	impl From<&[u8]> for string {
	fn from(s: &[u8]) -> Self {
	// SAFETY: Rust slice returns a valid pointer to a buffer of bytes.
	let raw_string = unsafe {
	conversion_function_helpers::StringCreateFromBuffer(s.as_ptr() as _, s.len())
	};
	if let Some(ptr) = NonNull::new(raw_string) {
	Self { owned_cpp_string: ptr }
	} else {
	panic!("Failed to create string");
	}
	}
	}

	impl Deref for string {
	type Target = [u8];
	fn deref(&self) -> &Self::Target {
	let ptr = self.owned_cpp_string.as_ptr();
	// SAFETY:
	//
	// * `owned_cpp_string` is guaranteed to be a non-null C++ allocated pointer to
	// std::string so `ptr` is non-null.
	// * `StringGetData` returns the pointer of the C++ `std::string::data()`, which
	// is guaranteed to be non-null and point to a continuous memory region. Every
	// byte in [ptr, ptr + len)) is intialized. (See https://en.cppreference.com/w/cpp/string/basic_string/data)
	// * The data is guaranteed to be not mutated because we don't ever mutate
	// data() except when accessed via &mut self, which is blocked by Rust borrow
	// checker.
	// * `len` is guaranteed to be less than `isize::MAX` because C++
	// implementations guarantee in practice that the object won't go past the end
	// of the address space.
	unsafe {
	let len = conversion_function_helpers::StringGetSize(ptr);
	core::slice::from_raw_parts(conversion_function_helpers::StringGetData(ptr) as _, len)
	}
	}
	}

	impl core::convert::AsRef<[u8]> for string {
	fn as_ref(&self) -> &[u8] {
	&*self
	}
	}

	impl core::fmt::Debug for string {
	// TODO(b/351976622): Make a pretty Debug like std::string(b"\xffhello\xde") or
	// similar.
	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
	write!(f, "cc_std::string({:?})", self.as_slice())
	}
	}

	impl core::fmt::Display for string {
	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
	self.display().fmt(f)
	}
	}

	// Allow converting a cc_std::std::string reference to a "real" C++ string pointer.

	type StringSymbol = forward_declare::symbol!(
	"std :: basic_string < char , std :: char_traits < char >, std :: allocator < char >>"
	);

	impl<'a, Crate> forward_declare::CppCast<*const forward_declare::Incomplete<StringSymbol, Crate>>
	for &'a string
	{
	fn cpp_cast(self) -> *const forward_declare::Incomplete<StringSymbol, Crate> {
	self.owned_cpp_string.as_ptr() as const _ as const _
	}
	}

	impl<'a, Crate> forward_declare::CppCast<*mut forward_declare::Incomplete<StringSymbol, Crate>>
	for &'a mut string
	{
	fn cpp_cast(self) -> *mut forward_declare::Incomplete<StringSymbol, Crate> {
	self.owned_cpp_string.as_ptr() as *mut _
	}
	}

	/// Helper struct for safely printing C++ string data with `format!` and `{}`.
	///
	/// A string from C++ might contain non-Unicode data. This struct implements the Display trait in a
	/// way that mitigates that. It is created by the display method on `string`. This may perform lossy
	/// conversion, depending on the underlying data.
	pub struct Display<'a>(&'a [u8]);

	impl<'a> core::fmt::Display for Display<'a> {
	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
	use core::fmt::Write;
	for chunk in self.0.utf8_chunks() {
	f.write_str(chunk.valid())?;
	if !chunk.invalid().is_empty() {
	f.write_char(core::char::REPLACEMENT_CHARACTER)?;
	}
	}
	Ok(())
	}
	}

	/// The Crubit ABI for C++ `std::string`. It is specified as one pointer.
	///
	/// This pointer should point to a heap allocated `std::string` object, where the pointer is the
	/// owner of the allocation. Alternatively, the pointer can be null if and only if the allocation
	/// failed, in which case it's okay to panic.
	pub struct BoxedCppStringAbi;

	unsafe impl CrubitAbi for BoxedCppStringAbi {
	type Value = string;

	const SIZE: usize = core::mem::size_of::<*mut c_void>();

	fn encode(value: Self::Value, encoder: &mut Encoder) {
	encoder.encode_transmute(ManuallyDrop::new(value).as_mut_void_ptr());
	}

	unsafe fn decode(decoder: &mut Decoder) -> Self::Value {
	// SAFETY: the caller guarantees that the buffer contains an allocated or null pointer to a
	// C++ `std::string` object.
	let ptr: *mut c_void = unsafe { decoder.decode_transmute() };

	Self::Value {
	owned_cpp_string: NonNull::new(ptr).expect("Boxing a std::string shouldn't fail"),
	}
	}
	}

	// Void pointer converters are needed for cc_bindings_from_rs.

	#[unsafe(no_mangle)]
	pub unsafe extern "C" fn rust_string_to_cpp_string(input: const c_void, output: mut c_void) {
	// SAFETY:
	// * `input` is a valid `string`.
	// * `input.owned_cpp_string` is guaranteed to be a non-null C++ allocated
	// pointer to std::string.
	// * `output` is a valid C++ `std::string`.
	unsafe {
	let input = &(input as const string);
	conversion_function_helpers::StringCreateInPlace(output, input.owned_cpp_string.as_ptr());
	}
	}

	#[unsafe(no_mangle)]
	pub unsafe extern "C" fn cpp_string_to_rust_string(input: mut c_void, output: mut c_void) {
	// SAFETY: `input` is a valid `std::string` so it can be safely moved.
	let owned_cpp_string = unsafe { conversion_function_helpers::StringMoveOwnedPtr(input) };
	if let Some(ptr) = NonNull::new(owned_cpp_string) {
	let output = &mut (output as mut MaybeUninit<string>);
	output.as_mut_ptr().write(string { owned_cpp_string: ptr });
	} else {
	panic!("Failed to create owned string");
	}
	}