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