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

samber/cc-skills-golang@golang-concurrency

samber/cc-skills-golang@golang-design-patterns

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

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

Clone

Equal

DeleteFunc

samber/cc-skills-golang@golang-safety

Slice Internals Deep Dive — Full

slices

len

cap

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+)

Collect

Insert

All

Keys

Values

For

Clone

Equal

samber/cc-skills-golang@golang-safety

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

container/list

container/heap

container/ring

bufio

Container types use

any

bufio

strings.Builder vs bytes.Buffer

Use

strings.Builder

String()

bytes.Buffer

io.Reader

Grow(n)

Generic Collections (Go 1.18+)

Use the tightest constraint possible.

comparable

cmp.Ordered

type Set[T comparable] map[T]struct{}

func (s Set[T]) Add(v T)          { s[v] = struct{}{} }
func (s Set[T]) Contains(v T) bool { _, ok := s[v]; return ok }

Writing Generic Data Structures — Using Go 1.18+ generics for type-safe containers, understanding constraint satisfaction, and building domain-specific generic types.

Pointer Types

*T

nil

unsafe.Pointer

nil

weak.Pointer[T]

Pointer Types Deep Dive — Normal pointers,

unsafe.Pointer

weak.Pointer[T]

Copy Semantics Quick Reference

int

float

bool

string

array

struct

slice

slices.Clone

map

maps.Clone

channel

*T

interface

Third-Party Libraries

For advanced data structures (trees, sets, queues, stacks) beyond the standard library:

• emirpasic/gods

  — comprehensive collection library (trees, sets, lists, stacks, maps, queues)

• deckarep/golang-set

  — thread-safe and non-thread-safe set implementations

• gammazero/deque

  — fast double-ended queue

When using third-party libraries, refer to their official documentation and code examples for current API signatures. Context7 can help as a discoverability platform.

Cross-References

• → See

  samber/cc-skills-golang@golang-performance

  skill for struct field alignment, memory layout optimization, and cache locality
• → See

  samber/cc-skills-golang@golang-safety

  skill for nil map/slice pitfalls, append aliasing, defensive copying,

  slices.Clone

  /

  Equal

• → See

  samber/cc-skills-golang@golang-concurrency

  skill for channels,

  sync.Map

  ,

  sync.Pool

  , and all sync primitives
• → See

  samber/cc-skills-golang@golang-design-patterns

  skill for

  string

  vs

  []byte

  vs

  []rune

  , iterators, streaming
• → See

  samber/cc-skills-golang@golang-structs-interfaces

  skill for struct composition, embedding, and generics vs

  any

• → See

  samber/cc-skills-golang@golang-code-style

  skill for slice/map initialization style

Common Mistakes

make([]T, 0, n)

slices.Grow

container/list

bytes.Buffer

String()

strings.Builder

unsafe.Pointer

uintptr

uintptr

map[K]*V

References

• Go Data Structures (Russ Cox)
• The Go Memory Model
• Effective Go