libgo/go/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 }