Struct ObjectStack

pub struct ObjectStack { /* private fields */ }

A high-level stack-based object builder that uses StackArena for memory management.

ObjectStack provides a more user-friendly interface on top of StackArena for building and managing objects in a stack-like fashion. It supports incremental object construction through the extend and finish methods, as well as direct formatting through the std::fmt::Write trait.

Features

• Push complete objects onto the stack
• Build objects incrementally using extend and finish methods
• Implements std::fmt::Write for string formatting directly into objects
• Stack-like (LIFO) allocation and deallocation pattern
• Memory-efficient with minimal overhead
• Automatic memory management with chunk reuse

Use Cases

ObjectStack is particularly useful for:

• String building and text processing
• Constructing complex objects incrementally
• Serialization operations
• Any scenario where objects need to be built in stages

Examples

use stack_arena::ObjectStack;
use std::fmt::Write;

let mut stack = ObjectStack::new();

// Push a complete object
stack.push(b"hello");

// Build an object incrementally
stack.extend("world ");
write!(&mut stack, "from {}", "Rust").unwrap();
let ptr = stack.finish();

// Access the object
let message = unsafe { std::str::from_utf8_unchecked(ptr.as_ref()) };
assert_eq!(message, "world from Rust");

// Pop the object when done
stack.pop();

Implementations

impl ObjectStack

pub fn new() -> Self

Creates a new empty ObjectStack with a default initial capacity.

The initial chunk size is 1024 bytes, managed by the underlying StackArena.

Examples

use stack_arena::ObjectStack;

let stack = ObjectStack::new();
assert!(stack.is_empty());

pub fn len(&self) -> usize

Returns the number of objects currently on the stack.

Examples

use stack_arena::ObjectStack;

let mut stack = ObjectStack::new();
assert_eq!(stack.len(), 0);

stack.push(b"hello");
assert_eq!(stack.len(), 1);

pub fn is_empty(&self) -> bool

Returns true if the stack contains no objects.

Examples

use stack_arena::ObjectStack;

let mut stack = ObjectStack::new();
assert!(stack.is_empty());

stack.push(b"hello");
assert!(!stack.is_empty());

pub fn push<P: AsRef<[u8]>>(&mut self, object: P) -> NonNull<[u8]>

Pushes a complete object onto the stack.

This method allocates memory for the object, copies the data, and returns a pointer to the allocated memory.

Parameters

• object - The data to push onto the stack, which can be any type that can be converted to a byte slice.

Returns

A non-null pointer to the allocated memory containing the data.

Examples

use stack_arena::ObjectStack;

let mut stack = ObjectStack::new();
let ptr = stack.push(b"hello world");
// The pointer is valid until the object is popped or freed

pub fn pop(&mut self)

Removes the most recently pushed object from the stack.

This method follows the LIFO (Last-In-First-Out) principle. After popping, any pointers to the popped object become invalid.

Panics

Panics if the stack is empty or if there is a partial object being built (i.e., if extend has been called but finish has not).

Examples

use stack_arena::ObjectStack;

let mut stack = ObjectStack::new();
stack.push(b"hello");
stack.push(b"world");
assert_eq!(stack.len(), 2);

stack.pop();
assert_eq!(stack.len(), 1);

pub fn extend<P: AsRef<[u8]>>(&mut self, value: P)

Extends the current object being built with additional data.

This method is used for incrementally building objects. Multiple calls to extend can be made before finalizing the object with finish. This method only supports extending the last allocation (following LIFO pattern), as it uses the underlying arena’s grow functionality.

Parameters

• value - The data to append to the current object, which can be any type that can be converted to a byte slice.

Examples

use stack_arena::ObjectStack;

let mut stack = ObjectStack::new();
stack.extend("Hello, ");
stack.extend("world!");
let ptr = stack.finish();
// ptr now points to "Hello, world!"

pub fn finish(&mut self) -> NonNull<[u8]>

Finalizes the current object being built and adds it to the stack.

This method should be called after one or more calls to extend to finalize the object and make it available on the stack.

Returns

A non-null pointer to the finalized object.

Examples

use stack_arena::ObjectStack;

let mut stack = ObjectStack::new();
stack.extend("Hello");
stack.extend(" world");
let ptr = stack.finish();
// ptr now points to "Hello world"

pub fn rollback(&mut self, data: &[u8])

Rolls back to a specific object, freeing it and all objects allocated after it.

This method allows for rolling back to a specific point in the allocation history by providing a reference to an object on the stack.

Parameters

• data - A reference to the object to free, along with all objects allocated after it.

Examples

use stack_arena::ObjectStack;

let mut stack = ObjectStack::new();
stack.push(b"first");
let second = stack.push(b"second");
stack.push(b"third");

// Free "second" and "third"
stack.rollback(unsafe { second.as_ref() });
assert_eq!(stack.len(), 1); // Only "first" remains

Trait Implementations

impl Debug for ObjectStack

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

Formats the value using the given formatter.

impl Write for ObjectStack

Implementation of the std::fmt::Write trait for ObjectStack.

This allows using the write! macro and other formatting utilities to write formatted text directly into the object being built.

Examples

use std::fmt::Write;
use stack_arena::ObjectStack;

let mut stack = ObjectStack::new();
write!(&mut stack, "Hello, {}!", "world").unwrap();
let formatted = stack.finish();
// formatted now points to "Hello, world!"

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

Writes a string into the arena.

This method extends the current object with the given string.

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.