Simplified arena allocator

Author: bamless

AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

CLAUDE.md

@@ -0,0 +1,111 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project overview
+
+extlib is a **single-header C99 library** (`extlib.h`) providing data structures and utilities missing
+from the C standard library: dynamic arrays, hashmaps, string slices/buffers, arenas, a context
+system for allocators/logging, and cross-platform IO. It supports no-std and wasm targets.
+
+## Build and test commands
+
+```sh
+make                    # Build all examples
+make test               # Build and run test suite
+make format             # Format all .c/.h files with clang-format
+make clean              # Remove built artifacts
+./test/test <suite>     # Run only one test suite (e.g. ./test/test array)
+```
+
+The test binary accepts an optional suite name argument to filter tests. Suite names match the first
+argument of `CTEST(suite, name)` in `test/test.c` (e.g. `alloc`, `temp`, `arena`, `array`, `sb`,
+`slice`, `hmap`, `defer`, `logging`, `io`).
+
+Compiler flags: `-Wall -Wextra -Wno-override-init -std=c99 -ggdb`.
+
+## Architecture
+
+The entire library lives in `extlib.h` (~3700 lines). In exactly one translation unit, define
+`EXTLIB_IMPL` before including the header to emit the implementation. All other files just
+`#include "extlib.h"` for declarations only.
+
+### Sections
+
+Navigate to a component by grepping for `SECTION: <name>`. The header is organized as declarations
+first (lines ~65–1210), then `#ifdef EXTLIB_IMPL` implementations (~1710–2800), then debug helpers
+and shorthand aliases (~2800–3580).
+
+Key sections: **Context**, **Allocators**, **Temporary allocator**, **Arena allocator**, **Dynamic
+array**, **Hashmap**, **String buffer**, **String slice**, **IO**.
+
+### Naming convention
+
+Every public symbol has an `ext_` / `Ext_` / `EXT_` prefix. Unless `EXTLIB_NO_SHORTHANDS` is
+defined, unprefixed aliases are also available (e.g. `array_push` for `ext_array_push`, `Arena` for
+`Ext_Arena`). **Always use the unprefixed shorthand names** in code that consumes extlib. Always
+use prefixed one for new implementations inside extlib.
+
+### Generic containers (dynamic array and hashmap)
+
+Both dynamic arrays and hashmaps are "generic" via a struct-layout convention — the user defines a
+struct with specific fields and passes a pointer to the container macros:
+
+**Dynamic array** — struct must have fields: `T* items; size_t size, capacity; Allocator* allocator;`
+
+**Hashmap** — entry struct must have fields: `K key; V value;` and the map struct must have:
+`Entry* entries; size_t* hashes; size_t size, capacity; Allocator* allocator;`
+
+Hashmaps come in three key-type flavors: integer keys (`hmap_put`/`hmap_get`), C-string keys
+(`hmap_put_cstr`/`hmap_get_cstr`), and `StringSlice` keys (`hmap_put_ss`/`hmap_get_ss`).
+
+### Context and allocators
+
+A thread-local `ext_context` pointer controls the default allocator and log level. Use
+`push_context` / `pop_context` (or `PUSH_ALLOCATOR` / `PUSH_CONTEXT` scope macros) to temporarily
+swap allocators. Individual containers can also override the allocator via their `.allocator` field.
+
+### Adding new functions — checklist
+
+Every new public function needs four pieces:
+
+1. **Declaration** (in the declarations section, ~65–1210) with `ext_` prefix and doc comment
+2. **Implementation** (inside `#ifdef EXTLIB_IMPL`, ~1710–2800) using `ext_` prefix
+3. **Shorthand alias** (in `#ifndef EXTLIB_NO_SHORTHANDS`, ~3480–3580) mapping unprefixed to prefixed
+4. **Tests** in `test/test.c` using the shorthand names
+
+For functions with a `StringSlice` parameter, also add a `_cstr` convenience variant that converts
+via `ext_ss_from_cstr` and delegates.
+
+### Declaration ordering constraints
+
+The `Ext_StringSlice` typedef lives at the start of the String slice section (~line 1064). Any
+declaration that references `Ext_StringSlice` must appear **after** this typedef. This means
+StringBuffer functions that take `Ext_StringSlice` parameters (e.g. `ext_sb_append_path`) must be
+declared in or after the String slice declaration section, not in the StringBuffer section above it.
+
+### `EXTLIB_NO_STD` / WASM considerations
+
+When adding functions that use libc utilities (e.g. `toupper`, `tolower`, `isspace`), you must
+provide fallback implementations in the `#else` branch of the `#ifndef EXTLIB_NO_STD` guard. The
+WASM build target (`make` builds `examples/03_arena.wasm`) compiles with `EXTLIB_WASM` which
+implies `EXTLIB_NO_STD`, and will fail if libc functions are used without fallbacks.
+
+The `<ctype.h>` include and its no-std fallbacks (`isspace`, `toupper`, `tolower`) live at the top
+of the String buffer implementation section (around line 2330).
+
+### Platform-conditional code
+
+Use `#ifdef EXT_WINDOWS` for Windows-specific behavior (e.g. backslash path separators). The
+platform macros (`EXT_WINDOWS`, `EXT_LINUX`, `EXT_POSIX`, etc.) are defined near the top of the
+header (~line 84). When testing platform-specific code on Linux, temporarily remove the `#ifdef`
+guard, verify, then restore it.
+
+### Testing
+
+Tests use the [ctest](https://github.com/bvdberg/ctest) framework (`test/ctest.h`). The test
+harness in `test/test.c` wraps all tests in a tracking allocator that detects memory leaks — any
+un-freed allocations cause a test failure.
+
+Always run both `make test` (test suite) and `make` (all examples including WASM) to verify changes.
+The WASM build often catches missing no-std fallbacks that the native build doesn't.