Solizardking/clawd-bot / .agents/skills/golang-data-structures
golang-data-structures
VerifiedGolang 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.2 KB |
| evals/evals.json | config | 19.6 KB |
| references/containers.md | markdown | 4.0 KB |
| references/generics.md | markdown | 2.5 KB |
| references/map-internals.md | markdown | 2.5 KB |
| references/pointers.md | markdown | 3.5 KB |
| references/slice-internals.md | markdown | 1.9 KB |
references/map-internals.md
View on GitHub# Map Internals Deep Dive
## Hash Table Structure
Go maps use hash tables with bucket-based collision resolution. The map header holds:
- `count` — number of entries
- `B` — log₂ of bucket count (2^B buckets total)
- `buckets` — pointer to bucket array
- `oldbuckets` — pointer to old buckets during growth
Each bucket holds 8 key-value pairs. Keys and values are stored in separate arrays within buckets to minimize padding waste.
## Memory Growth and Capacity
- **Load factor threshold**: 6.5 entries per bucket triggers growth (sweet spot between memory efficiency and collision performance)
- **Overflow bucket chains** also trigger growth if too long (prevents O(1)→O(n) degradation)
- **Bucket count doubles**: 2^B → 2^(B+1) (efficient rehashing with powers of 2)
- **Incremental evacuation**: Old and new buckets coexist during growth; entries move lazily during operations to avoid GC pauses
- **No `cap()` function**: Capacity depends on hash distribution and load factor, not a fixed limit. Preallocation (`make(map[string]int, expectedSize)`) is worthwhile for large maps to avoid repeated growth cycles
## Preallocation
```go
// Without preallocation — multiple growths as entries are added
m := map[string]int{}
// With preallocation — allocates enough buckets upfront
m := make(map[string]int, expectedSize)
```
Preallocation avoids repeated growths. The hint is approximate — Go allocates 2^B buckets where 2^B \* 6.5 >= hint.
## Pointers vs Values
For large value types, storing pointers reduces copy overhead:
```go
// Large struct — copied on every read/write
m := map[string]BigStruct{} // copies large struct
// Pointer — only pointer is copied
m := map[string]*BigStruct{} // copies 8-byte pointer
```
Trade-off: pointer maps add GC pressure. For small structs (< 128 bytes), value maps are typically faster.
## `maps` Package (Go 1.21+)
| Function | Description |
| --- | --- |
| `Clone`, `Equal`, `EqualFunc` | Shallow copy and equality comparison |
| `Keys`, `Values`, `All` (1.23+) | Iterators over keys, values, or pairs |
| `Collect`, `Insert` (1.23+) | Build maps from iterators or insert entries |
See `samber/cc-skills-golang@golang-safety` skill for `Clone`, `Equal`, and sorted iteration patterns.
## Map Key Requirements
Map keys must be comparable (`==` must work). This includes:
- All numeric types, `string`, `bool`
- Pointers, channels, interfaces (compared by identity)
- Arrays of comparable types
- Structs where all fields are comparable
Slices, maps, and functions **cannot** be map keys.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |