Golang Rune and Byte: UTF-8 Strings Explained

A Go string is a sequence of bytes, and Go source and string literals are UTF-8. A byte is one of those bytes. A rune is one Unicode character (a code point), which UTF-8 stores in 1 to 4 bytes. Most string confusion in Go comes from mixing the two up:

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)
	}
}

語 is three bytes in UTF-8, so "語Go" is 5 bytes but 3 runes. The index loop sees five bytes, and bytes 0, 1 and 2 are meaningless on their own. The range loop decodes UTF-8 and yields three runes at indexes 0, 3 and 4: i is always a byte offset, not a character count.

byte and rune Are Aliases

Because they are aliases, a byte is a uint8 and a rune is an int32; no conversion is needed between the alias and its underlying type. Single quotes make a rune, double quotes a string. 'ab' is a compile error, since a rune literal holds exactly one character.

Runes are numbers, so you can do arithmetic on them:

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' is the classic way to turn a digit character into its value. The unicode package classifies runes (IsLetter, IsDigit, IsSpace, IsUpper) and changes case correctly for non-ASCII letters. %c prints a rune as a character, %U in U+4E16 form, %q as a quoted rune literal.

How UTF-8 Stores Characters

ASCII text is identical in UTF-8, which is why byte-based code often works in testing and breaks on the first accented name. The unicode/utf8 package works with the encoding directly:

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 (with a space) prints bytes in hex separated by spaces. utf8.ValidString reports whether a string is valid UTF-8. Go strings may hold any bytes, not only valid UTF-8; when range meets an invalid byte it yields utf8.RuneError (U+FFFD, the replacement character) and advances one byte.

Converting Between string, []byte and []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))
}

Reversing by bytes would scramble 世界 into invalid UTF-8, which is why reverse works on runes. Even runes are not the full story: a character like é can also be written as e plus a combining accent, which is two runes. For user-visible characters (grapheme clusters), use a library such as github.com/rivo/uniseg.

Each conversion copies, because strings are immutable and slices are not. In hot code, avoid converting back and forth; the compiler optimizes some cases (such as string(b) used as a map key or in a comparison) to skip the copy.

Indexing Gives a Byte

s[i] returns a byte, and s[i:j] slices by byte offsets:

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]) is a trap: converting a single byte to string treats it as the code point 195, which is Ã, not the byte itself. To find character boundaries, use range, the strings.Index family (which return byte offsets that are always on boundaries), or utf8.DecodeRuneInString.

The bytes Package

bytes mirrors strings for []byte: bytes.Contains, bytes.Split, bytes.Fields, bytes.TrimSpace, bytes.Equal, bytes.ToUpper and so on. Use it when data arrives as bytes (file contents, HTTP bodies, network buffers), so you do not convert to a string and back:

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 is a growable byte buffer that implements io.Reader and io.Writer. It is the right tool when you both write and read bytes; for building a string, strings.Builder is slightly cheaper. Compare byte slices with bytes.Equal, since == does not work on slices.

Choosing Between Them

• Text you display, compare or search: keep it a string, and use range when you walk it character by character.
• Character positions, reversing, truncating to n characters: convert to []rune.
• I/O, hashing, encoding, binary protocols: use []byte and the bytes package.
• A single character: a rune. A single raw byte: a byte.