reagin Go Data Structures
Choose the simplest representation that satisfies the operation, ownership, and lifecycle requirements. Internal runtime layouts and growth policies are implementation details unless the current toolchain documents them as API.
Gather requirements
Before changing a representation, inspect nearby code, go.mod, tests, serialization contracts, concurrency, and performance evidence. Determine:
- dominant operations and their required complexity;
- expected and worst-case size;
- insertion, deletion, and ordering requirements;
- uniqueness and key equality rules;
- mutation and ownership across API boundaries;
- whether nil, empty, and absent have distinct external meaning;
- whether the structure is shared concurrently;
- whether allocation or retention is a measured concern.
Do not replace a familiar built-in type with a custom container solely for theoretical complexity at small sizes.
Selection guide
| Need | Starting point | Important trade-off |
|---|---|---|
| Ordered, indexable sequence | Slice | Append can replace the backing array; subslices can retain or alias data |
| Fixed-size comparable value | Array | Assignment copies the full value; size is part of the type |
| Keyed lookup | Map | Iteration order is unspecified; map access is not safe with concurrent writes |
| Set membership | map[T]struct{} or project type |
Decide whether a named abstraction improves the API |
| Priority queue | container/heap |
Interface adapter and heap invariant |
| O(1) removal with a retained node handle | container/list |
Allocation and poor locality often lose to slices otherwise |
| Fixed circular traversal | container/ring or a slice-based ring |
Choose based on indexing, storage, and mutation needs |
| String construction | strings.Builder |
Builder is write-only and must not be copied after use |
| Read/write byte buffer | bytes.Buffer |
Exposes byte-oriented I/O and mutable storage |
Read container choices when a standard container or buffering API is under consideration.
Stable semantics
- Preallocate a slice or map when a credible size estimate exists and the allocation matters. Do not reserve a large worst case without evidence.
- Treat slice assignment, reslicing, and map assignment as sharing underlying state. Clone at ownership boundaries when independent mutation is required.
- Treat nil and empty according to the API contract. Both can be idiomatic; they differ in some encodings and in whether a map can be written.
- Do not depend on a particular slice growth factor, map bucket layout, or whether deleted map storage is returned to the runtime.
- Map iteration order must not drive deterministic output. Collect and sort keys when order is part of the contract.
- A value stored in a map cannot be addressed directly. Copy-modify-store or use pointers when identity and mutation semantics justify them.
See slice semantics and map semantics for aliasing, retention, and copying decisions.
Generics and pointers
Use generics when one algorithm or representation is genuinely identical across types and the constraint expresses the required operations. Prefer a concrete type or interface when behavior differs by domain. See generic collections.
Choose values or pointers based on identity, mutation, optionality, copying, allocation, and API contracts—not a universal byte threshold. Use unsafe only for a demonstrated low-level requirement and verify against the current toolchain documentation. See pointer choices.
Verification
Add tests for observable semantics: ordering, duplicate handling, nil/empty behavior, aliasing, boundary ownership, and error cases. Benchmark only when the choice is performance-sensitive under representative sizes. If concurrency is involved, design synchronization separately; changing the container does not make an ownership protocol safe.