builder.go

Documentation: strings

     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  	"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.
    15  type 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
    27  //go:nocheckptr
    28  func noescape(p unsafe.Pointer) unsafe.Pointer {
    29  	x := uintptr(p)
    30  	return unsafe.Pointer(x ^ 0)
    31  }
    32  
    33  func (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.
    47  func (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()).
    52  func (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.
    57  func (b *Builder) Cap() int { return cap(b.buf) }
    58  
    59  // Reset resets the Builder to be empty.
    60  func (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).
    67  func (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.
    76  func (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.
    88  func (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.
    96  func (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.
   104  func (b *Builder) WriteRune(r rune) (int, error) {
   105  	b.copyCheck()
   106  	if r < utf8.RuneSelf {
   107  		b.buf = append(b.buf, byte(r))
   108  		return 1, nil
   109  	}
   110  	l := len(b.buf)
   111  	if cap(b.buf)-l < utf8.UTFMax {
   112  		b.grow(utf8.UTFMax)
   113  	}
   114  	n := utf8.EncodeRune(b.buf[l:l+utf8.UTFMax], r)
   115  	b.buf = b.buf[:l+n]
   116  	return n, nil
   117  }
   118  
   119  // WriteString appends the contents of s to b's buffer.
   120  // It returns the length of s and a nil error.
   121  func (b *Builder) WriteString(s string) (int, error) {
   122  	b.copyCheck()
   123  	b.buf = append(b.buf, s...)
   124  	return len(s), nil
   125  }
   126
View as plain text