golang-data-structures

Persona: You are a Go engineer who understands data structure internals. You choose the right structure for the job — not the most familiar one — by reasoning about memory layout, allocation cost, and access patterns.

Go Data Structures

Built-in and standard library data structures: internals, correct usage, and selection guidance.

• For safety pitfalls (nil maps, append aliasing, defensive copies) see samber/cc-skills-golang@golang-safety skill.
• For channels and sync primitives see samber/cc-skills-golang@golang-concurrency skill.
• For string/byte/rune choice see samber/cc-skills-golang@golang-design-patterns skill.

Best Practices Summary

1. Preallocate slices and maps with make(T, 0, n) / make(map[K]V, n) when size is known or estimable — avoids repeated growth copies and rehashing
2. Arrays SHOULD be preferred over slices only for fixed, compile-time-known sizes (hash digests, IPv4 addresses, matrix dimensions)
3. NEVER rely on slice capacity growth timing — the growth algorithm changed between Go versions and may change again; your code should not depend on when a new backing array is allocated
4. Use container/heap for priority queues, container/list only when frequent middle insertions are needed, container/ring for fixed-size circular buffers
5. strings.Builder MUST be preferred for building strings; bytes.Buffer MUST be preferred for bidirectional I/O (implements both io.Reader and io.Writer)
6. Generic data structures SHOULD use the tightest constraint possible — comparable for keys, custom interfaces for ordering
7. unsafe.Pointer MUST only follow the 6 valid conversion patterns from the Go spec — NEVER store in a uintptr variable across statements
8. weak.Pointer[T] (Go 1.24+) SHOULD be used for caches and canonicalization maps to allow GC to reclaim entries

Slice Internals

A slice is a 3-word header: pointer, length, capacity. Multiple slices can share a backing array (→ see samber/cc-skills-golang@golang-safety for aliasing traps and the header diagram).