Documentation for Caffeine Engine Containers module - Phase 1: Atomic Foundation
The Containers module provides data structures optimized for game development with cache locality and zero heap allocations where possible.
Location: src/containers/
| File | Description | Status |
|---|---|---|
Vector.hpp |
Dynamic array with cache-friendly contiguous memory | ✅ Complete |
HashMap.hpp |
Hash table with O(1) lookup | ✅ Complete |
StringView.hpp |
String without ownership (zero-copy) | ✅ Complete |
FixedString.hpp |
Inline buffer string (zero heap) | ✅ Complete |
Dynamic array with automatic growth. Supports custom allocators or defaults to global operator new.
// Default construction (uses global new/delete)
Caffeine::Vector<int> vec;
vec.pushBack(42);
// With custom allocator
Caffeine::LinearAllocator alloc(1024);
Caffeine::Vector<int> vec2(&alloc);| Method | Complexity | Description |
|---|---|---|
pushBack() |
O(1) amortized | Add element |
operator[] |
O(1) | Access by index |
reserve() |
O(n) | Pre-allocate capacity |
clear() |
O(n) | Clear all elements |
size() |
O(1) | Get element count |
capacity() |
O(1) | Get allocated capacity |
Open addressing hash map with linear probing.
Caffeine::HashMap<int, const char*> map;
map.set(1, “one”);
map.set(2, “two”);
const char* val = map.get(1);
bool exists = map.contains(1);| Method | Complexity | Description |
|---|---|---|
set() |
O(1) amortized | Insert or update |
get() |
O(1) | Retrieve value |
contains() |
O(1) | Check key exists |
remove() |
O(1) | Delete key-value |
Zero-copy string reference (pointer + length).
Caffeine::StringView sv(“Hello World”, 5); // “Hello”Stack-allocated string with inline buffer.
Caffeine::FixedString<char, 32> fs;
fs.append(“Hello”);- Vector: Contiguous memory, no fragmentation
- HashMap<K,V>: Linear probing for cache-friendly access
- StringView: Zero-copy, no allocation
- FixedString<T,N>: Inline buffer, zero heap
- ROADMAP.md - Phase 1 RF1.7-RF1.9
- SPECS.md - Development rules
- architecture_specs.md - Technical specifications
- API Reference - Complete API documentation
- Test Documentation - Container tests
- Core Module - Foundation types
- Memory Module - Allocators used by containers
- Math Module - Vector math types