Advanced Map Usage

Once you can read, write, and iterate over a map, you have the fundamentals. But many real problems call for patterns that go beyond the basics. This page covers four advanced techniques: using a map to represent a set of unique items, choosing keys that are more interesting than simple strings or numbers, the maps standard library package that arrived in Go 1.21, and the rules that keep maps safe when multiple goroutines are involved.

Maps as Sets

Go does not include a dedicated set type. The closest and most idiomatic replacement is a map whose values signal membership. Since map keys must be unique, checking whether an item belongs to the set reduces to an ordinary key lookup — a constant‑time operation.

The zero‑value approach with bool

A map[T]bool is the most direct mapping of the set idea. For any key that is a member, store true. When you read a key that has never been written, the map returns the zero value of bool, which is false. That lets you test membership without calling the two‑value comma‑ok form.

visited := make(map[string]bool)
visited["home"] = true
visited["about"] = true
if visited["home"] {
    fmt.Println("home was visited")   // prints
}
if visited["contact"] {
    fmt.Println("contact was visited") // never runs — zero value is false
}

If you delete a member, use delete(visited, "home") rather than setting the value to false. Leaving an explicit false entry means the key still exists, which makes len(visited) misleading. The deletion approach keeps the map clean.

The zero‑allocation approach with struct{}

A map[T]struct{} uses no storage for the value — an empty struct occupies zero bytes. The trade‑off is that you must use the two‑value lookup to test membership because you cannot compare struct{} to anything meaningful in an if.

set := make(map[string]struct{})
set["apple"] = struct{}{}
set["banana"] = struct{}{}
if _, ok := set["apple"]; ok {
    fmt.Println("apple is in the set")
}
// Compile error — you cannot test a struct{} as a boolean:
// if set["apple"] { … }

The struct{} pattern is common in library code and whenever memory efficiency matters. For quick scripts, map[T]bool is often clearer and perfectly adequate.

A practical example: detecting cycles

A map used as a set can track items you have already seen. The classic illustration from the Go blog detects a cycle in a linked list by storing visited node pointers.

type Node struct {
    Next  *Node
    Value any
}
func hasCycle(start *Node) bool {
    seen := make(map[*Node]bool)
    for n := start; n != nil; n = n.Next {
        if seen[n] {
            return true
        }
        seen[n] = true
    }
    return false
}

The zero value of bool means a never‑before‑seen node automatically returns false; no explicit existence check is needed.

Maps with Struct or Interface Keys

A map key can be any type that supports == and !=. Numbers, strings, pointers, channels, and interfaces are all comparable, as are structs and arrays whose fields are themselves comparable. This flexibility means you can use a composite key instead of nesting maps inside maps.

Struct keys for multi‑dimensional lookups

Imagine counting page hits per country. Without struct keys you might write a nested map:

hits := make(map[string]map[string]int)
// Increment a hit from Australia on the /doc/ page:
mm, ok := hits["/doc/"]
if !ok {
    mm = make(map[string]int)
    hits["/doc/"] = mm
}
mm["au"]++

The outer map must be checked and initialised for every new path. With a struct key the whole operation becomes a single line.

type Key struct {
    Path    string
    Country string
}
hits := make(map[Key]int)
hits[Key{"/doc/", "au"}]++   // no nested checks

Go compares structs field by field, so Key{"/doc/", "au"} and Key{"/doc/", "au"} are equal. This pattern works for any number of dimensions and keeps the code flat and readable.

Interface keys and the hidden runtime panic

An interface value can be used as a key, but only if the dynamic type stored inside the interface is comparable. The compiler cannot always check this at build time, so a map with interface keys will compile — and then panic at runtime if you ever insert a non‑comparable value, such as a slice.

m := make(map[any]int)
m["hello"] = 1           // fine: string is comparable
m[[]int{1, 2}] = 2       // runtime panic: slice is not comparable

The panic occurs on the write, not on the read. Interface keys are most useful when you control the types being stored — for example, in a generic cache where you know all callers pass comparable values. When that guarantee is absent, prefer a concrete key type or use a hashing mechanism that avoids the == comparison altogether.

The maps Standard Library Package

Starting with Go 1.21, the standard library ships the maps package — a collection of generic functions that cover operations developers previously had to write by hand. It removes boilerplate, reduces mistakes, and makes intent explicit.

Clone

maps.Clone creates a shallow copy of a map. The new map has the same keys and values as the original, but the two maps are independent — adding or deleting from one does not affect the other.

import "maps"
original := map[string]int{"a": 1, "b": 2}
duplicate := maps.Clone(original)
duplicate["c"] = 3
fmt.Println(original)   // map[a:1 b:2]  — unchanged
fmt.Println(duplicate)  // map[a:1 b:2 c:3]

A shallow copy means the values themselves are not deep‑cloned. If the values are pointers, both maps point to the same underlying objects. That matches Go’s normal assignment semantics and is almost always what you want.

Copy

maps.Copy copies every key‑value pair from a source map into a destination map. Existing keys in the destination are overwritten.

dest := map[string]int{"x": 10}
src  := map[string]int{"x": 20, "y": 30}
maps.Copy(dest, src)
// dest is now map[x:20 y:30]

Copy does not clear the destination first; keys that exist only in the destination remain untouched.

DeleteFunc

maps.DeleteFunc removes entries for which a predicate returns true. It is especially useful for cleaning a map based on the value.

scores := map[string]int{"alice": 91, "bob": 55, "carol": 72}
maps.DeleteFunc(scores, func(name string, score int) bool {
    return score < 60
})
// scores is now map[alice:91 carol:72]

Equal and EqualFunc

maps.Equal checks whether two maps have the same length and whether every key‑value pair is identical using ==. maps.EqualFunc does the same but uses a caller‑supplied comparison function, which is required when the value type is not comparable with == (for example, a slice value).

m1 := map[string][]int{"a": {1, 2}}
m2 := map[string][]int{"a": {1, 2}}
// maps.Equal(m1, m2) — compile error: []int is not comparable
equal := maps.EqualFunc(m1, m2, func(a, b []int) bool {
    return slices.Equal(a, b)   // Go 1.21+ slices package
})
fmt.Println(equal) // true

These functions replace ad‑hoc reflection‑based comparisons that were fragile and slow.

Concurrency Safety of Maps

A map is not safe for simultaneous reads and writes. If one goroutine modifies the map while another is reading or writing it, the runtime can panic with a fatal “concurrent map read and map write” error. Even when no panic occurs, the result is undefined — lost updates, corrupted internal state, or values that appear only intermittently.

Protecting a map with sync.RWMutex

The most common protection mechanism is a sync.RWMutex embedded alongside the map. Readers acquire the read lock, allowing multiple readers to proceed concurrently. Writers acquire the exclusive write lock, blocking all other access.

var visits = struct {
    sync.RWMutex
    m map[string]int
}{m: make(map[string]int)}
// Reader
visits.RLock()
count := visits.m["home"]
visits.RUnlock()
// Writer
visits.Lock()
visits.m["home"]++
visits.Unlock()

The embedded struct groups the lock and the map it protects, making it clear they belong together and preventing accidental copy of the mutex.

When sync.Map is the right choice

The standard library also provides sync.Map, a concurrent map with a different trade‑off. It is not a general‑purpose replacement for a regular map. It performs well when:

• Most operations read keys that are set once and then rarely changed, or
• Many goroutines read, write, and iterate over largely disjoint sets of keys.

In those scenarios the overhead of a full RWMutex can be eliminated. For most other workloads — especially when the map changes frequently across all keys — a regular map behind an RWMutex is simpler and faster.

var sm sync.Map
sm.Store("key", 10)
if v, ok := sm.Load("key"); ok {
    fmt.Println(v.(int))  // type assertion needed
}

The sync.Map API uses any typed values, so you lose compile‑time type safety. That alone is reason to reach for it only when profiling shows a genuine bottleneck.

The nil‑map danger, amplified by concurrency

A nil map behaves like an empty map when reading, but any write to it — including increment — panics. That rule still applies when a mutex is involved, because the mutex only serialises access; it does not initialise the map.

var unsafe struct {
    sync.RWMutex
    m map[string]int   // nil map — not initialised
}
unsafe.Lock()
unsafe.m["x"] = 1     // panic: assignment to entry in nil map
unsafe.Unlock()

Always call make when you create the map that lives behind a mutex. The embedded literal {m: make(map[string]int)} shown earlier is a reliable pattern.

Summary

When a basic key‑value lookup stops being enough, the patterns in this section give you a path forward. A map masquerading as a set eliminates duplicate tracking code. Struct keys flatten nested maps into a single, straightforward index. The maps package standardises cloning, copying, filtering, and comparison so you spend fewer lines on boilerplate. And when concurrency enters the picture, an RWMutex — or, in specific cases, a sync.Map — keeps the runtime from ever seeing a race it cannot handle.

What connects all these techniques is that they build on the same map[K]V you already know. There is no special variant, no hidden compiler mode. Once you understand the comparability rules for keys and the synchronisation rules for goroutines, you can adapt maps to almost any shape your data requires.