Subscribe

Golang Tutorial 9: Arrays and slices

Arrays vs slices in Go, length and capacity, the append gotcha that overwrote my data, copy, and the slices package (Sort, Contains, Index, BinarySearch). Runnable examples on Go 1.27 and a small exercise at the end.

Golang Tutorial 9: Arrays and slices

The Golang tutorial series on this blog stopped at Tutorial 8 on concurrency, and it skipped a few things every Go program uses. Slices are the biggest one. In this blog we will look at arrays, slices, length and capacity, the append gotcha that bites almost everyone once, copy, and the slices package. Level: beginner. You need Go installed (Tutorial 2 covers the setup) and you should be fine with loops from Tutorial 5.

I ran every example here on Go 1.27.3 on my Mac. The latest patch release is 1.27.4, but nothing in this post changes between the two.

Setting up

Each example is a small main package in its own folder inside one module, so you can run them one by one.

mkdir slicesdemo && cd slicesdemo
go mod init example.com/slicesdemo
mkdir arrays lencap gotcha copyslice slicespkg nilempty exercise

Then put each file below in its folder and run it with go run ./arrays, go run ./lencap and so on.

Arrays first

An array in Go has a fixed length, and the length is part of the type. [3]int and [4]int are two different types. You will rarely write arrays directly, but slices are built on top of them, so it's worth five minutes.

package main

import "fmt"

func double(nums [3]int) {
    for i := range nums {
        nums[i] *= 2
    }
    fmt.Println("inside double:", nums)
}

func main() {
    var scores [3]int
    fmt.Println(scores, len(scores))

    primes := [5]int{2, 3, 5, 7, 11}
    days := [...]string{"Mon", "Tue", "Wed"}
    fmt.Println(primes, days, len(days))

    a := [3]int{1, 2, 3}
    b := a // b is a full copy
    b[0] = 100
    fmt.Println("a:", a, "b:", b)

    double(a)
    fmt.Println("after double:", a)

    fmt.Println("equal?", a == [3]int{1, 2, 3})
}
[0 0 0] 3
[2 3 5 7 11] [Mon Tue Wed] 3
a: [1 2 3] b: [100 2 3]
inside double: [2 4 6]
after double: [1 2 3]
equal? true

Two things to notice. An array is a value: assigning it or passing it to a function copies every element, so double changed its own copy and a stayed the same. And arrays of comparable things can be compared with ==. Slices can't, which we'll get to.

[...] just asks the compiler to count the elements for you.

Slices, length and capacity

A slice is a small header with three fields: a pointer into an array (the backing array), a length and a capacity. Length is how many elements you can see. Capacity is how many there are from the start of the slice to the end of the backing array.

package main

import "fmt"

func main() {
    nums := []int{10, 20, 30, 40, 50}
    part := nums[1:3]
    fmt.Println(part, "len", len(part), "cap", cap(part))

    buf := make([]int, 0, 4)
    fmt.Println(buf, "len", len(buf), "cap", cap(buf))

    var s []int
    prev := cap(s)
    for i := range 2000 {
        s = append(s, i)
        if cap(s) != prev {
            fmt.Printf("len %4d  cap %4d -> %4d\n", len(s), prev, cap(s))
            prev = cap(s)
        }
    }
}
[20 30] len 2 cap 4
[] len 0 cap 4
len    1  cap    0 ->    4
len    5  cap    4 ->    8
len    9  cap    8 ->   16
len   17  cap   16 ->   32
len   33  cap   32 ->   64
len   65  cap   64 ->  128
len  129  cap  128 ->  256
len  257  cap  256 ->  512
len  513  cap  512 ->  848
len  849  cap  848 -> 1280
len 1281  cap 1280 -> 1792
len 1793  cap 1792 -> 2560

nums[1:3] gives elements 1 and 2, so the length is 2. The capacity is 4 because there are four elements from index 1 to the end of nums.

The growth loop surprised me a bit. I expected the first append to give capacity of 1, then 2, then 4, the way older blog posts show it. On Go 1.27.3 the very first append jumped straight to 4. After that it doubles until 512 and then grows by smaller steps (848, 1280...), because the runtime switches to a gentler growth factor for big slices and rounds up to its memory size classes. Don't write code that depends on these exact numbers. They have changed between Go versions before and they will change again.

What you can depend on is this: when append runs out of capacity it allocates a new, bigger backing array and copies everything over. That's why you must always use the result, s = append(s, x).

If you know size up front, make([]int, 0, n) gives you the capacity in one allocation. I do this a lot when converting one slice into another of the same length.

The append gotcha

This is the one that bites. A slice made from another slice shares its backing array. If the small slice still has spare capacity, append writes into that shared array instead of making a new one.

package main

import (
    "fmt"
    "slices"
)

func main() {
    all := []string{"a", "b", "c", "d"}
    first := all[:2]
    first = append(first, "X")
    fmt.Println("all:  ", all)
    fmt.Println("first:", first)

    // Fix 1: full slice expression caps the capacity.
    all = []string{"a", "b", "c", "d"}
    safe := all[:2:2]
    safe = append(safe, "X")
    fmt.Println("all:  ", all, "safe:", safe)

    // Fix 2: clone before you change it.
    all = []string{"a", "b", "c", "d"}
    own := slices.Clone(all[:2])
    own = append(own, "X")
    fmt.Println("all:  ", all, "own: ", own)

    // The other half of the gotcha: append inside a function.
    tags := make([]string, 0, 10)
    addTag(tags, "go")
    fmt.Println("tags after addTag:", tags, len(tags))
    tags = addTagFixed(tags, "go")
    fmt.Println("tags after addTagFixed:", tags, len(tags))
}

func addTag(tags []string, t string) {
    tags = append(tags, t)
}

func addTagFixed(tags []string, t string) []string {
    return append(tags, t)
}
all:   [a b X d]
first: [a b X]
all:   [a b c d] safe: [a b X]
all:   [a b c d] own:  [a b X]
tags after addTag: [] 0
tags after addTagFixed: [go] 1

Look at the first line. We appended to first and the "c" in all became "X". No error, no warning. In a real program this shows up as data that changes "by itself" somewhere far away from the append. The bug is quiet, which is what makes it nasty.

There are two fixes. The full slice expression all[:2:2] sets the capacity to 2 as well as the length, so the next append has no room and must copy. Or slices.Clone gives you a fresh backing array straight away. I reach for Clone when I'm going to keep the slice around, and [:n:n] when I return a sub-slice from a function and don't want callers to be able to write past it.

The second half is just as common. addTag appends to its own copy of the slice header. The element did land in the backing array (capacity was 10), but the caller's header still says length 0, so it never sees it. Return the new slice and let the caller assign it, like append itself does.

Copying with copy

copy(dst, src) copies min(len(dst), len(src)) elements and returns how many it copied. It never grows dst.

package main

import "fmt"

func main() {
    src := []int{1, 2, 3, 4, 5}
    dst := make([]int, 3)
    n := copy(dst, src)
    fmt.Println("copied", n, "dst", dst)

    // copy works on overlapping slices too: shift left by one
    copy(src, src[1:])
    src = src[:len(src)-1]
    fmt.Println("shifted", src)

    var empty []int
    fmt.Println("copy into nil:", copy(empty, src))
}
copied 3 dst [1 2 3]
shifted [2 3 4 5]
copy into nil: 0

The last line is the classic beginner mistake: copying into a nil or zero length slice copies nothing. Make dst with the right length first.

The slices package

Since Go 1.21 the standard library has a slices package, and I barely write search or sort loops by hand any more. Here it is on a list of languages and on a small link struct (the kind of thing the URL shortener from the URL shortener design post would keep).

package main

import (
    "cmp"
    "fmt"
    "slices"
    "strings"
)

type link struct {
    Code   string
    Clicks int
}

func main() {
    langs := []string{"python", "go", "rust", "go", "dart"}
    fmt.Println(slices.Contains(langs, "go"), slices.Index(langs, "rust"), slices.Index(langs, "java"))

    slices.Sort(langs)
    fmt.Println(langs)
    langs = slices.Compact(langs)
    fmt.Println(langs)

    i, found := slices.BinarySearch(langs, "python")
    fmt.Println("python at", i, found)

    langs = slices.Insert(langs, 1, "c")
    langs = slices.Delete(langs, 0, 1)
    fmt.Println(langs, slices.Max(langs))

    links := []link{{"abc", 12}, {"xyz", 40}, {"k9", 12}, {"go1", 3}}
    slices.SortFunc(links, func(a, b link) int {
        return cmp.Or(
            cmp.Compare(b.Clicks, a.Clicks), // most clicks first
            strings.Compare(a.Code, b.Code),
        )
    })
    fmt.Println(links)

    idx := slices.IndexFunc(links, func(l link) bool { return l.Clicks < 10 })
    fmt.Println("first under 10 clicks:", idx, links[idx].Code)

    links = slices.DeleteFunc(links, func(l link) bool { return l.Clicks < 10 })
    fmt.Println(len(links), links)
}
true 2 -1
[dart go go python rust]
[dart go python rust]
python at 2 true
[c go python rust] rust
[{xyz 40} {abc 12} {k9 12} {go1 3}]
first under 10 clicks: 3 go1
3 [{xyz 40} {abc 12} {k9 12}]

A few notes from using these.

  • Index returns -1 when the value isn't there, same as strings.Index.
  • Compact only removes duplicates that sit next to each other, so sort first.
  • BinarySearch needs a sorted slice. On an unsorted one it gives you a wrong answer quietly.
  • Insert, Delete, Compact and DeleteFunc return the new slice. Assign it back, just like append.
  • SortFunc takes a compare function that returns negative, zero or positive. cmp.Or returns the first non-zero result, which makes "sort by clicks, then by code" a one liner.

Sorting links by clicks put abc and k9 (both 12) in a fixed order only because of the second compare on Code. Without it the order of equal items isn't guaranteed. Use slices.SortStableFunc if you want equal items to keep their original order.

nil slices, empty slices and 2D slices

A nil slice and an empty slice both have length 0 and both work with append, len and range. The difference shows up when you encode them to JSON.

package main

import (
    "encoding/json"
    "fmt"
)

type resp struct {
    Links []string `json:"links"`
}

func main() {
    var a []string
    b := []string{}
    fmt.Println(a == nil, b == nil, len(a), len(b))

    ja, _ := json.Marshal(resp{Links: a})
    jb, _ := json.Marshal(resp{Links: b})
    fmt.Println(string(ja))
    fmt.Println(string(jb))

    a = append(a, "works on nil too")
    fmt.Println(a)

    grid := make([][]int, 3)
    for i := range grid {
        grid[i] = make([]int, 4)
    }
    grid[1][2] = 7
    for _, row := range grid {
        fmt.Println(row)
    }
}
true false 0 0
{"links":null}
{"links":[]}
[works on nil too]
[0 0 0 0]
[0 0 7 0]
[0 0 0 0]

The null versus [] difference is easy to miss in a code review, because both print as [] with fmt.Println. A JavaScript client doing resp.links.length crashes on null though. If an API returns a list, I start it as []T{} (or make([]T, 0)) so it always encodes as [].

And a slice can only be compared to nil with ==. Anything else is a compile error. To compare two slices use slices.Equal.

For a 2D slice you make the outer slice and then make every row. Forgetting the inner make gives you nil rows and an index out of range panic on the first write.

Exercise

Write a function chunk(s []int, n int) [][]int that splits s into pieces of at most n elements. chunk([]int{1,2,3,4,5,6,7}, 3) should give [[1 2 3] [4 5 6] [7]]. One extra rule: changing a piece must not change the original slice. That rules out just returning s[i:i+n], and after reading the gotcha section you know why.

Try it before you look, here is my version.

package main

import "fmt"

// chunk splits s into pieces of at most n elements.
// The pieces must not share a backing array with s.
func chunk(s []int, n int) [][]int {
    var out [][]int
    for len(s) > 0 {
        end := min(n, len(s))
        piece := make([]int, end)
        copy(piece, s[:end])
        out = append(out, piece)
        s = s[end:]
    }
    return out
}

func main() {
    nums := []int{1, 2, 3, 4, 5, 6, 7}
    parts := chunk(nums, 3)
    fmt.Println(parts)
    parts[0][0] = 99
    fmt.Println(nums)
}
[[1 2 3] [4 5 6] [7]]
[1 2 3 4 5 6 7]

min is a builtin since Go 1.21, so no helper needed. If you want more practice, there is also slices.Chunk, which does the splitting for you but returns sub-slices that share memory with the original. Write a small program that shows that, using what you learned above.

Next in the series is pointers, which explains a lot of what we saw here with slice headers.