str_builder.h File Reference

Allocator-agnostic StringBuilder for efficient string concatenation. More...

#include "base_macros.h"
#include "base_strings.h"
#include "base_types.h"
#include "memory/mem_allocator.h"
#include <stdarg.h>
#include <stdio.h>

Include dependency graph for str_builder.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	StringBuilder
	An allocator-agnostic string builder. More...

Typedefs
typedef struct StringBuilder	StringBuilder
	An allocator-agnostic string builder.

Functions
static void	sb_append (StringBuilder *sb, MemAllocator *alloc, String8 str)
	Appends a String8 slice to the builder.
static void	sb_append_cstr (StringBuilder *sb, MemAllocator *alloc, const char *cstr)
	Appends a null-terminated C string to the builder.
static void	sb_append_fmt (StringBuilder *sb, MemAllocator *alloc, const char *fmt,...)
	Appends a printf-style formatted string to the builder.
static String8	sb_join (StringBuilder *sb, MemAllocator *out_alloc)
	Materializes all appended segments into a single contiguous String8.
static void	sb_reset (StringBuilder *sb)
	Resets the builder to empty without touching the allocator.

Detailed Description

Allocator-agnostic StringBuilder for efficient string concatenation.

A StringBuilder accumulates string segments as a singly-linked list of String8Node chunks, each allocated from a caller-supplied MemAllocator. No copying occurs during appending - the final contiguous String8 is only materialized when sb_join() is called.

Why caller decides the allocator at join time

The builder nodes are cheap scratch allocations - they only need to live long enough to produce the final string. Passing a separate allocator to sb_join() lets you put the result exactly where it needs to live (e.g., a permanent arena) while discarding the intermediate nodes cheaply.

Usage

MemAllocator scratch = mem_allocator_create(ARENA, MB(1));
MemAllocator result  = mem_allocator_create(ARENA, MB(4));
 
StringBuilder sb = {0};
sb_append(&sb, &scratch, STR8("Hello, "));
sb_append_fmt(&sb, &scratch, "%s!", "World");
 
String8 out = sb_join(&sb, &result);
mem_free_all(&scratch); // wipe nodes cheaply

Copyright

2026 Alfred Jijo (MIT License)

Definition in file str_builder.h.