...

Source file src/bytes/buffer.go

Documentation: bytes

     1  // Copyright 2009 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 bytes
     6  
     7  // Simple byte buffer for marshaling data.
     8  
     9  import (
    10  	"errors"
    11  	"io"
    12  	"unicode/utf8"
    13  )
    14  
    15  // smallBufferSize is an initial allocation minimal capacity.
    16  const smallBufferSize = 64
    17  
    18  // A Buffer is a variable-sized buffer of bytes with [Buffer.Read] and [Buffer.Write] methods.
    19  // The zero value for Buffer is an empty buffer ready to use.
    20  type Buffer struct {
    21  	buf      []byte // contents are the bytes buf[off : len(buf)]
    22  	off      int    // read at &buf[off], write at &buf[len(buf)]
    23  	lastRead readOp // last read operation, so that Unread* can work correctly.
    24  }
    25  
    26  // The readOp constants describe the last action performed on
    27  // the buffer, so that UnreadRune and UnreadByte can check for
    28  // invalid usage. opReadRuneX constants are chosen such that
    29  // converted to int they correspond to the rune size that was read.
    30  type readOp int8
    31  
    32  // Don't use iota for these, as the values need to correspond with the
    33  // names and comments, which is easier to see when being explicit.
    34  const (
    35  	opRead      readOp = -1 // Any other read operation.
    36  	opInvalid   readOp = 0  // Non-read operation.
    37  	opReadRune1 readOp = 1  // Read rune of size 1.
    38  	opReadRune2 readOp = 2  // Read rune of size 2.
    39  	opReadRune3 readOp = 3  // Read rune of size 3.
    40  	opReadRune4 readOp = 4  // Read rune of size 4.
    41  )
    42  
    43  // ErrTooLarge is passed to panic if memory cannot be allocated to store data in a buffer.
    44  var ErrTooLarge = errors.New("bytes.Buffer: too large")
    45  var errNegativeRead = errors.New("bytes.Buffer: reader returned negative count from Read")
    46  
    47  const maxInt = int(^uint(0) >> 1)
    48  
    49  // Bytes returns a slice of length b.Len() holding the unread portion of the buffer.
    50  // The slice is valid for use only until the next buffer modification (that is,
    51  // only until the next call to a method like [Buffer.Read], [Buffer.Write], [Buffer.Reset], or [Buffer.Truncate]).
    52  // The slice aliases the buffer content at least until the next buffer modification,
    53  // so immediate changes to the slice will affect the result of future reads.
    54  func (b *Buffer) Bytes() []byte { return b.buf[b.off:] }
    55  
    56  // AvailableBuffer returns an empty buffer with b.Available() capacity.
    57  // This buffer is intended to be appended to and
    58  // passed to an immediately succeeding [Buffer.Write] call.
    59  // The buffer is only valid until the next write operation on b.
    60  func (b *Buffer) AvailableBuffer() []byte { return b.buf[len(b.buf):] }
    61  
    62  // String returns the contents of the unread portion of the buffer
    63  // as a string. If the [Buffer] is a nil pointer, it returns "<nil>".
    64  //
    65  // To build strings more efficiently, see the strings.Builder type.
    66  func (b *Buffer) String() string {
    67  	if b == nil {
    68  		// Special case, useful in debugging.
    69  		return "<nil>"
    70  	}
    71  	return string(b.buf[b.off:])
    72  }
    73  
    74  // empty reports whether the unread portion of the buffer is empty.
    75  func (b *Buffer) empty() bool { return len(b.buf) <= b.off }
    76  
    77  // Len returns the number of bytes of the unread portion of the buffer;
    78  // b.Len() == len(b.Bytes()).
    79  func (b *Buffer) Len() int { return len(b.buf) - b.off }
    80  
    81  // Cap returns the capacity of the buffer's underlying byte slice, that is, the
    82  // total space allocated for the buffer's data.
    83  func (b *Buffer) Cap() int { return cap(b.buf) }
    84  
    85  // Available returns how many bytes are unused in the buffer.
    86  func (b *Buffer) Available() int { return cap(b.buf) - len(b.buf) }
    87  
    88  // Truncate discards all but the first n unread bytes from the buffer
    89  // but continues to use the same allocated storage.
    90  // It panics if n is negative or greater than the length of the buffer.
    91  func (b *Buffer) Truncate(n int) {
    92  	if n == 0 {
    93  		b.Reset()
    94  		return
    95  	}
    96  	b.lastRead = opInvalid
    97  	if n < 0 || n > b.Len() {
    98  		panic("bytes.Buffer: truncation out of range")
    99  	}
   100  	b.buf = b.buf[:b.off+n]
   101  }
   102  
   103  // Reset resets the buffer to be empty,
   104  // but it retains the underlying storage for use by future writes.
   105  // Reset is the same as [Buffer.Truncate](0).
   106  func (b *Buffer) Reset() {
   107  	b.buf = b.buf[:0]
   108  	b.off = 0
   109  	b.lastRead = opInvalid
   110  }
   111  
   112  // tryGrowByReslice is an inlineable version of grow for the fast-case where the
   113  // internal buffer only needs to be resliced.
   114  // It returns the index where bytes should be written and whether it succeeded.
   115  func (b *Buffer) tryGrowByReslice(n int) (int, bool) {
   116  	if l := len(b.buf); n <= cap(b.buf)-l {
   117  		b.buf = b.buf[:l+n]
   118  		return l, true
   119  	}
   120  	return 0, false
   121  }
   122  
   123  // grow grows the buffer to guarantee space for n more bytes.
   124  // It returns the index where bytes should be written.
   125  // If the buffer can't grow it will panic with ErrTooLarge.
   126  func (b *Buffer) grow(n int) int {
   127  	m := b.Len()
   128  	// If buffer is empty, reset to recover space.
   129  	if m == 0 && b.off != 0 {
   130  		b.Reset()
   131  	}
   132  	// Try to grow by means of a reslice.
   133  	if i, ok := b.tryGrowByReslice(n); ok {
   134  		return i
   135  	}
   136  	if b.buf == nil && n <= smallBufferSize {
   137  		b.buf = make([]byte, n, smallBufferSize)
   138  		return 0
   139  	}
   140  	c := cap(b.buf)
   141  	if n <= c/2-m {
   142  		// We can slide things down instead of allocating a new
   143  		// slice. We only need m+n <= c to slide, but
   144  		// we instead let capacity get twice as large so we
   145  		// don't spend all our time copying.
   146  		copy(b.buf, b.buf[b.off:])
   147  	} else if c > maxInt-c-n {
   148  		panic(ErrTooLarge)
   149  	} else {
   150  		// Add b.off to account for b.buf[:b.off] being sliced off the front.
   151  		b.buf = growSlice(b.buf[b.off:], b.off+n)
   152  	}
   153  	// Restore b.off and len(b.buf).
   154  	b.off = 0
   155  	b.buf = b.buf[:m+n]
   156  	return m
   157  }
   158  
   159  // Grow grows the buffer's capacity, if necessary, to guarantee space for
   160  // another n bytes. After Grow(n), at least n bytes can be written to the
   161  // buffer without another allocation.
   162  // If n is negative, Grow will panic.
   163  // If the buffer can't grow it will panic with [ErrTooLarge].
   164  func (b *Buffer) Grow(n int) {
   165  	if n < 0 {
   166  		panic("bytes.Buffer.Grow: negative count")
   167  	}
   168  	m := b.grow(n)
   169  	b.buf = b.buf[:m]
   170  }
   171  
   172  // Write appends the contents of p to the buffer, growing the buffer as
   173  // needed. The return value n is the length of p; err is always nil. If the
   174  // buffer becomes too large, Write will panic with [ErrTooLarge].
   175  func (b *Buffer) Write(p []byte) (n int, err error) {
   176  	b.lastRead = opInvalid
   177  	m, ok := b.tryGrowByReslice(len(p))
   178  	if !ok {
   179  		m = b.grow(len(p))
   180  	}
   181  	return copy(b.buf[m:], p), nil
   182  }
   183  
   184  // WriteString appends the contents of s to the buffer, growing the buffer as
   185  // needed. The return value n is the length of s; err is always nil. If the
   186  // buffer becomes too large, WriteString will panic with [ErrTooLarge].
   187  func (b *Buffer) WriteString(s string) (n int, err error) {
   188  	b.lastRead = opInvalid
   189  	m, ok := b.tryGrowByReslice(len(s))
   190  	if !ok {
   191  		m = b.grow(len(s))
   192  	}
   193  	return copy(b.buf[m:], s), nil
   194  }
   195  
   196  // MinRead is the minimum slice size passed to a Read call by
   197  // [Buffer.ReadFrom]. As long as the [Buffer] has at least MinRead bytes beyond
   198  // what is required to hold the contents of r, ReadFrom will not grow the
   199  // underlying buffer.
   200  const MinRead = 512
   201  
   202  // ReadFrom reads data from r until EOF and appends it to the buffer, growing
   203  // the buffer as needed. The return value n is the number of bytes read. Any
   204  // error except io.EOF encountered during the read is also returned. If the
   205  // buffer becomes too large, ReadFrom will panic with [ErrTooLarge].
   206  func (b *Buffer) ReadFrom(r io.Reader) (n int64, err error) {
   207  	b.lastRead = opInvalid
   208  	for {
   209  		i := b.grow(MinRead)
   210  		b.buf = b.buf[:i]
   211  		m, e := r.Read(b.buf[i:cap(b.buf)])
   212  		if m < 0 {
   213  			panic(errNegativeRead)
   214  		}
   215  
   216  		b.buf = b.buf[:i+m]
   217  		n += int64(m)
   218  		if e == io.EOF {
   219  			return n, nil // e is EOF, so return nil explicitly
   220  		}
   221  		if e != nil {
   222  			return n, e
   223  		}
   224  	}
   225  }
   226  
   227  // growSlice grows b by n, preserving the original content of b.
   228  // If the allocation fails, it panics with ErrTooLarge.
   229  func growSlice(b []byte, n int) []byte {
   230  	defer func() {
   231  		if recover() != nil {
   232  			panic(ErrTooLarge)
   233  		}
   234  	}()
   235  	// TODO(http://golang.org/issue/51462): We should rely on the append-make
   236  	// pattern so that the compiler can call runtime.growslice. For example:
   237  	//	return append(b, make([]byte, n)...)
   238  	// This avoids unnecessary zero-ing of the first len(b) bytes of the
   239  	// allocated slice, but this pattern causes b to escape onto the heap.
   240  	//
   241  	// Instead use the append-make pattern with a nil slice to ensure that
   242  	// we allocate buffers rounded up to the closest size class.
   243  	c := len(b) + n // ensure enough space for n elements
   244  	if c < 2*cap(b) {
   245  		// The growth rate has historically always been 2x. In the future,
   246  		// we could rely purely on append to determine the growth rate.
   247  		c = 2 * cap(b)
   248  	}
   249  	b2 := append([]byte(nil), make([]byte, c)...)
   250  	copy(b2, b)
   251  	return b2[:len(b)]
   252  }
   253  
   254  // WriteTo writes data to w until the buffer is drained or an error occurs.
   255  // The return value n is the number of bytes written; it always fits into an
   256  // int, but it is int64 to match the io.WriterTo interface. Any error
   257  // encountered during the write is also returned.
   258  func (b *Buffer) WriteTo(w io.Writer) (n int64, err error) {
   259  	b.lastRead = opInvalid
   260  	if nBytes := b.Len(); nBytes > 0 {
   261  		m, e := w.Write(b.buf[b.off:])
   262  		if m > nBytes {
   263  			panic("bytes.Buffer.WriteTo: invalid Write count")
   264  		}
   265  		b.off += m
   266  		n = int64(m)
   267  		if e != nil {
   268  			return n, e
   269  		}
   270  		// all bytes should have been written, by definition of
   271  		// Write method in io.Writer
   272  		if m != nBytes {
   273  			return n, io.ErrShortWrite
   274  		}
   275  	}
   276  	// Buffer is now empty; reset.
   277  	b.Reset()
   278  	return n, nil
   279  }
   280  
   281  // WriteByte appends the byte c to the buffer, growing the buffer as needed.
   282  // The returned error is always nil, but is included to match [bufio.Writer]'s
   283  // WriteByte. If the buffer becomes too large, WriteByte will panic with
   284  // [ErrTooLarge].
   285  func (b *Buffer) WriteByte(c byte) error {
   286  	b.lastRead = opInvalid
   287  	m, ok := b.tryGrowByReslice(1)
   288  	if !ok {
   289  		m = b.grow(1)
   290  	}
   291  	b.buf[m] = c
   292  	return nil
   293  }
   294  
   295  // WriteRune appends the UTF-8 encoding of Unicode code point r to the
   296  // buffer, returning its length and an error, which is always nil but is
   297  // included to match [bufio.Writer]'s WriteRune. The buffer is grown as needed;
   298  // if it becomes too large, WriteRune will panic with [ErrTooLarge].
   299  func (b *Buffer) WriteRune(r rune) (n int, err error) {
   300  	// Compare as uint32 to correctly handle negative runes.
   301  	if uint32(r) < utf8.RuneSelf {
   302  		b.WriteByte(byte(r))
   303  		return 1, nil
   304  	}
   305  	b.lastRead = opInvalid
   306  	m, ok := b.tryGrowByReslice(utf8.UTFMax)
   307  	if !ok {
   308  		m = b.grow(utf8.UTFMax)
   309  	}
   310  	b.buf = utf8.AppendRune(b.buf[:m], r)
   311  	return len(b.buf) - m, nil
   312  }
   313  
   314  // Read reads the next len(p) bytes from the buffer or until the buffer
   315  // is drained. The return value n is the number of bytes read. If the
   316  // buffer has no data to return, err is io.EOF (unless len(p) is zero);
   317  // otherwise it is nil.
   318  func (b *Buffer) Read(p []byte) (n int, err error) {
   319  	b.lastRead = opInvalid
   320  	if b.empty() {
   321  		// Buffer is empty, reset to recover space.
   322  		b.Reset()
   323  		if len(p) == 0 {
   324  			return 0, nil
   325  		}
   326  		return 0, io.EOF
   327  	}
   328  	n = copy(p, b.buf[b.off:])
   329  	b.off += n
   330  	if n > 0 {
   331  		b.lastRead = opRead
   332  	}
   333  	return n, nil
   334  }
   335  
   336  // Next returns a slice containing the next n bytes from the buffer,
   337  // advancing the buffer as if the bytes had been returned by [Buffer.Read].
   338  // If there are fewer than n bytes in the buffer, Next returns the entire buffer.
   339  // The slice is only valid until the next call to a read or write method.
   340  func (b *Buffer) Next(n int) []byte {
   341  	b.lastRead = opInvalid
   342  	m := b.Len()
   343  	if n > m {
   344  		n = m
   345  	}
   346  	data := b.buf[b.off : b.off+n]
   347  	b.off += n
   348  	if n > 0 {
   349  		b.lastRead = opRead
   350  	}
   351  	return data
   352  }
   353  
   354  // ReadByte reads and returns the next byte from the buffer.
   355  // If no byte is available, it returns error io.EOF.
   356  func (b *Buffer) ReadByte() (byte, error) {
   357  	if b.empty() {
   358  		// Buffer is empty, reset to recover space.
   359  		b.Reset()
   360  		return 0, io.EOF
   361  	}
   362  	c := b.buf[b.off]
   363  	b.off++
   364  	b.lastRead = opRead
   365  	return c, nil
   366  }
   367  
   368  // ReadRune reads and returns the next UTF-8-encoded
   369  // Unicode code point from the buffer.
   370  // If no bytes are available, the error returned is io.EOF.
   371  // If the bytes are an erroneous UTF-8 encoding, it
   372  // consumes one byte and returns U+FFFD, 1.
   373  func (b *Buffer) ReadRune() (r rune, size int, err error) {
   374  	if b.empty() {
   375  		// Buffer is empty, reset to recover space.
   376  		b.Reset()
   377  		return 0, 0, io.EOF
   378  	}
   379  	c := b.buf[b.off]
   380  	if c < utf8.RuneSelf {
   381  		b.off++
   382  		b.lastRead = opReadRune1
   383  		return rune(c), 1, nil
   384  	}
   385  	r, n := utf8.DecodeRune(b.buf[b.off:])
   386  	b.off += n
   387  	b.lastRead = readOp(n)
   388  	return r, n, nil
   389  }
   390  
   391  // UnreadRune unreads the last rune returned by [Buffer.ReadRune].
   392  // If the most recent read or write operation on the buffer was
   393  // not a successful [Buffer.ReadRune], UnreadRune returns an error.  (In this regard
   394  // it is stricter than [Buffer.UnreadByte], which will unread the last byte
   395  // from any read operation.)
   396  func (b *Buffer) UnreadRune() error {
   397  	if b.lastRead <= opInvalid {
   398  		return errors.New("bytes.Buffer: UnreadRune: previous operation was not a successful ReadRune")
   399  	}
   400  	if b.off >= int(b.lastRead) {
   401  		b.off -= int(b.lastRead)
   402  	}
   403  	b.lastRead = opInvalid
   404  	return nil
   405  }
   406  
   407  var errUnreadByte = errors.New("bytes.Buffer: UnreadByte: previous operation was not a successful read")
   408  
   409  // UnreadByte unreads the last byte returned by the most recent successful
   410  // read operation that read at least one byte. If a write has happened since
   411  // the last read, if the last read returned an error, or if the read read zero
   412  // bytes, UnreadByte returns an error.
   413  func (b *Buffer) UnreadByte() error {
   414  	if b.lastRead == opInvalid {
   415  		return errUnreadByte
   416  	}
   417  	b.lastRead = opInvalid
   418  	if b.off > 0 {
   419  		b.off--
   420  	}
   421  	return nil
   422  }
   423  
   424  // ReadBytes reads until the first occurrence of delim in the input,
   425  // returning a slice containing the data up to and including the delimiter.
   426  // If ReadBytes encounters an error before finding a delimiter,
   427  // it returns the data read before the error and the error itself (often io.EOF).
   428  // ReadBytes returns err != nil if and only if the returned data does not end in
   429  // delim.
   430  func (b *Buffer) ReadBytes(delim byte) (line []byte, err error) {
   431  	slice, err := b.readSlice(delim)
   432  	// return a copy of slice. The buffer's backing array may
   433  	// be overwritten by later calls.
   434  	line = append(line, slice...)
   435  	return line, err
   436  }
   437  
   438  // readSlice is like ReadBytes but returns a reference to internal buffer data.
   439  func (b *Buffer) readSlice(delim byte) (line []byte, err error) {
   440  	i := IndexByte(b.buf[b.off:], delim)
   441  	end := b.off + i + 1
   442  	if i < 0 {
   443  		end = len(b.buf)
   444  		err = io.EOF
   445  	}
   446  	line = b.buf[b.off:end]
   447  	b.off = end
   448  	b.lastRead = opRead
   449  	return line, err
   450  }
   451  
   452  // ReadString reads until the first occurrence of delim in the input,
   453  // returning a string containing the data up to and including the delimiter.
   454  // If ReadString encounters an error before finding a delimiter,
   455  // it returns the data read before the error and the error itself (often io.EOF).
   456  // ReadString returns err != nil if and only if the returned data does not end
   457  // in delim.
   458  func (b *Buffer) ReadString(delim byte) (line string, err error) {
   459  	slice, err := b.readSlice(delim)
   460  	return string(slice), err
   461  }
   462  
   463  // NewBuffer creates and initializes a new [Buffer] using buf as its
   464  // initial contents. The new [Buffer] takes ownership of buf, and the
   465  // caller should not use buf after this call. NewBuffer is intended to
   466  // prepare a [Buffer] to read existing data. It can also be used to set
   467  // the initial size of the internal buffer for writing. To do that,
   468  // buf should have the desired capacity but a length of zero.
   469  //
   470  // In most cases, new([Buffer]) (or just declaring a [Buffer] variable) is
   471  // sufficient to initialize a [Buffer].
   472  func NewBuffer(buf []byte) *Buffer { return &Buffer{buf: buf} }
   473  
   474  // NewBufferString creates and initializes a new [Buffer] using string s as its
   475  // initial contents. It is intended to prepare a buffer to read an existing
   476  // string.
   477  //
   478  // In most cases, new([Buffer]) (or just declaring a [Buffer] variable) is
   479  // sufficient to initialize a [Buffer].
   480  func NewBufferString(s string) *Buffer {
   481  	return &Buffer{buf: []byte(s)}
   482  }
   483  

View as plain text