Struct ExString 

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

A growable, allocator-backed UTF-8 string.

Invariant

The byte buffer buf always contains valid UTF-8. Methods that accept raw &str or char values uphold this invariant automatically. The as_str / as_bytes accessors expose the buffer read-only so callers cannot introduce invalid UTF-8.

Lifetime

The allocator reference 'a must outlive the ExString.

Implementations

impl<'a> ExString<'a>

pub fn new(alloc: &'a dyn Allocator) -> Self

Creates a new, empty ExString that will allocate through alloc.

Examples found in repository

examples/pool_string.rs (line 11)

fn main() {
    let sys = SystemAllocator;

    let pool = PoolAllocator::typed::<[u8; 128]>(&sys, 5).unwrap();

    let mut log = ExString::new(&pool);
    write!(log, "Status: {}, Code: {}", "OK", 200).unwrap();

    println!("Log message: {}", log.as_str());
    println!("Slots left in pool: {}", pool.free_count());
}

examples/full.rs (line 42)

fn main() {
    let sys = CountingAllocator::new(SystemAllocator);
    
    println!("=== ExBox & SystemAllocator ===");
    {
        let b = ExBox::new(42, &sys).expect("Failed to alloc Box");
        println!("Box value: {}", *b);
    }
    
    let stats = sys.stats();
    println!("Allocated: {} bytes", stats.bytes_allocated);
    println!("Deallocated: {} bytes", stats.bytes_freed);
    println!("Live bytes: {}\n", stats.bytes_live);

    println!("=== ExVec & Arena (Linear Allocation) ===");
    {
        let arena = ArenaAllocator::new(&sys);
        
        let mut v = ExVec::new(&arena);
        for i in 0..5 {
            v.push(i * 10);
        }
        println!("Vec: {:?}", v.as_slice());
        
        arena.reset();
        println!("Arena reset performed");
    }

    println!("\n=== ExString & Pool (Fixed Size Blocks) ===");
    {
        let pool = PoolAllocator::typed::<[u8; 64]>(&sys, 10)
            .expect("Failed to create Pool");
        
        let mut s = ExString::new(&pool);
        s.push_str("Hello from ZigZag!");
        
        println!("String in Pool: {}", s.as_str());
        println!("Pool free slots: {}", pool.free_count());
    }

    println!("\n=== Final Global Stats ===");
    let final_stats = sys.stats();
    println!("Total count of alloc() calls: {}", final_stats.allocs);
    println!("Total count of dealloc() calls: {}", final_stats.deallocs);
    println!("Total bytes allocated: {}", final_stats.bytes_allocated);
    println!("Total bytes freed: {}", final_stats.bytes_freed);
    println!("Current leak/live size: {} bytes", final_stats.bytes_live);
}

pub fn from_str(s: &str, alloc: &'a dyn Allocator) -> Self

Creates an ExString pre-populated with a copy of s.

pub fn push_str(&mut self, s: &str)

Appends the string slice s to the end of this string.

Grows the underlying buffer if necessary.

Panics

Panics if the backing allocator cannot satisfy the growth request.

Examples found in repository

examples/full.rs (line 43)

fn main() {
    let sys = CountingAllocator::new(SystemAllocator);
    
    println!("=== ExBox & SystemAllocator ===");
    {
        let b = ExBox::new(42, &sys).expect("Failed to alloc Box");
        println!("Box value: {}", *b);
    }
    
    let stats = sys.stats();
    println!("Allocated: {} bytes", stats.bytes_allocated);
    println!("Deallocated: {} bytes", stats.bytes_freed);
    println!("Live bytes: {}\n", stats.bytes_live);

    println!("=== ExVec & Arena (Linear Allocation) ===");
    {
        let arena = ArenaAllocator::new(&sys);
        
        let mut v = ExVec::new(&arena);
        for i in 0..5 {
            v.push(i * 10);
        }
        println!("Vec: {:?}", v.as_slice());
        
        arena.reset();
        println!("Arena reset performed");
    }

    println!("\n=== ExString & Pool (Fixed Size Blocks) ===");
    {
        let pool = PoolAllocator::typed::<[u8; 64]>(&sys, 10)
            .expect("Failed to create Pool");
        
        let mut s = ExString::new(&pool);
        s.push_str("Hello from ZigZag!");
        
        println!("String in Pool: {}", s.as_str());
        println!("Pool free slots: {}", pool.free_count());
    }

    println!("\n=== Final Global Stats ===");
    let final_stats = sys.stats();
    println!("Total count of alloc() calls: {}", final_stats.allocs);
    println!("Total count of dealloc() calls: {}", final_stats.deallocs);
    println!("Total bytes allocated: {}", final_stats.bytes_allocated);
    println!("Total bytes freed: {}", final_stats.bytes_freed);
    println!("Current leak/live size: {} bytes", final_stats.bytes_live);
}

pub fn push(&mut self, ch: char)

Appends the Unicode scalar ch (encoded as UTF-8) to this string.

Panics

Panics if the backing allocator cannot satisfy the growth request.

pub fn as_str(&self) -> &str

Returns the string content as a &str.

Safety Justification

The buffer is always valid UTF-8 because only push_str and push can append bytes, and both sources (&str / char) are guaranteed to be valid UTF-8 by Rust’s type system. clear simply sets len = 0 without writing invalid bytes.

Examples found in repository

examples/pool_string.rs (line 14)

fn main() {
    let sys = SystemAllocator;

    let pool = PoolAllocator::typed::<[u8; 128]>(&sys, 5).unwrap();

    let mut log = ExString::new(&pool);
    write!(log, "Status: {}, Code: {}", "OK", 200).unwrap();

    println!("Log message: {}", log.as_str());
    println!("Slots left in pool: {}", pool.free_count());
}

examples/full.rs (line 45)

fn main() {
    let sys = CountingAllocator::new(SystemAllocator);
    
    println!("=== ExBox & SystemAllocator ===");
    {
        let b = ExBox::new(42, &sys).expect("Failed to alloc Box");
        println!("Box value: {}", *b);
    }
    
    let stats = sys.stats();
    println!("Allocated: {} bytes", stats.bytes_allocated);
    println!("Deallocated: {} bytes", stats.bytes_freed);
    println!("Live bytes: {}\n", stats.bytes_live);

    println!("=== ExVec & Arena (Linear Allocation) ===");
    {
        let arena = ArenaAllocator::new(&sys);
        
        let mut v = ExVec::new(&arena);
        for i in 0..5 {
            v.push(i * 10);
        }
        println!("Vec: {:?}", v.as_slice());
        
        arena.reset();
        println!("Arena reset performed");
    }

    println!("\n=== ExString & Pool (Fixed Size Blocks) ===");
    {
        let pool = PoolAllocator::typed::<[u8; 64]>(&sys, 10)
            .expect("Failed to create Pool");
        
        let mut s = ExString::new(&pool);
        s.push_str("Hello from ZigZag!");
        
        println!("String in Pool: {}", s.as_str());
        println!("Pool free slots: {}", pool.free_count());
    }

    println!("\n=== Final Global Stats ===");
    let final_stats = sys.stats();
    println!("Total count of alloc() calls: {}", final_stats.allocs);
    println!("Total count of dealloc() calls: {}", final_stats.deallocs);
    println!("Total bytes allocated: {}", final_stats.bytes_allocated);
    println!("Total bytes freed: {}", final_stats.bytes_freed);
    println!("Current leak/live size: {} bytes", final_stats.bytes_live);
}

pub fn len(&self) -> usize

Returns the number of bytes (not Unicode code points) in the string.

pub fn is_empty(&self) -> bool

Returns true if the string contains no bytes.

pub fn capacity(&self) -> usize

Returns the number of bytes the buffer can hold without reallocating.

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

Returns the raw byte slice of the string contents.

pub fn clear(&mut self)

Clears the string, setting its length to zero.

Does not release the backing allocation.

pub fn find_byte(&self, byte: u8) -> Option<usize>

Returns the byte offset of the first occurrence of byte, or None.

pub fn contains_byte(&self, byte: u8) -> bool

Returns true if the string contains the given byte.

pub fn count_byte(&self, byte: u8) -> usize

Returns the number of times byte appears in the string.

pub fn for_each_byte_match<F: FnMut(usize)>(&self, byte: u8, f: F)

Calls f with the byte offset of every occurrence of byte.

pub fn replace_byte(&mut self, from: u8, to: u8)

Replaces every occurrence of from with to in-place.

Panics

If from and to have different UTF-8 lengths, the resulting string may no longer be valid UTF-8. This method is designed for single-byte replacements only (e.g. replacing b'\n' with b' ').

Trait Implementations

impl Debug for ExString<'_>

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

Formats the value using the given formatter.

impl Display for ExString<'_>

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

Formats the value using the given formatter.

impl PartialEq<str> for ExString<'_>

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 ExString<'_>

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 Write for ExString<'_>

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

Appends s to the string. Called by write! / writeln!.

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.