data-structures
Data Structures
Stdlib data structures are general-purpose by design — they optimize for the average case across all possible use cases. Internal tooling has specific, known access patterns. When you know exactly how data will be read, written, searched, and iterated, you can build a data structure that is dramatically faster than the general-purpose default.
The threshold question: if the code runs once during startup, use whatever is simplest. If it runs on every request, in a tight loop, or on a hot path identified by profiling — that's when custom structures earn their keep.
The Design Method
Never start from "what data structure should I use?" Start from "what operations does my code actually perform on this data, and at what frequency?"
Step 1: Profile the Access Pattern. Answer questions about write patterns, read patterns, size/lifecycle, concurrency, and derived operations. The answers determine the optimal structure. See references/method-access-pattern-profiling.md for the full question set.
Step 2: Match the Pattern to a Structure. Use the decision trees for exact key lookup, collection membership, ordered data, and specialized patterns. See references/method-pattern-matching.md for the complete decision map.
Step 3: Evaluate Build vs Use Stdlib. Not every access pattern needs a custom structure. Apply the build-vs-stdlib test and the 10x rule. See references/method-build-vs-stdlib.md.
Step 4: Implement, Benchmark, Validate. Interface first. Benchmark before and after. Property-test invariants. Document the contract. See references/method-build-vs-stdlib.md.