go-data-structures

Go Data Structures

Resource Routing

references/SLICES.md - Read when deciding nil versus empty slices, copying slices, or managing slice capacity and aliasing.

Choosing a Data Structure

What do you need?
├─ Ordered collection of items
│  ├─ Fixed size known at compile time → Array [N]T
│  └─ Dynamic size → Slice []T
│     ├─ Know approximate size? → make([]T, 0, capacity)
│     └─ Unknown size or nil-safe for JSON? → var s []T (nil)
├─ Key-value lookup
│  └─ Map map[K]V
│     ├─ Know approximate size? → make(map[K]V, capacity)
│     └─ Need a set? → map[T]struct{} (zero-size values)
└─ Need to pass to a function?
   └─ Copy at the boundary if the caller might mutate it

When this skill does NOT apply: For concurrent access to data structures (mutexes, atomic operations), see go-concurrency. For defensive copying at API boundaries, see go-defensive. For pre-sizing capacity for performance, see go-performance.

Slices

The append Function

Always assign the result — the underlying array may change:

Two-Dimensional Slices

Independent inner slices (can grow/shrink independently):

Single allocation (more efficient for fixed sizes):

Declaring Empty Slices

Prefer nil slices over empty literals:

Both have len and cap of zero, but the nil slice is the preferred style.

Exception for JSON: A nil slice encodes to null, while []string{} encodes to []. Use non-nil when you need a JSON array.

When designing interfaces, avoid distinguishing between nil and non-nil zero-length slices.

Maps

Implementing a Set

Use map[T]struct{} when the map is only a set. The empty struct takes no storage and makes membership intent explicit:

Use boolean map values only when the value carries a separate meaning beyond presence.

Copying

Be careful when copying a struct from another package. If the type has methods on its pointer type (*T), copying the value can cause aliasing bugs.

General rule: Do not copy a value of type T if its methods are associated with the pointer type *T. This applies to bytes.Buffer, sync.Mutex, sync.WaitGroup, and types containing them.

Quick Reference

Topic	Key Point
Slices	Always assign `append` result; `nil` slice preferred over `[]T{}`
Sets	`map[T]struct{}` for membership-only sets
Copying	Don't copy `T` if methods are on `*T`; beware aliasing

Defensive copying: See go-defensive when copying slices or maps at API boundaries to prevent mutation
Capacity hints: See go-performance when pre-sizing slices or maps for known workloads
Iteration patterns: See go-control-flow when using range loops over slices, maps, or channels
Declaration style: See go-declarations when choosing between new, make, var, and composite literals