base_strings.h File Reference

Sized UTF-8 string slices (String8) and manipulation utilities. More...

#include "base_macros.h"
#include "base_types.h"
#include <ctype.h>
#include <string.h>

Include dependency graph for base_strings.h:

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

Go to the source code of this file.

Classes
struct	String8
	A sized UTF-8 string slice. More...
struct	String8Node
	A node for building singly-linked lists of strings. More...
struct	String8List
	A singly-linked list of String8 slices. More...

Macros
#define	STR8(s)
	Wraps a C string literal into a String8 at compile time.
#define	STR8_FMT(s)
	Helper macro to use a String8 in a printf-style format string. Example:

Typedefs
typedef struct String8	String8
	A sized UTF-8 string slice.
typedef struct String8Node	String8Node
	A node for building singly-linked lists of strings.
typedef struct String8List	String8List
	A singly-linked list of String8 slices.

Functions
static String8	str8 (u8 *str, usize size)
	Creates a String8 from a raw pointer and explicit byte length.
static String8	str8_range (u8 *first, u8 *one_past_last)
	Creates a String8 spanning from first to one_past_last.
static String8	str8_cstr (const char *cstr)
	Converts a null-terminated C string into a String8.
static String8	str8_prefix (String8 str, usize size)
	Returns the first size bytes of str.
static String8	str8_suffix (String8 str, usize size)
	Returns the last size bytes of str.
static String8	str8_skip (String8 str, usize amt)
	Returns str with the first amt bytes removed.
static String8	str8_chop (String8 str, usize amt)
	Returns str with the last amt bytes removed.
static String8	str8_substr (String8 str, usize first, usize one_past_last)
	Returns the substring from byte index first to one_past_last.
static b32	str8_match (String8 a, String8 b)
	Returns 1 if a and b contain identical bytes (case-sensitive).
static b32	str8_match_nocase (String8 a, String8 b)
	Returns 1 if a and b are equal ignoring ASCII case.
static b32	str8_starts_with (String8 str, String8 prefix)
	Returns 1 if str begins with prefix.
static b32	str8_ends_with (String8 str, String8 suffix)
	Returns 1 if str ends with suffix.
static usize	str8_find_first (String8 str, u8 byte)
	Returns the byte index of the first occurrence of byte in str.
static void	str8_list_push (String8List *list, String8Node *node, String8 str)
	Appends a String8 to a String8List via a caller-allocated node.

Detailed Description

Sized UTF-8 string slices (String8) and manipulation utilities.

Provides safe, allocation-free string operations using pointer/length pairs rather than null-terminated C strings. This eliminates a whole class of bugs: buffer overflows from missing null terminators, O(n) strlen calls on hot paths, and ambiguous ownership when slicing into existing buffers.

Design

A String8 is a non-owning view into a byte buffer - it does not allocate or free memory. All slice operations (prefix, skip, substr, etc.) are O(1) pointer arithmetic with clamped bounds, so they never read or write out of range.

For building strings dynamically, see str_builder.h. For interning and deduplication, see base_map.h.

Null Termination

String8 slices are NOT null-terminated by default. If you need to pass one to a C API that requires a null terminator, use arena_push_cstr() or PUSH_CSTR() to copy the slice into an arena with a trailing NUL.

Usage

String8 path = STR8("include/base/base_strings.h");
 
// Slice operations - all O(1), no allocation.
String8 dir  = str8_prefix(path, 12);   // "include/base"
String8 file = str8_suffix(path, 15);   // "base_strings.h"
 
// Safe printf formatting via the STR8_FMT helper.
printf("dir: %.*s\n", STR8_FMT(dir));

Copyright

2026 Alfred Jijo (MIT License)

Definition in file base_strings.h.