Struct StbString 

#[repr(C)]
pub struct StbString {
    pub ptr: *mut c_char,
    pub len: usize,
}

An owned UTF-8 string crossing the ABI as a (ptr, len) pair.

Copy (raw pointers are Copy): copying a StbString duplicates the pointer, not the allocation. The receiver of a StbString owns the allocation and MUST free it exactly once by calling the producer’s FreeStringFn (or StbString::free_with / [StbString::free_host]). Never free a StbString you did not receive as an owner (e.g. one built from a borrow via [StbString::from_ref], which is non-owning — its free is a no-op only if the producer guarantees the buffer outlives the call; in practice inputs cross as StbStringRef instead).

Construction ownership contract:

• StbString::from_owned — takes a Box<[u8]> the caller allocated; the StbString now owns it; free deallocates.
• StbString::from_boxed_str / StbString::from_string — convenience over from_owned (host side, needs alloc).
• StbString::empty — null/0; free is a no-op.

Null ptr ⇒ empty (len MUST be 0). A null pointer is never dereferenced.

Fields

ptr: *mut c_char

UTF-8 bytes. Null when len == 0 (empty string).

len: usize

Byte length (NOT a NUL terminator — the buffer is NOT NUL-terminated).

Implementations

impl StbString

pub const fn empty() -> Self

An empty string: null pointer, zero length. free is a no-op.

pub const fn is_empty(&self) -> bool

Whether this is the empty/null string.

impl StbString

pub fn from_owned(buf: Box<[u8]>) -> Self

Wrap an allocation the caller already boxed. The StbString takes ownership: a later free_with(free_fn) will deallocate it via the producer’s free_string.

The buffer MUST be UTF-8.

pub fn from_string(s: String) -> Self

Convenience: from a String, transferring ownership. After this the passed String is consumed and must not be reused.

pub fn from_vec(v: Vec<u8>) -> Self

Convenience: from a Vec<u8> (UTF-8), transferring ownership.

pub fn from_boxed_str(s: Box<str>) -> Self

Convenience: from a boxed str.

pub fn to_string_lossy(&self) -> String

Copy this StbString’s bytes into an owned String (without freeing the original — the caller still owns the original allocation). Use this to read a received StbString into safe Rust; then free the original.

impl StbString

pub fn free_with(self, free_fn: Option<FreeStringFn>)

Free this StbString via the given free_string fn, if non-null and non-empty. Consumes ownership (the value is Copy, but semantically the caller relinquishes the allocation).

After this call the bytes are invalid; do not use the StbString again.

Trait Implementations

impl Clone for StbString

fn clone(&self) -> StbString

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for StbString

impl Send for StbString

impl Sync for StbString