...
Run Format

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

View as plain text