pub trait PyStringMethods<'py>: Sealed {
// Required methods
fn to_str(&self) -> PyResult<&str>;
fn to_cow(&self) -> PyResult<Cow<'_, str>>;
fn to_string_lossy(&self) -> Cow<'_, str>;
fn encode_utf8(&self) -> PyResult<Bound<'py, PyBytes>>;
unsafe fn data(&self) -> PyResult<PyStringData<'_>>;
}Expand description
Implementation of functionality for PyString.
These methods are defined for the Bound<'py, PyString> smart pointer, so to use method call
syntax these methods are separated into a trait, because stable Rust does not yet support
arbitrary_self_types.
Required Methods§
Sourcefn to_str(&self) -> PyResult<&str>
fn to_str(&self) -> PyResult<&str>
Gets the Python string as a Rust UTF-8 string slice.
Returns a UnicodeEncodeError if the input is not valid unicode
(containing unpaired surrogates).
Sourcefn to_cow(&self) -> PyResult<Cow<'_, str>>
fn to_cow(&self) -> PyResult<Cow<'_, str>>
Converts the PyString into a Rust string, avoiding copying when possible.
Returns a UnicodeEncodeError if the input is not valid unicode
(containing unpaired surrogates).
Sourcefn to_string_lossy(&self) -> Cow<'_, str>
fn to_string_lossy(&self) -> Cow<'_, str>
Converts the PyString into a Rust string.
Unpaired surrogates invalid UTF-8 sequences are
replaced with U+FFFD REPLACEMENT CHARACTER.
Sourcefn encode_utf8(&self) -> PyResult<Bound<'py, PyBytes>>
fn encode_utf8(&self) -> PyResult<Bound<'py, PyBytes>>
Encodes this string as a Python bytes object, using UTF-8 encoding.
Sourceunsafe fn data(&self) -> PyResult<PyStringData<'_>>
unsafe fn data(&self) -> PyResult<PyStringData<'_>>
Obtains the raw data backing the Python string.
If the Python string object was created through legacy APIs, its internal storage format will be canonicalized before data is returned.
§Safety
This function implementation relies on manually decoding a C bitfield. In practice, this works well on common little-endian architectures such as x86_64, where the bitfield has a common representation (even if it is not part of the C spec). The PyO3 CI tests this API on x86_64 platforms.
By using this API, you accept responsibility for testing that PyStringData behaves as expected on the targets where you plan to distribute your software.