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