go-data-structures

Files (2)

• SKILL.md
• containers.md · references/

SKILL.md (first lines)

# Go Data Structures

Slices and maps look simple and hide the sharpest edges in the language.
These rules prevent the aliasing, nil, and iteration bugs that survive
code review.

Detailed reference material, loaded on demand:

- `references/containers.md` — `container/heap` priority queue, LRU with
  `container/list`, reclaiming map memory, a `weak.Pointer` cache.

Read a reference file only when the summary below is not enough.

## 1. Nil Slice vs Empty Slice

```go
var a []int          // nil slice — len 0, cap 0, no allocation
b := []int{}         // empty slice — len 0, allocated header
c := make([]int, 0)  // empty slice — same as b
```

- `len`, `cap`, `range`, and `append` treat all three identically.
- **Prefer the nil slice** as the "no elements" value; don't allocate
  just to return "empty".
- Exception: JSON. With `encoding/json`, `nil` marshals to `null` and empty
  to `[]`; if the contract requires `[]`, return an empty slice. The Go
  1.27 `encoding/json/v2` API marshals nil as `[]` by default.
- Never distinguish nil from empty in logic — check `len(s) == 0`.

## 2. Append Semantics and Aliasing

`append` MAY return the same backing array or a new one. Both cases
bite:

```go
// ❌ Bad — result may alias the input
func addSuffix(base []string) []string {
    return append(base, "suffix") // if cap(base) > len(base),
}                                 // this WRITES INTO base's array

// ✅ Good — force a copy when the input must not be touched
func addSuffix(base []string) []string {
    out := make([]string, len(base), len(base)+1)
    copy(out, base)
    return append(out, "suffix")
}
```

```go
// ❌ Bad — subslice keeps the whole 64 MB alive
func header(big []byte) []byte {
    return big[:512] // backing array is still the full big
}

// ✅ Good — copy the window you keep
func header(big []byte) []byte {
    return slices.Clone(big[:512]) // Go 1.21+; or copy() manually
}
```

Rule: a function either owns a slice or copies it. Returning a subslice
of a caller's slice, or appending to one, silently shares memory.

## 3. Preallocation

When the final size is known or bounded, allocate once:

```go
// ✅ Good — one allocation
names := make([]string, 0, len(users))
for _, u := range users {
    names = append(names, u.Name)
}

// ❌ Bad — repeated growth and copying
var names []string
for _, u := range users {
    names = append(names, u.Name)
}
```

Same for maps: `make(map[string]int, len(items))`.
Don't preallocate when the size is unknown — a wrong large cap wastes
memory; `append` growth is fine for cold paths.

## 4. Map Essentials

```go
// Comma-ok distinguishes "missing" from "zero value"
count, ok := hits[key]
if !ok { /* key absent */ }

// Zero value reads are safe; writes to a nil map PANIC
var m map[string]int
_ = m["x"]      // 0, fine
m["x"] = 1      // panic: assignment to entry in nil map — make() first

// Iteration order is RANDOM and differs between runs.
// Sort keys when output must be deterministic:
keys := slices.Sorted(maps.Keys(m)) // Go 1.23+
for _, k := range keys {
    fmt.Println(k, m[k])
}
```

- Map values are not addressable: `m[k].Field = v` doesn't compile for
  struct values. Use a map of pointers, or read-modify-write.
- Deleting during `range` is safe; inserting during `range` is
  unspecified (the new key may or may not be visited).

## 5. Sets

The idiomatic set is a map with empty-struct values:

```go
seen := make(map[string]struct{}, len(items))
for _, it := range items {
    if _, dup := seen[it.ID]; dup {
        continue

From eduardo-sl/go-agent-skills, MIT.

More from eduardo-sl/go-agent-skills