Maps, and why iteration order is random on purpose

A Go map is a hash table with typed keys and typed values. It is the closest thing Go has to a JavaScript object used as a dictionary, and it differs in four ways that each cause a specific bug the first time you meet them.

Declaring and using

ages := map[string]int{
    "ada":   36,
    "grace": 45,
}

ages["alan"] = 41
fmt.Println(ages["ada"])    // 36
fmt.Println(len(ages))      // 3
delete(ages, "alan")

The type is map[KeyType]ValueType. Keys must be comparable, so strings, ints, booleans and structs of those are fine; slices, maps and functions are not.

var m map[string]int      // nil
fmt.Println(m["a"])       // 0, fine
fmt.Println(len(m))       // 0, fine
m["a"] = 1                // panic: assignment to entry in nil map

Missing keys return the zero value

Reading a key that is not there is not an error. You get the zero value of the value type.

counts := map[string]int{}
fmt.Println(counts["nothing"])   // 0, not undefined
counts["word"]++                 // works: reads 0, writes 1

That last line is why counting in Go is so tidy: no "if the key exists, add one, otherwise set it to one".

To tell "absent" from "present but zero", use the two-value form:

v, ok := ages["nobody"]
if !ok {
    fmt.Println("not in the map")
}

ok is a bool. This is the comma ok idiom, and you will see the same shape for type assertions and channel receives.

Iteration order is deliberately random

for k, v := range ages {
    fmt.Println(k, v)
}

Run that twice and the order differs. This is not an implementation accident that might settle down: the runtime randomises the starting point on purpose, so that code which accidentally depends on order fails immediately and loudly rather than in production two years later when the table grows.

To iterate in a stable order, sort the keys:

keys := make([]string, 0, len(ages))
for k := range ages {
    keys = append(keys, k)
}
slices.Sort(keys)

for _, k := range keys {
    fmt.Println(k, ages[k])
}

Maps are reference types

Passing a map to a function does not copy it. The function can modify the caller's map.

func add(m map[string]int) {
    m["new"] = 1        // visible to the caller
}

This is unlike a struct and unlike an array, and like a slice's elements. There is no const map and no way to pass one read-only. If a function must not modify a map, the only guards are a copy (maps.Clone) or a comment.

Structs as values, and the thing you cannot do

A map of structs has one sharp edge:

type Stat struct{ Count int }
m := map[string]Stat{"a": {Count: 1}}

m["a"].Count++      // compile error: cannot assign to struct field

The map returns a copy of the struct, so incrementing it would modify something about to be discarded, and Go refuses rather than letting you write code that does nothing. Two fixes:

// 1. Read, modify, write back.
s := m["a"]
s.Count++
m["a"] = s

// 2. Store pointers instead.
m := map[string]*Stat{"a": {Count: 1}}
m["a"].Count++      // fine

The second is usually what you want when the values are large or frequently updated. The first is fine for small structs and avoids a layer of indirection.

Sets

Go has no set type. The idiom is a map with an empty struct value:

seen := map[string]struct{}{}
seen["ada"] = struct{}{}

if _, ok := seen["ada"]; ok {
    fmt.Println("already seen")
}

struct{} is a struct with no fields and it occupies zero bytes, so the map stores only keys. Using map[string]bool is also common and slightly more readable at the cost of one byte per entry; both are accepted Go.

Maps are not safe for concurrent use

Two goroutines writing to the same map at the same time will crash the program with a runtime error, deliberately. Go detects it and stops rather than corrupting the table silently.

The answer is usually a mutex, which is chapter fifteen:

type Counter struct {
    mu     sync.Mutex
    counts map[string]int
}

func (c *Counter) Inc(key string) {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.counts[key]++
}

package main

import (
    "bufio"
    "fmt"
    "os"
    "slices"
    "strings"
)

func main() {
    if len(os.Args) < 2 {
        fmt.Fprintln(os.Stderr, "usage: index <file>")
        os.Exit(1)
    }

    f, err := os.Open(os.Args[1])
    if err != nil {
        fmt.Fprintln(os.Stderr, "error:", err)
        os.Exit(1)
    }
    defer f.Close()

    index := map[string][]int{}

    scanner := bufio.NewScanner(f)
    line := 0
    for scanner.Scan() {
        line++
        for _, w := range strings.Fields(scanner.Text()) {
            w = strings.ToLower(strings.Trim(w, ".,!?;:\"'()"))
            if len(w) < 4 {
                continue    // skip short words
            }
            // Appending to a nil slice works, so no "if absent" branch.
            if !slices.Contains(index[w], line) {
                index[w] = append(index[w], line)
            }
        }
    }
    if err := scanner.Err(); err != nil {
        fmt.Fprintln(os.Stderr, "reading:", err)
        os.Exit(1)
    }

    words := make([]string, 0, len(index))
    for w := range index {
        words = append(words, w)
    }
    slices.Sort(words)

    for _, w := range words {
        if len(index[w]) > 2 {   // only words on three or more lines
            fmt.Printf("%-16s %v\n", w, index[w])
        }
    }
}

Assignment

Commit your work with the message Maps - Assignment One, exactly as written, so the leaderboard can score it.