golang-data-structures

Files (6)

• SKILL.md
• containers.md · references/
• generics.md · references/
• map-internals.md · references/
• pointers.md · references/
• slice-internals.md · references/

SKILL.md (first lines)

# 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](references/containers.md) 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](references/slice-internals.md) and [map semantics](references/map-internals.md) 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](references/generics.md).

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](references/pointers.md).

## 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.

From reagin/agent-skills, MIT.

More from reagin/agent-skills