8.19 strings and bytes — Specification¶

Reference card. Method signatures and notes only — for "why" see the other files in this leaf. Source of truth: $GOROOT/src/strings/ and $GOROOT/src/bytes/.

1. The two packages mirror each other¶

For almost every function in strings, there is a bytes function with the same name and the same shape, with string replaced by []byte. The exceptions:

• strings.Builder vs bytes.Buffer — different APIs because they serve different roles (write-only string builder vs read/write byte buffer).
• strings.Title is deprecated (Unicode title-casing is locale- dependent); bytes has no analog because byte-level case mapping isn't meaningful for non-ASCII text.

The tables below use s for the input and document strings unless noted.

2. Search and comparison¶

3. Split, join, fields¶

4. Transformation¶

Trim*¶

Trim*Func checks each rune from the relevant end. Trim and TrimLeft/TrimRight treat cutset as a set of runes (not a substring).

5. strings.Builder¶

type Builder struct {
    // unexported
}

func (b *Builder) Cap() int
func (b *Builder) Grow(n int)
func (b *Builder) Len() int
func (b *Builder) Reset()
func (b *Builder) String() string
func (b *Builder) Write(p []byte) (int, error)
func (b *Builder) WriteByte(c byte) error
func (b *Builder) WriteRune(r rune) (int, error)
func (b *Builder) WriteString(s string) (int, error)

Contracts:

• The zero value is ready to use.
• A non-zero Builder copied by value will panic on the next write.
• String() returns a string that aliases the internal buffer (zero-copy). Subsequent writes mutate the underlying buffer; the returned string is observed as before-the-write because the internal slice header records the length at call time. Do not rely on observability of writes; do reset and reuse safely.
• Write always returns nil error; the signature matches io.Writer.
• WriteByte always returns nil; signature matches io.ByteWriter.

6. bytes.Buffer¶

type Buffer struct {
    // unexported
}

func NewBuffer(buf []byte) *Buffer
func NewBufferString(s string) *Buffer

func (b *Buffer) Bytes() []byte
func (b *Buffer) Cap() int
func (b *Buffer) Grow(n int)
func (b *Buffer) Len() int
func (b *Buffer) Next(n int) []byte
func (b *Buffer) Read(p []byte) (int, error)
func (b *Buffer) ReadByte() (byte, error)
func (b *Buffer) ReadBytes(delim byte) ([]byte, error)
func (b *Buffer) ReadFrom(r io.Reader) (int64, error)
func (b *Buffer) ReadRune() (r rune, size int, err error)
func (b *Buffer) ReadString(delim byte) (string, error)
func (b *Buffer) Reset()
func (b *Buffer) String() string
func (b *Buffer) Truncate(n int)
func (b *Buffer) UnreadByte() error
func (b *Buffer) UnreadRune() error
func (b *Buffer) Write(p []byte) (int, error)
func (b *Buffer) WriteByte(c byte) error
func (b *Buffer) WriteRune(r rune) (int, error)
func (b *Buffer) WriteString(s string) (int, error)
func (b *Buffer) WriteTo(w io.Writer) (int64, error)

Interface satisfaction:

Contracts:

• Zero value is ready to use.
• Bytes() returns the unread portion of the buffer. Validity ends at the next mutating call (any Read*/Write*/Reset/Grow/ Truncate).
• Read drains; Bytes views without draining.
• ReadFrom reads into tail capacity; may grow.
• WriteTo calls w.Write(b.Bytes()) then resets.

7. strings.Reader¶

type Reader struct {
    // unexported
}

func NewReader(s string) *Reader

func (r *Reader) Len() int
func (r *Reader) Read(p []byte) (int, error)
func (r *Reader) ReadAt(p []byte, off int64) (int, error)
func (r *Reader) ReadByte() (byte, error)
func (r *Reader) ReadRune() (ch rune, size int, err error)
func (r *Reader) Reset(s string)
func (r *Reader) Seek(offset int64, whence int) (int64, error)
func (r *Reader) Size() int64
func (r *Reader) UnreadByte() error
func (r *Reader) UnreadRune() error
func (r *Reader) WriteTo(w io.Writer) (int64, error)

Implements: io.Reader, io.ReaderAt, io.ByteReader, io.ByteScanner, io.RuneReader, io.RuneScanner, io.Seeker, io.WriterTo. No allocation beyond the struct itself.

8. bytes.Reader¶

Same shape as strings.Reader but for []byte:

type Reader struct {
    // unexported
}

func NewReader(b []byte) *Reader
// methods identical to strings.Reader except Reset(b []byte)

9. strings.Replacer¶

type Replacer struct {
    // unexported
}

func NewReplacer(oldnew ...string) *Replacer

func (r *Replacer) Replace(s string) string
func (r *Replacer) WriteString(w io.Writer, s string) (n int, err error)

NewReplacer panics if given an odd number of arguments. Construction chooses one of three strategies based on input: single-byte trie, generic trie, or hash-based. Replacement happens in a single pass.

*Replacer is safe for concurrent use after construction.

10. bytes.Buffer constants and limits¶

// MinRead is the minimum slice size passed to a Read call by Buffer.ReadFrom.
const MinRead = 512

// ErrTooLarge is returned when a buffer cannot grow.
var ErrTooLarge = errors.New("bytes.Buffer: too large")

11. Conversion table: when does it allocate?¶

12. Complexity summary¶

13. Stability and compatibility¶

• The strings and bytes packages have a hard compatibility promise. No function has been removed since Go 1.
• Behavior of Title is deprecated; results are unchanged but callers should migrate to golang.org/x/text/cases.
• strings.Clone, Cut, CutPrefix, CutSuffix, ContainsFunc are post-1.0 additions; check go.mod for minimum version when using.

14. References¶

• pkg.go.dev/strings
• pkg.go.dev/bytes
• pkg.go.dev/unicode/utf8
• Source: $GOROOT/src/strings/, $GOROOT/src/bytes/, $GOROOT/src/internal/bytealg/