1// Copyright 2017 The Go Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style
3// license that can be found in the LICENSE file.
4
5package strings
6
7import (
8	"unicode/utf8"
9	"unsafe"
10)
11
12// A Builder is used to efficiently build a string using Write methods.
13// It minimizes memory copying. The zero value is ready to use.
14// Do not copy a non-zero Builder.
15type Builder struct {
16	addr *Builder // of receiver, to detect copies by value
17	buf  []byte
18}
19
20// noescape hides a pointer from escape analysis.  noescape is
21// the identity function but escape analysis doesn't think the
22// output depends on the input. noescape is inlined and currently
23// compiles down to zero instructions.
24// USE CAREFULLY!
25// This was copied from the runtime; see issues 23382 and 7921.
26//go:nosplit
27func noescape(p unsafe.Pointer) unsafe.Pointer {
28	x := uintptr(p)
29	return unsafe.Pointer(x ^ 0)
30}
31
32func (b *Builder) copyCheck() {
33	if b.addr == nil {
34		// This hack works around a failing of Go's escape analysis
35		// that was causing b to escape and be heap allocated.
36		// See issue 23382.
37		// TODO: once issue 7921 is fixed, this should be reverted to
38		// just "b.addr = b".
39		b.addr = (*Builder)(noescape(unsafe.Pointer(b)))
40	} else if b.addr != b {
41		panic("strings: illegal use of non-zero Builder copied by value")
42	}
43}
44
45// String returns the accumulated string.
46func (b *Builder) String() string {
47	return *(*string)(unsafe.Pointer(&b.buf))
48}
49
50// Len returns the number of accumulated bytes; b.Len() == len(b.String()).
51func (b *Builder) Len() int { return len(b.buf) }
52
53// Cap returns the capacity of the builder's underlying byte slice. It is the
54// total space allocated for the string being built and includes any bytes
55// already written.
56func (b *Builder) Cap() int { return cap(b.buf) }
57
58// Reset resets the Builder to be empty.
59func (b *Builder) Reset() {
60	b.addr = nil
61	b.buf = nil
62}
63
64// grow copies the buffer to a new, larger buffer so that there are at least n
65// bytes of capacity beyond len(b.buf).
66func (b *Builder) grow(n int) {
67	buf := make([]byte, len(b.buf), 2*cap(b.buf)+n)
68	copy(buf, b.buf)
69	b.buf = buf
70}
71
72// Grow grows b's capacity, if necessary, to guarantee space for
73// another n bytes. After Grow(n), at least n bytes can be written to b
74// without another allocation. If n is negative, Grow panics.
75func (b *Builder) Grow(n int) {
76	b.copyCheck()
77	if n < 0 {
78		panic("strings.Builder.Grow: negative count")
79	}
80	if cap(b.buf)-len(b.buf) < n {
81		b.grow(n)
82	}
83}
84
85// Write appends the contents of p to b's buffer.
86// Write always returns len(p), nil.
87func (b *Builder) Write(p []byte) (int, error) {
88	b.copyCheck()
89	b.buf = append(b.buf, p...)
90	return len(p), nil
91}
92
93// WriteByte appends the byte c to b's buffer.
94// The returned error is always nil.
95func (b *Builder) WriteByte(c byte) error {
96	b.copyCheck()
97	b.buf = append(b.buf, c)
98	return nil
99}
100
101// WriteRune appends the UTF-8 encoding of Unicode code point r to b's buffer.
102// It returns the length of r and a nil error.
103func (b *Builder) WriteRune(r rune) (int, error) {
104	b.copyCheck()
105	if r < utf8.RuneSelf {
106		b.buf = append(b.buf, byte(r))
107		return 1, nil
108	}
109	l := len(b.buf)
110	if cap(b.buf)-l < utf8.UTFMax {
111		b.grow(utf8.UTFMax)
112	}
113	n := utf8.EncodeRune(b.buf[l:l+utf8.UTFMax], r)
114	b.buf = b.buf[:l+n]
115	return n, nil
116}
117
118// WriteString appends the contents of s to b's buffer.
119// It returns the length of s and a nil error.
120func (b *Builder) WriteString(s string) (int, error) {
121	b.copyCheck()
122	b.buf = append(b.buf, s...)
123	return len(s), nil
124}
125