Notes - Ashwin Gopalsamy

Go Error Wrapping Patterns

hi@ashwingopalsamy.in (Ashwin Gopalsamy) — Sat, 28 Mar 2026 00:00:00 +0000

The fmt.Errorf("context: %w", err) pattern is the standard way to add context to errors in Go. But there are nuances worth knowing.

Always wrap with context that answers “what were you trying to do?” not “what went wrong?” The original error already says what went wrong.

Bad: fmt.Errorf("error: %w", err) Good: fmt.Errorf("parsing field DE%d: %w", fieldNum, err)

Why slog Over zerolog

hi@ashwingopalsamy.in (Ashwin Gopalsamy) — Tue, 10 Mar 2026 00:00:00 +0000

Go 1.21 introduced log/slog in the standard library. For new projects, I now default to slog over zerolog.

The API is cleaner, it is part of the standard library (no dependency), and the handler interface makes it trivial to swap backends. The performance gap that once justified zerolog has narrowed significantly.

Go Maps Iteration Order

hi@ashwingopalsamy.in (Ashwin Gopalsamy) — Thu, 25 Dec 2025 00:00:00 +0000

I was working on a minimal word counter. Read from stdin, normalize the input, increment the value for the keys in a map[string]int each time a value is observed.

Irrespective of the order of the input data for a very small unit test-case I created, the output looked sorted. Alphabetically sorted. Clean. Predictable.

I ran it again. Same order. Added more input. Digits. Letters. Mixed tokens.

At that point, my instincts kicked in. Go maps are unordered. I knew that. So why was the output behaving so politely?

The non-negotiable fact

Go maps do not guarantee iteration order. Ever.

The language spec is explicit. Iteration order is not specified and must not be relied upon.

So if the output looks sorted, that is never by intention. It might be an accident. The interesting part is understanding why this accident looks so consistent.

What is actually happening inside a Go map

A Go map is a hash table. Iteration walks buckets in a runtime-defined sequence, not key order.

Important detail: iteration does not mean “pick a random key each time” but rather “walk internal memory structures in a sequence”. This distinction explains everything I had observed.

graph LR subgraph "Hash Function" H["hash(key)"] end K1["a"] --> H K2["b"] --> H K3["m"] --> H K4["1"] --> H H --> B0["Bucket 0
1"] H --> B1["Bucket 1
2"] H --> B3["Bucket 3
a"] H --> B4["Bucket 4
b"] H --> B6["Bucket 6
m"] style H fill:#6366f1,color:#fff,stroke:none style B0 fill:#374151,color:#fff,stroke:none style B1 fill:#374151,color:#fff,stroke:none style B3 fill:#374151,color:#fff,stroke:none style B4 fill:#374151,color:#fff,stroke:none style B6 fill:#374151,color:#fff,stroke:none

Why the output looked sorted

The experiment had a very specific shape:

Small number of keys
Short ASCII strings
No map resizing during insertion

Under these conditions, hash values distribute nicely across buckets, and buckets are laid out in memory in a way that often correlates with lexical order.

Not because Go sorts anything. Because the bucket layout ends up looking sorted by coincidence.

Unspecified order can still be stable and repeatable.

A simplified mental model

This is not how Go maps are implemented exactly, but it explains the behavior well enough:

Input keys:  a   b   m   x   y   z   1   2   9

Hashing step:
a -> bucket 3    x -> bucket 9
b -> bucket 4    y -> bucket 10
m -> bucket 6    z -> bucket 11
1 -> bucket 0    2 -> bucket 1    9 -> bucket 2

Buckets in memory order:
[0] [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11]
 1   2   9   a   b       m           x    y    z

Iteration walks buckets left to right:
1 2 9 a b m x y z

Digits first. Then letters. Within each group, alphabetical-looking order. No sorting happened. Iteration just walked buckets in memory order.

Change the input distribution, force collisions, trigger a map resize, or run on a different Go version, and this illusion will break instantly.

graph TD S["Small ASCII key set"] L["Large / diverse key set"] S --> |"hash values spread
neatly across buckets"| O1["Appears sorted
(coincidence)"] L --> |"collisions, resizing,
overflow buckets"| O2["Visibly unordered
(reality)"] style S fill:#f59e0b,color:#fff,stroke:none style L fill:#374151,color:#fff,stroke:none style O1 fill:#ef4444,color:#fff,stroke:none style O2 fill:#374151,color:#fff,stroke:none

Why the order kept changing as you inserted new keys

When you print the map after each insertion, you see the output “reorder itself.” That was not reordering. What happened was:

A new key landed in an earlier bucket
Iteration still walked buckets from the start
The newly populated bucket now appeared earlier in output

This is why adding "0" suddenly made it appear before "1" through "z".

We can’t really inspect map internals

Go does not allow reliable inspection of map internals. The language specification does not define the memory layout of maps at all. Bucket structure, hash seeds, overflow handling and growth strategy live entirely inside the runtime and are treated as implementation details. They are free to change between Go versions, and they do.

On top of that, map elements are allowed to move in memory when the map grows. This is why Go explicitly disallows taking the address of a map element. Any address you observe today could become invalid tomorrow, even within the same program execution.

As Keith Randall explains in his deep dive into Go maps, this movement happens incrementally during normal map operations, which makes layout and addresses fundamentally unstable by design.

You can technically poke around using unsafe, but that immediately ties your understanding to a specific Go version and runtime implementation. It is educational at best and misleading at worst.

★

Deterministic-looking behavior does not imply guarantees. This is a perfect, low-stakes example of that lesson.

Runes, Bytes, and Graphemes in Go

hi@ashwingopalsamy.in (Ashwin Gopalsamy) — Sat, 09 Aug 2025 00:00:00 +0000

I once ran into this problem of differentiating runes, bytes and graphemes while handling names in Tamil and emoji in a Go web app: a string that looked short wasn’t, and reversing it produced gibberish. The culprit wasn’t Go being flawed, it was me making assumptions about what “a character” means.

Let’s map the territory precisely.

graph TD G["Grapheme Cluster
(what users see)"] R1["Rune 1
(code point)"] R2["Rune 2
(combining mark)"] B1["Bytes
(1-4 per rune)"] B2["Bytes
(1-4 per rune)"] G --> R1 G --> R2 R1 --> B1 R2 --> B2 style G fill:#374151,color:#fff,stroke:none style R1 fill:#6366f1,color:#fff,stroke:none style R2 fill:#6366f1,color:#fff,stroke:none style B1 fill:#64748b,color:#fff,stroke:none style B2 fill:#64748b,color:#fff,stroke:none

1. Bytes: the raw material Go calls a string

Go represents strings as immutable UTF-8 byte sequences. What we see isn’t what Go handles under the hood.

s := "வணக்கம்"
fmt.Println(len(s)) // 21

The length is 21 bytes, not visible symbols. Every Tamil character can span 3 bytes. Even simple-looking emojis stretch across multiple bytes.

2. Runes: Unicode code points

string to []rune gives you code points, but still not what a human perceives.

rs := []rune(s)
fmt.Println(len(rs)) // 7

Here it’s 7 runes, but some Tamil graphemes (like “க்”) combine two runes: க + ்.

3. Grapheme clusters: the units users actually see

Go’s standard library stops at runes. To work with visible characters, you need a grapheme-aware library like github.com/rivo/uniseg.

for gr := uniseg.NewGraphemes(s); gr.Next(); {
    fmt.Printf("%q\n", gr.Str())
}

That outputs what a human reads: “வ”, “ண”, “க்”, “க”, “ம்”, and even a heart emoji as a single unit.

graph LR T["வணக்கம் (Tamil)"] T --> |"len()"| BY["21 bytes"] T --> |"[]rune"| RU["7 runes"] T --> |"uniseg"| GR["5 graphemes"] style T fill:#374151,color:#fff,stroke:none style BY fill:#ef4444,color:#fff,stroke:none style RU fill:#f59e0b,color:#fff,stroke:none style GR fill:#374151,color:#fff,stroke:none

Why this matters

If your app deals with names, chats, or any multilingual text, indexing by bytes will break things. Counting runes helps but can still split what you intend as one unit. Grapheme-aware operations align with what users actually expect.

Real bugs I’ve seen: Tamil names chopped mid-character, emoji reactions breaking because only one code point was taken.

Quick reference

Task	Approach
Count code points	`utf8.RuneCountInString(s)`
Count visible units	Grapheme iteration (`uniseg`)
Reverse text	Parse into graphemes, reverse slice, join
Slice safely	Only use `s[i:j]` on grapheme boundaries

Think about what you intend to manipulate: the raw bytes, the code points, or what a user actually reads on screen, and choose the right level.