strings

Go strings as bytes and runes, plus Cut, Split, Fields, prefix checks, and replacement helpers.

A Go string is a read-only slice of bytes. When the bytes are UTF-8, ranging the string with a for range loop yields runes, but len(s), s[i], and most strings functions still operate in bytes. Indexing into the middle of a multi-byte rune is a bug.

This page documents the helpers used most often to search, split, and rewrite text. It does not cover the strings.Builder type or every comparison helper in the package.

Examples were checked against Go 1.24.0. See the official package documentation for the complete API.

Go reference overview →

API index

APISummary
len, strings.Index, strings.IndexRuneReport the byte offset of a substring or rune. Combine this with len and utf8.RuneCountInString to see why a string can have more bytes than characters.
strings.Cut, strings.Split, strings.Fields, strings.CutPrefix, strings.HasPrefix, strings.ContainsSplit or search a string by bytes. Prefer Cut or CutPrefix when you need to know whether the separator or prefix was actually there.
strings.ToLower, strings.TrimSpace, strings.ReplaceAll, strings.CountReturn a rewritten copy of the string, or count non-overlapping copies of a substring. None of these functions modify the original string.

Bytes and runes

len(s) is the number of bytes, not the number of Unicode code points. utf8.RuneCountInString(s) or len([]rune(s)) counts runes. Both strings.Index and strings.IndexRune return a byte offset, or -1 when there is no match, so the two calls can agree even when the match is a multi-byte rune.

Slice expressions such as s[0:2] are also in bytes. Convert to []rune when you need to slice by code points.

len, strings.Index, strings.IndexRune

func Index(s, substr string) int
func IndexRune(s string, r rune) int

Report the byte offset of a substring or rune. Combine this with len and utf8.RuneCountInString to see why a string can have more bytes than characters.

ParameterDescription
sThe string to search, treated as a sequence of bytes.
substr / rThe substring or rune to find. IndexRune cannot search for a multi-rune string; use Index for that.

Returns: The byte index of the first match, or -1 if there is no match. These functions do not return a rune index.

  • In "Go语言", "Go" is two bytes and each of the next two runes is three bytes, so len is 8 and the rune count is 4.
  • Both Index(s, "语") and IndexRune(s, '语') return 2, which is a byte offset, not "the third character" counted from one.
  • s[0:2] is safe here because it lands on a rune boundary. s[0:3] would cut inside 语.
go
package main

import (
	"fmt"
	"strings"
	"unicode/utf8"
)

func main() {
	s := "Go语言"
	fmt.Println(len(s), utf8.RuneCountInString(s))
	fmt.Println(strings.Index(s, "语"), strings.IndexRune(s, '语'))
	fmt.Println(s[0:2], string([]rune(s)[0:3]))
}

Expected output

8 4
2 2
Go Go语

Related: unicode/utf8.RuneCountInString

Official documentation →

Cut, Split, and search

Cut splits on the first separator and tells you whether the separator was present. Split divides on every separator and does not report that fact. Fields splits on any sequence of unicode.IsSpace whitespace and discards empty leading or trailing pieces.

HasPrefix and Contains search by bytes. They do not fold case and they do not treat equivalent Unicode normalizations as equal.

Replace, trim, and case

ToLower and ToUpper use Unicode case mapping. TrimSpace removes leading and trailing unicode.IsSpace characters, including newlines. ReplaceAll replaces every non-overlapping instance of old; it does not interpret old as a regular expression.

strings.ToLower, strings.TrimSpace, strings.ReplaceAll, strings.Count

func ToLower(s string) string
func TrimSpace(s string) string
func ReplaceAll(s, old, new string) string
func Count(s, substr string) int

Return a rewritten copy of the string, or count non-overlapping copies of a substring. None of these functions modify the original string.

ParameterDescription
sThe input string.
old, newFor ReplaceAll, the byte sequence to replace and its replacement. An empty old matches at every rune boundary, including the start and end of the string.
substrFor Count, the non-overlapping substring to count. Counting the empty string returns 1 plus the number of runes.

Returns: ToLower, TrimSpace, and ReplaceAll return a new string. Count returns an int.

  • Go strings are immutable. The return value is a new string; the input is unchanged.
  • Count("banana", "na") is 2. The matches do not overlap.
go
package main

import (
	"fmt"
	"strings"
)

func main() {
	fmt.Println(strings.ToLower("Go"))
	fmt.Println(strings.TrimSpace("  hi\n"))
	fmt.Println(strings.ReplaceAll("go go go", "go", "ok"))
	fmt.Println(strings.Count("banana", "na"))
}

Expected output

go
hi
ok ok ok
2

Official documentation →