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