...
Run Format

Source file src/bytes/buffer.go

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

View as plain text