Struct StrBuf 

pub struct StrBuf<'a> { /* private fields */ }

🧶 A borrowed UTF-8 string buffer over caller-provided bytes.

---

^{📍 text/str}

---

It stores a valid UTF-8 prefix inside a mutable byte slice, leaving the remaining bytes as spare capacity.

This is the borrowed counterpart to fixed-capacity owned strings.

Implementations

impl<'a> StrBuf<'a>

pub const fn new(buf: &'a mut [u8]) -> Self

Creates an empty buffer over buf.

pub const fn from_bytes( buf: &'a mut [u8], len: usize, ) -> Result<Self, InvalidText>

Creates a buffer from the first len bytes of buf.

Errors

Returns InvalidText::MismatchedCapacity if len > buf.len(), or InvalidText::Utf8 if buf[..len] is not valid UTF-8.

pub const unsafe fn from_bytes_unchecked(buf: &'a mut [u8], len: usize) -> Self

Available on crate feature unsafe_str only.

Creates a buffer from the first len bytes of buf without validation.

Safety

len must be <= buf.len() and buf[..len] must be valid UTF-8.

pub const fn as_str(&self) -> &str

Returns the initialized UTF-8 string.

pub const fn as_mut_str(&mut self) -> &mut str

Returns the initialized UTF-8 string mutably.

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

Returns the initialized bytes.

pub const unsafe fn as_bytes_mut(&mut self) -> &mut [u8]

Available on crate feature unsafe_str only.

Returns the initialized bytes mutably.

Safety

The caller must preserve valid UTF-8 in self.as_bytes().

pub const fn spare_capacity_mut(&mut self) -> &mut [u8]

Returns the spare byte capacity.

Writing here does not change the string length. Use set_len_checked afterwards to extend safely.

pub const fn into_str(self) -> &'a str

Consumes the buffer and returns the initialized UTF-8 string.

pub const fn len(&self) -> usize

Returns the initialized length in bytes.

pub const fn capacity(&self) -> usize

Returns the total byte capacity.

pub const fn remaining_capacity(&self) -> usize

Returns the remaining byte capacity.

pub const fn is_empty(&self) -> bool

Returns true if no bytes are initialized.

pub const fn is_full(&self) -> bool

Returns true if no spare capacity remains.

pub const fn clear(&mut self)

Clears the string.

pub const fn truncate(&mut self, new_len: usize) -> Result<(), InvalidText>

Truncates the string to new_len bytes.

Does nothing if new_len >= self.len().

Errors

Returns InvalidText::Utf8 if new_len is not a UTF-8 boundary.

pub const fn set_len_checked(&mut self, len: usize) -> Result<(), InvalidText>

Sets the initialized length after validating buf[..len].

Errors

Returns InvalidText::MismatchedCapacity if len > self.capacity(), or InvalidText::Utf8 if buf[..len] is not valid UTF-8.

pub const unsafe fn set_len_unchecked(&mut self, len: usize)

Available on crate feature unsafe_str only.

Sets the initialized length without validation.

Safety

len must be <= self.capacity() and self.buf[..len] must be valid UTF-8.

pub const fn push(&mut self, ch: char) -> usize

Appends ch if it fits, returning the number of bytes written.

Returns 0 if there is not enough remaining capacity.

pub const fn try_push(&mut self, ch: char) -> Result<usize, NotEnoughSpace>

Appends ch, returning its UTF-8 length.

Errors

Returns NotEnoughSpace if the character does not fit.

pub const fn push_str(&mut self, s: &str) -> usize

Appends the largest UTF-8 prefix of s that fits.

Returns the number of bytes written.

pub const fn try_push_str(&mut self, s: &str) -> Result<usize, usize>

Appends the largest UTF-8 prefix of s that fits.

Returns Ok(written) if the complete string fit, otherwise Err(written) with the valid prefix length that was written.

pub const fn try_push_str_complete( &mut self, s: &str, ) -> Result<usize, NotEnoughSpace>

Appends s only if it fits completely.

Errors

Returns NotEnoughSpace without modifying the buffer if s does not fit.

pub fn format( buf: &'a mut [u8], args: FmtArguments<'_>, ) -> Result<&'a str, &'a str>

Writes formatted output into buf.

Returns:

• Ok(&str) if all formatting writes completed.
• Err(&str) with the valid partial result if formatting stopped early.

Unlike FmtWriter, this uses StrBuf’s FmtWrite implementation: every write_str chunk is all-or-nothing.

Trait Implementations

impl Write for StrBuf<'_>

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

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.