golang-data-structures
Golang data structures — slices (internals, capacity growth, preallocation, slices package), maps (internals, hash buckets, maps package), arrays, container/list/heap/ring, strings.Builder vs bytes.Buffer, generic collections, pointers (unsafe.Pointer, weak.Pointer), and copy semantics. Use when choosing or optimizing Go data structures, implementing generic containers, using container/ packages, unsafe or weak pointers, or questioning slice/map internals.
samber · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add samber/cc-skills-golang --skill golang-data-structuresAbout this skill
name: golang-data-structures description: "Golang data structures — slices (internals, capacity growth, preallocation, slices package), maps (internals, hash buckets, maps package), arrays, container/list/heap/ring, strings.Builder vs bytes.Buffer, generic collections, pointers (unsafe.Pointer, weak.Pointer), and copy semantics. Use when choosing or optimizing Go data structures, implementing generic containers, using container/ packages, unsafe or weak pointers, or questioning slice/map internals." user-invocable: true license: MIT compatibility: Designed for Claude Code, Codex or similar harness, and for projects using Golang. metadata: author: samber version: "1.2.0" openclaw: emoji: "🗃" homepage: https://github.com/samber/cc-skills-golang requires: bins: - go install: [] allowed-tools: Read Edit Write Glob Grep Bash(go:) Bash(golangci-lint:) Bash(git:) Agent Bash(godig:) Bash(gopls:) LSP mcp__gopls__ mcp__context7__resolve-library-id mcp__context7__query-docs paths:
- "**/*.go"
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
- 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 - Arrays SHOULD be preferred over slices only for fixed, compile-time-known sizes (hash digests, IPv4 addresses, matrix dimensions)
- 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
- Use
container/heapfor priority queues,container/listonly when frequent middle insertions are needed,container/ringfor fixed-size circular buffers strings.BuilderMUST be preferred for building strings;bytes.BufferMUST be preferred for bidirectional I/O (implements bothio.Readerandio.Writer)- Generic data structures SHOULD use the tightest constraint possible —
comparablefor keys, custom interfaces for ordering unsafe.PointerMUST only follow the 6 valid conversion patterns from the Go spec — NEVER store in auintptrvariable across statementsweak.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).
Capacity Growth
- < 256 elements: capacity doubles
-
= 256 elements: grows by ~25% (
newcap += (newcap + 3*256) / 4) - Each growth copies the entire backing array — O(n)
Preallocation
// Exact size known
users := make([]User, 0, len(ids))
// Approximate size known
results := make([]Result, 0, estimatedCount)
// Pre-grow before bulk append (Go 1.21+)
s = slices.Grow(s, additionalNeeded)
slices Package (Go 1.21+)
Key functions: Sort/SortFunc, BinarySearch, Contains, Compact, Grow. For Clone, Equal, DeleteFunc → see samber/cc-skills-golang@golang-safety skill.
Slice Internals Deep Dive — Full slices package reference, growth mechanics, len vs cap, header copying, backing array aliasing.
Map Internals
Maps are hash tables with 8-entry buckets and overflow chains. They are reference types — assigning a map copies the pointer, not the data.
Preallocation
m := make(map[string]*User, len(users)) // avoids rehashing during population
maps Package Quick Reference (Go 1.21+)
| Function | Purpose |
|---|---|
Collect (1.23+) | Build map from iterator |
Insert (1.23+) | Insert entries from iterator |
All (1.23+) | Iterator over all entries |
Keys, Values | Iterators over keys/values |
For Clone, Equal, sorted iteration → see samber/cc-skills-golang@golang-safety skill.
Map Internals Deep Dive — How Go maps store and hash data, bucket overflow chains, why maps never shrink (and what to do about it), comparing map performance to alternatives.
Arrays
Fixed-size, value types. Copied entirely on assignment. Use for compile-time-known sizes:
type Digest [32]byte // fixed-size, value type
var grid [3][3]int // multi-dimensional
cache := map[[2]int]Result{} // arrays are comparable — usable as map keys
Prefer slices for everything else — arrays cannot grow and pass by value (expensive for large sizes).
container/ Standard Library
| Package | Data Structure | Best For |
|---|---|---|
container/list | Doubly-linked list | LRU caches, frequent middle insertion/removal |
container/heap | Min-heap (priority queue) | Top-K, scheduling, Dijkstra |
container/ring | Circular buffer | Rolling windows, round-robin |
bufio | Buffered reader/writer/scanner | Efficient I/O with small reads/writes |
Container types use any (no type safety) — consider generic wrappers. Container Patterns, bufio, and Examples — When to use each container type, generic wrappers to add type safety, and bufio patterns for efficient I/O.
strings.Builder vs bytes.Buffer
Use `s
Read the complete source ↗