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