Struct CxxString

#[repr(C)]
pub struct CxxString { /* private fields */ }

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>.

Implementations

impl CxxString

pub fn new<T: Private>() -> Self

CxxString is not constructible via new. Instead, use the let_cxx_string! macro.

pub fn len(&self) -> usize

Returns the length of the string in bytes.

Matches the behavior of C++ std::string::size.

pub fn is_empty(&self) -> bool

Returns true if self has a length of zero bytes.

Matches the behavior of C++ std::string::empty.

pub fn as_bytes(&self) -> &[u8]

Returns a byte slice of this string’s contents.

pub fn as_ptr(&self) -> *const u8

Produces a pointer to the first character of the string.

Matches the behavior of C++ std::string::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().

pub fn to_str(&self) -> Result<&str, Utf8Error>

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_string_lossy(&self) -> Cow<'_, str>

Available on crate feature alloc only.

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.

pub fn clear(self: Pin<&mut Self>)

Removes all characters from the string.

Matches the behavior of C++ std::string::clear.

Note: unlike the guarantee of Rust’s std::string::String::clear, the C++ standard does not require that capacity is unchanged by this operation. In practice existing implementations do not change the capacity but all pointers, references, and iterators into the string contents are nevertheless invalidated.

pub fn reserve(self: Pin<&mut Self>, additional: usize)

Ensures that this string’s capacity is at least additional bytes larger than its length.

The capacity may be increased by more than additional bytes if it chooses, to amortize the cost of frequent reallocations.

The meaning of the argument is not the same as std::string::reserve in C++. The C++ standard library and Rust standard library both have a reserve method on strings, but in C++ code the argument always refers to total capacity, whereas in Rust code it always refers to additional capacity. This API on CxxString follows the Rust convention, the same way that for the length accessor we use the Rust conventional len() naming and not C++ size() or length().

Panics

Panics if the new capacity overflows usize.

pub fn push_str(self: Pin<&mut Self>, s: &str)

Appends a given string slice onto the end of this C++ string.

pub fn push_bytes(self: Pin<&mut Self>, bytes: &[u8])

Appends arbitrary bytes onto the end of this C++ string.

Trait Implementations

impl Debug for CxxString

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for CxxString

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl ExternType for CxxString

type Kind = Opaque

Either cxx::kind::Opaque or cxx::kind::Trivial.

type Id

A type-level representation of the type’s C++ namespace and type name.

impl Hash for CxxString

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for CxxString

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq<CxxString> for str

fn eq(&self, other: &CxxString) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<str> for CxxString

fn eq(&self, other: &str) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for CxxString

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for CxxString

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Write for Pin<&mut CxxString>

fn write_str(&mut self, s: &str) -> Result

Writes a string slice into this writer, returning whether the write succeeded.

fn write_char(&mut self, c: char) -> Result<(), Error>

Writes a char into this writer, returning whether the write succeeded.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Glue for usage of the write! macro with implementors of this trait.

impl Write for Pin<&mut CxxString>

fn write(&mut self, buf: &[u8]) -> Result<usize>

Writes a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.

impl Eq for CxxString

impl SharedPtrTarget for CxxString

impl UniquePtrTarget for CxxString

impl VectorElement for CxxString

impl WeakPtrTarget for CxxString