Rune e byte em Golang: strings UTF-8 explicadas

Uma string em Go é uma sequência de bytes, e o código-fonte Go e os literais de string são UTF-8. Um byte é um desses bytes. Uma rune é um caractere Unicode (um code point), que o UTF-8 guarda em 1 a 4 bytes. A maior parte da confusão com strings em Go vem de misturar os dois:

package main

import (
	"fmt"
	"unicode/utf8"
)

func main() {
	s := "語Go"

	fmt.Println("bytes:", len(s))
	fmt.Println("runes:", utf8.RuneCountInString(s))

	fmt.Println("byte loop:")
	for i := 0; i < len(s); i++ {
		fmt.Printf("  %d: %d\n", i, s[i])
	}

	fmt.Println("range loop:")
	for i, r := range s {
		fmt.Printf("  %d: %c (%d)\n", i, r, r)
	}
}

語 ocupa três bytes em UTF-8, então "語Go" tem 5 bytes, mas 3 runes. O laço por índice vê cinco bytes, e os bytes 0, 1 e 2 não significam nada sozinhos. O laço com range decodifica o UTF-8 e entrega três runes nos índices 0, 3 e 4: i é sempre um offset em bytes, não uma contagem de caracteres.

byte e rune são aliases

Como são aliases, um byte é um uint8 e uma rune é um int32; nenhuma conversão é necessária entre o alias e o tipo subjacente. Aspas simples criam uma rune, aspas duplas uma string. 'ab' é erro de compilação, já que um literal de rune guarda exatamente um caractere.

Runes são números, então dá para fazer contas com elas:

package main

import (
	"fmt"
	"unicode"
)

func main() {
	r := 'a'
	fmt.Println(r, string(r))
	fmt.Println(string(r + 1))
	fmt.Println('7'-'0', unicode.IsDigit('7'))
	fmt.Println(unicode.ToUpper('é') == 'É', string(unicode.ToUpper('é')))
	fmt.Printf("%c %U %q\n", '世', '世', '世')
}

'7' - '0' é o jeito clássico de transformar um caractere de dígito no seu valor. O pacote unicode classifica runes (IsLetter, IsDigit, IsSpace, IsUpper) e muda maiúsculas e minúsculas corretamente em letras não ASCII. %c imprime uma rune como caractere, %U no formato U+4E16 e %q como um literal de rune entre aspas.

Como o UTF-8 guarda caracteres

Texto ASCII é idêntico em UTF-8, e é por isso que código baseado em bytes muitas vezes funciona nos testes e quebra no primeiro nome com acento. O pacote unicode/utf8 trabalha diretamente com a codificação:

package main

import (
	"fmt"
	"unicode/utf8"
)

func main() {
	for _, s := range []string{"a", "é", "€", "🙂"} {
		r, size := utf8.DecodeRuneInString(s)
		fmt.Printf("%s  U+%04X  %d bytes  % x\n", s, r, size, []byte(s))
	}

	fmt.Println(utf8.ValidString("ok"), utf8.ValidString("\xff"))
	fmt.Println(utf8.RuneLen('語'))
}

% x (com um espaço) imprime os bytes em hexadecimal separados por espaço. utf8.ValidString diz se uma string é UTF-8 válido. Strings em Go podem guardar quaisquer bytes, não só UTF-8 válido; quando o range encontra um byte inválido, ele entrega utf8.RuneError (U+FFFD, o caractere de substituição) e avança um byte.

Convertendo entre string, []byte e []rune

package main

import "fmt"

func reverse(s string) string {
	r := []rune(s)
	for i, j := 0, len(r)-1; i < j; i, j = i+1, j-1 {
		r[i], r[j] = r[j], r[i]
	}
	return string(r)
}

func main() {
	s := "héllo, 世界"

	b := []byte(s)
	r := []rune(s)
	fmt.Println(len(s), len(b), len(r))

	fmt.Println(reverse(s))

	// first 7 characters, not bytes
	fmt.Println(string(r[:7]))

	// edit bytes, then convert back
	b[0] = 'H'
	fmt.Println(string(b))
}

Inverter por bytes transformaria 世界 em UTF-8 inválido, e é por isso que reverse trabalha com runes. Nem as runes contam toda a história: um caractere como é também pode ser escrito como e mais um acento combinante, o que dá duas runes. Para os caracteres que o usuário enxerga (grapheme clusters), use uma biblioteca como github.com/rivo/uniseg.

Cada conversão copia, porque strings são imutáveis e slices não. Em código quente, evite converter de um lado para o outro; o compilador otimiza alguns casos (como string(b) usado como chave de map ou em uma comparação) para pular a cópia.

Indexar devolve um byte

s[i] devolve um byte, e s[i:j] fatia por offsets em bytes:

s := "café"
fmt.Println(s[3])            // 195: the first byte of é
fmt.Println(string(s[3]))    // "Ã": that byte read as a code point
fmt.Println(s[:3])           // "caf"
fmt.Println(s[:4])           // "caf\xc3": half of é, invalid UTF-8

string(s[3]) é uma armadilha: converter um único byte para string o trata como o code point 195, que é Ã, e não o próprio byte. Para encontrar as fronteiras entre caracteres, use range, a família strings.Index (que devolve offsets em bytes sempre em fronteiras) ou utf8.DecodeRuneInString.

O pacote bytes

bytes espelha strings para []byte: bytes.Contains, bytes.Split, bytes.Fields, bytes.TrimSpace, bytes.Equal, bytes.ToUpper e assim por diante. Use-o quando os dados chegam como bytes (conteúdo de arquivo, corpo HTTP, buffers de rede), para não converter para string e de volta:

package main

import (
	"bytes"
	"fmt"
)

func main() {
	data := []byte("name=ana\nrole=admin\n")

	for _, line := range bytes.Split(bytes.TrimSpace(data), []byte("\n")) {
		key, value, _ := bytes.Cut(line, []byte("="))
		fmt.Printf("%s -> %s\n", key, value)
	}

	var buf bytes.Buffer
	buf.WriteString("hello, ")
	buf.Write([]byte("bytes"))
	buf.WriteByte('!')
	fmt.Println(buf.String(), buf.Len())

	fmt.Println(bytes.Equal([]byte("a"), []byte("a")))
}

bytes.Buffer é um buffer de bytes que cresce e implementa io.Reader e io.Writer. É a ferramenta certa quando você escreve e lê bytes; para montar uma string, strings.Builder é um pouco mais barato. Compare slices de bytes com bytes.Equal, já que == não funciona com slices.

Qual escolher

• Texto que você exibe, compara ou busca: mantenha como string e use range para percorrê-lo caractere por caractere.
• Posições de caractere, inverter, cortar em n caracteres: converta para []rune.
• I/O, hashing, codificação, protocolos binários: use []byte e o pacote bytes.
• Um único caractere: uma rune. Um único byte bruto: um byte.