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

View as plain text