Slices em Golang: append, make, len e cap e o bug do compartilhamento

Um slice em um exemplo

Um slice é uma visão expansível sobre um array. Você cria um com um literal ou com make, aumenta com append e lê o tamanho com len.

package main

import "fmt"

func main() {
	langs := []string{"Go", "Rust"}
	langs = append(langs, "Zig", "C")
	fmt.Println(langs, len(langs))

	for i, l := range langs {
		fmt.Println(i, l)
	}

	fmt.Println(langs[1:3]) // elements 1 and 2
}

[]string não tem tamanho entre os colchetes. Essa é a diferença para um tipo array como [4]string, cujo tamanho é fixo.

O que é um slice

Um valor de slice é um cabeçalho pequeno com três campos:

• um ponteiro para um elemento de um array subjacente
• um tamanho (length): quantos elementos o slice enxerga
• uma capacidade (capacity): quantos elementos existem desse ponteiro até o fim do array subjacente

Copiar um slice (atribuí-lo, passá-lo para uma função) copia só esse cabeçalho. As duas cópias apontam para os mesmos elementos. Quase toda surpresa com slices vem de esquecer isso.

make: tamanho e capacidade

make([]T, len, cap) aloca um array subjacente e devolve um slice sobre ele. A capacidade é opcional e, por padrão, é igual ao tamanho.

package main

import "fmt"

func main() {
	a := make([]int, 3) // len 3, cap 3, all zeros
	fmt.Println(a, len(a), cap(a))

	b := make([]int, 0, 10) // len 0, room for 10
	fmt.Println(b, len(b), cap(b))

	for i := range 5 {
		b = append(b, i*i)
	}
	fmt.Println(b, len(b), cap(b)) // no reallocation happened
}

Uma confusão comum: make([]int, 5) seguido de cinco chamadas de append dá dez elementos, sendo os cinco primeiros zero. Use make([]int, 0, 5) quando for fazer append, ou make([]int, 5) quando for atribuir por índice.

Pré-alocar a capacidade quando você sabe o tamanho final evita crescimentos repetidos. É uma otimização, não uma exigência.

append e crescimento

O append acrescenta elementos depois do tamanho atual. Se a capacidade for suficiente, ele escreve no lugar. Se não for, aloca um array maior, copia os elementos antigos e devolve um slice que aponta para o array novo.

package main

import "fmt"

func main() {
	var s []int
	prevCap := cap(s)
	for i := range 2000 {
		s = append(s, i)
		if cap(s) != prevCap {
			fmt.Printf("len %4d  cap %4d\n", len(s), cap(s))
			prevCap = cap(s)
		}
	}
}

A capacidade mais ou menos dobra enquanto o slice é pequeno e cresce por um fator menor (tendendo a 1,25x) depois de passar de 256 elementos. Os números exatos são um detalhe do runtime que já mudou entre versões do Go, então nunca escreva código que dependa deles.

Como o append pode devolver outro array, você precisa usar o resultado dele:

append(s, 4)     // compile error: append(s, 4) (value of type []int) is not used
s = append(s, 4) // correct

Acrescentar um slice inteiro usa a sintaxe de espalhamento: s = append(s, other...).

Fatiar compartilha o array subjacente

s[low:high] cria um novo cabeçalho de slice sobre o mesmo array, cobrindo os índices de low até high, sem incluir high. Qualquer um dos limites pode ser omitido. Nenhum elemento é copiado.

package main

import "fmt"

func main() {
	nums := []int{10, 20, 30, 40, 50}
	mid := nums[1:4] // 20 30 40
	mid[0] = 99
	fmt.Println(nums) // the write shows up in nums

	fmt.Println(len(mid), cap(mid)) // cap runs to the end of nums
}

Saída:

[10 99 30 40 50]
3 4

Esse compartilhamento é o que torna o fatiamento barato. É também a origem do bug de slice mais famoso.

O bug de aliasing do append

Quando um sub-slice tem capacidade sobrando, fazer append nele escreve no array do slice pai, por cima de elementos que o pai ainda usa.

package main

import "fmt"

func main() {
	base := []int{1, 2, 3, 4, 5}
	first := base[:2] // [1 2], cap 5

	first = append(first, 100) // fits in capacity: overwrites base[2]
	fmt.Println(base)
	fmt.Println(first)

	// Two slices built from the same prefix clobber each other.
	prefix := make([]string, 0, 4)
	prefix = append(prefix, "cmd")
	a := append(prefix, "build")
	b := append(prefix, "test")
	fmt.Println(a, b) // both print test
}

Saída:

[1 2 100 4 5]
[1 2 100]
[cmd test] [cmd test]

a e b compartilham a posição do array logo depois de "cmd", então o segundo append sobrescreveu o primeiro. O código parece correto e funciona sempre que a capacidade por acaso está cheia, e é por isso que esse bug só aparece às vezes.

Duas correções:

1. A expressão de slice completa s[low:high:max] limita a capacidade a max-low. Sem capacidade sobrando, o próximo append precisa alocar. first := base[:2:2] deixa o primeiro exemplo seguro.
2. Copie explicitamente quando um slice for sobreviver à chamada ou receber appends de forma independente: slices.Clone(prefix) ou append([]string(nil), prefix...).

Uma armadilha parecida: um slice pequeno de um array enorme mantém o array inteiro vivo para o coletor de lixo. Se você lê um arquivo de 100 MB e guarda data[:10], os 100 MB continuam na memória. Clone a parte que vai guardar.

copy

A função embutida copy(dst, src) copia min(len(dst), len(src)) elementos e devolve essa contagem. Ela nunca aumenta dst.

package main

import (
	"fmt"
	"slices"
)

func main() {
	src := []int{1, 2, 3}

	dst := make([]int, len(src))
	n := copy(dst, src)
	dst[0] = 100
	fmt.Println(n, src, dst) // independent

	var empty []int
	fmt.Println(copy(empty, src)) // 0: dst has no length

	c := slices.Clone(src) // the one-line version (Go 1.21)
	fmt.Println(c)
}

O copy lida corretamente com origem e destino sobrepostos, então copy(s[1:], s) desloca os elementos para a direita sem corromper nada.

O pacote slices

Desde o Go 1.21, o pacote padrão slices tem funções genéricas para as operações que você antes escrevia à mão.

package main

import (
	"fmt"
	"slices"
)

func main() {
	s := []int{5, 2, 8, 2, 9}

	fmt.Println(slices.Contains(s, 8)) // true
	fmt.Println(slices.Index(s, 2))    // 1
	fmt.Println(slices.Max(s), slices.Min(s))

	slices.Sort(s)
	fmt.Println(s)
	i, found := slices.BinarySearch(s, 8)
	fmt.Println(i, found)

	s = slices.Compact(s) // drop adjacent duplicates
	fmt.Println(s)

	s = slices.Delete(s, 1, 2) // remove index 1
	fmt.Println(s)

	s = slices.Insert(s, 1, 3, 4)
	fmt.Println(s)

	slices.Reverse(s)
	fmt.Println(s, slices.Equal(s, []int{9, 8, 4, 3, 2}))
}

Delete e Insert devolvem um slice que você precisa atribuir, como o append. Ordenação tem página própria: ordenação.

Remover elementos durante um laço por índice pula elementos. Use slices.DeleteFunc no lugar:

s = slices.DeleteFunc(s, func(n int) bool { return n%2 == 0 }) // drop evens

Slices 2D

Um slice de slices dá uma grade cujas linhas podem ter tamanhos diferentes. Cada linha precisa ser alocada separadamente.

package main

import "fmt"

func main() {
	rows, cols := 3, 4
	grid := make([][]int, rows)
	for r := range grid {
		grid[r] = make([]int, cols)
	}
	grid[1][2] = 7

	for _, row := range grid {
		fmt.Println(row)
	}

	// Rows of different lengths are fine.
	triangle := [][]int{{1}, {1, 1}, {1, 2, 1}}
	fmt.Println(triangle)
}

Esquecer o make interno deixa cada linha nil, e grid[1][2] = 7 causa panic com index out of range [2] with length 0.

Slices nil e slices vazios

package main

import (
	"encoding/json"
	"fmt"
)

func main() {
	var a []int  // nil
	b := []int{} // empty, not nil

	fmt.Println(len(a), len(b), a == nil, b == nil)

	a = append(a, 1) // append works on nil
	fmt.Println(a)

	ja, _ := json.Marshal(struct{ Items []int }{})
	jb, _ := json.Marshal(struct{ Items []int }{Items: []int{}})
	fmt.Println(string(ja), string(jb))
}

Um slice nil se comporta como um vazio para len, cap, range e append, então prefira var s []T como estado inicial. Inicialize com []T{} só quando a diferença importar, o que acontece principalmente na saída JSON (null ou []). Verifique se está vazio com len(s) == 0, não com s == nil.

Slices e funções

Uma função que recebe um slice pode mudar os elementos dele, e quem chama vê as mudanças. Ela não pode mudar o tamanho do slice de quem chama, porque recebeu uma cópia do cabeçalho. Uma função que faz append precisa devolver o slice novo:

func addAll(s []int, vals ...int) []int {
	return append(s, vals...)
}

É por isso que append, slices.Delete e slices.Insert devolvem um slice.

Erros comuns

• Ignorar o resultado do append. Descartá-lo por completo não compila, mas atribuir append(s, x) a uma variável diferente da que você continua usando é um bug de lógica.
• Dois appends a partir da mesma base. Eles podem compartilhar o armazenamento. Clone a base ou use uma expressão de slice completa.
• make([]T, n) seguido de append. Deixa n zeros no início.
• Índice fora da faixa. s[len(s)] causa panic. O último elemento é s[len(s)-1].
• Comparar slices com ==. Só s == nil compila. Use slices.Equal.