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 bufio implements buffered I/O. It wraps an io.Reader or io.Writer 6// object, creating another object (Reader or Writer) that also implements 7// the interface but provides buffering and some help for textual I/O. 8package bufio 9 10import ( 11 "bytes" 12 "errors" 13 "io" 14 "unicode/utf8" 15) 16 17const ( 18 defaultBufSize = 4096 19) 20 21var ( 22 ErrInvalidUnreadByte = errors.New("bufio: invalid use of UnreadByte") 23 ErrInvalidUnreadRune = errors.New("bufio: invalid use of UnreadRune") 24 ErrBufferFull = errors.New("bufio: buffer full") 25 ErrNegativeCount = errors.New("bufio: negative count") 26) 27 28// Buffered input. 29 30// Reader implements buffering for an io.Reader object. 31type Reader struct { 32 buf []byte 33 rd io.Reader // reader provided by the client 34 r, w int // buf read and write positions 35 err error 36 lastByte int // last byte read for UnreadByte; -1 means invalid 37 lastRuneSize int // size of last rune read for UnreadRune; -1 means invalid 38} 39 40const minReadBufferSize = 16 41const maxConsecutiveEmptyReads = 100 42 43// NewReaderSize returns a new Reader whose buffer has at least the specified 44// size. If the argument io.Reader is already a Reader with large enough 45// size, it returns the underlying Reader. 46func NewReaderSize(rd io.Reader, size int) *Reader { 47 // Is it already a Reader? 48 b, ok := rd.(*Reader) 49 if ok && len(b.buf) >= size { 50 return b 51 } 52 if size < minReadBufferSize { 53 size = minReadBufferSize 54 } 55 r := new(Reader) 56 r.reset(make([]byte, size), rd) 57 return r 58} 59 60// NewReader returns a new Reader whose buffer has the default size. 61func NewReader(rd io.Reader) *Reader { 62 return NewReaderSize(rd, defaultBufSize) 63} 64 65// Size returns the size of the underlying buffer in bytes. 66func (b *Reader) Size() int { return len(b.buf) } 67 68// Reset discards any buffered data, resets all state, and switches 69// the buffered reader to read from r. 70func (b *Reader) Reset(r io.Reader) { 71 b.reset(b.buf, r) 72} 73 74func (b *Reader) reset(buf []byte, r io.Reader) { 75 *b = Reader{ 76 buf: buf, 77 rd: r, 78 lastByte: -1, 79 lastRuneSize: -1, 80 } 81} 82 83var errNegativeRead = errors.New("bufio: reader returned negative count from Read") 84 85// fill reads a new chunk into the buffer. 86func (b *Reader) fill() { 87 // Slide existing data to beginning. 88 if b.r > 0 { 89 copy(b.buf, b.buf[b.r:b.w]) 90 b.w -= b.r 91 b.r = 0 92 } 93 94 if b.w >= len(b.buf) { 95 panic("bufio: tried to fill full buffer") 96 } 97 98 // Read new data: try a limited number of times. 99 for i := maxConsecutiveEmptyReads; i > 0; i-- { 100 n, err := b.rd.Read(b.buf[b.w:]) 101 if n < 0 { 102 panic(errNegativeRead) 103 } 104 b.w += n 105 if err != nil { 106 b.err = err 107 return 108 } 109 if n > 0 { 110 return 111 } 112 } 113 b.err = io.ErrNoProgress 114} 115 116func (b *Reader) readErr() error { 117 err := b.err 118 b.err = nil 119 return err 120} 121 122// Peek returns the next n bytes without advancing the reader. The bytes stop 123// being valid at the next read call. If Peek returns fewer than n bytes, it 124// also returns an error explaining why the read is short. The error is 125// ErrBufferFull if n is larger than b's buffer size. 126// 127// Calling Peek prevents a UnreadByte or UnreadRune call from succeeding 128// until the next read operation. 129func (b *Reader) Peek(n int) ([]byte, error) { 130 if n < 0 { 131 return nil, ErrNegativeCount 132 } 133 134 b.lastByte = -1 135 b.lastRuneSize = -1 136 137 for b.w-b.r < n && b.w-b.r < len(b.buf) && b.err == nil { 138 b.fill() // b.w-b.r < len(b.buf) => buffer is not full 139 } 140 141 if n > len(b.buf) { 142 return b.buf[b.r:b.w], ErrBufferFull 143 } 144 145 // 0 <= n <= len(b.buf) 146 var err error 147 if avail := b.w - b.r; avail < n { 148 // not enough data in buffer 149 n = avail 150 err = b.readErr() 151 if err == nil { 152 err = ErrBufferFull 153 } 154 } 155 return b.buf[b.r : b.r+n], err 156} 157 158// Discard skips the next n bytes, returning the number of bytes discarded. 159// 160// If Discard skips fewer than n bytes, it also returns an error. 161// If 0 <= n <= b.Buffered(), Discard is guaranteed to succeed without 162// reading from the underlying io.Reader. 163func (b *Reader) Discard(n int) (discarded int, err error) { 164 if n < 0 { 165 return 0, ErrNegativeCount 166 } 167 if n == 0 { 168 return 169 } 170 remain := n 171 for { 172 skip := b.Buffered() 173 if skip == 0 { 174 b.fill() 175 skip = b.Buffered() 176 } 177 if skip > remain { 178 skip = remain 179 } 180 b.r += skip 181 remain -= skip 182 if remain == 0 { 183 return n, nil 184 } 185 if b.err != nil { 186 return n - remain, b.readErr() 187 } 188 } 189} 190 191// Read reads data into p. 192// It returns the number of bytes read into p. 193// The bytes are taken from at most one Read on the underlying Reader, 194// hence n may be less than len(p). 195// To read exactly len(p) bytes, use io.ReadFull(b, p). 196// At EOF, the count will be zero and err will be io.EOF. 197func (b *Reader) Read(p []byte) (n int, err error) { 198 n = len(p) 199 if n == 0 { 200 if b.Buffered() > 0 { 201 return 0, nil 202 } 203 return 0, b.readErr() 204 } 205 if b.r == b.w { 206 if b.err != nil { 207 return 0, b.readErr() 208 } 209 if len(p) >= len(b.buf) { 210 // Large read, empty buffer. 211 // Read directly into p to avoid copy. 212 n, b.err = b.rd.Read(p) 213 if n < 0 { 214 panic(errNegativeRead) 215 } 216 if n > 0 { 217 b.lastByte = int(p[n-1]) 218 b.lastRuneSize = -1 219 } 220 return n, b.readErr() 221 } 222 // One read. 223 // Do not use b.fill, which will loop. 224 b.r = 0 225 b.w = 0 226 n, b.err = b.rd.Read(b.buf) 227 if n < 0 { 228 panic(errNegativeRead) 229 } 230 if n == 0 { 231 return 0, b.readErr() 232 } 233 b.w += n 234 } 235 236 // copy as much as we can 237 n = copy(p, b.buf[b.r:b.w]) 238 b.r += n 239 b.lastByte = int(b.buf[b.r-1]) 240 b.lastRuneSize = -1 241 return n, nil 242} 243 244// ReadByte reads and returns a single byte. 245// If no byte is available, returns an error. 246func (b *Reader) ReadByte() (byte, error) { 247 b.lastRuneSize = -1 248 for b.r == b.w { 249 if b.err != nil { 250 return 0, b.readErr() 251 } 252 b.fill() // buffer is empty 253 } 254 c := b.buf[b.r] 255 b.r++ 256 b.lastByte = int(c) 257 return c, nil 258} 259 260// UnreadByte unreads the last byte. Only the most recently read byte can be unread. 261// 262// UnreadByte returns an error if the most recent method called on the 263// Reader was not a read operation. Notably, Peek is not considered a 264// read operation. 265func (b *Reader) UnreadByte() error { 266 if b.lastByte < 0 || b.r == 0 && b.w > 0 { 267 return ErrInvalidUnreadByte 268 } 269 // b.r > 0 || b.w == 0 270 if b.r > 0 { 271 b.r-- 272 } else { 273 // b.r == 0 && b.w == 0 274 b.w = 1 275 } 276 b.buf[b.r] = byte(b.lastByte) 277 b.lastByte = -1 278 b.lastRuneSize = -1 279 return nil 280} 281 282// ReadRune reads a single UTF-8 encoded Unicode character and returns the 283// rune and its size in bytes. If the encoded rune is invalid, it consumes one byte 284// and returns unicode.ReplacementChar (U+FFFD) with a size of 1. 285func (b *Reader) ReadRune() (r rune, size int, err error) { 286 for b.r+utf8.UTFMax > b.w && !utf8.FullRune(b.buf[b.r:b.w]) && b.err == nil && b.w-b.r < len(b.buf) { 287 b.fill() // b.w-b.r < len(buf) => buffer is not full 288 } 289 b.lastRuneSize = -1 290 if b.r == b.w { 291 return 0, 0, b.readErr() 292 } 293 r, size = rune(b.buf[b.r]), 1 294 if r >= utf8.RuneSelf { 295 r, size = utf8.DecodeRune(b.buf[b.r:b.w]) 296 } 297 b.r += size 298 b.lastByte = int(b.buf[b.r-1]) 299 b.lastRuneSize = size 300 return r, size, nil 301} 302 303// UnreadRune unreads the last rune. If the most recent method called on 304// the Reader was not a ReadRune, UnreadRune returns an error. (In this 305// regard it is stricter than UnreadByte, which will unread the last byte 306// from any read operation.) 307func (b *Reader) UnreadRune() error { 308 if b.lastRuneSize < 0 || b.r < b.lastRuneSize { 309 return ErrInvalidUnreadRune 310 } 311 b.r -= b.lastRuneSize 312 b.lastByte = -1 313 b.lastRuneSize = -1 314 return nil 315} 316 317// Buffered returns the number of bytes that can be read from the current buffer. 318func (b *Reader) Buffered() int { return b.w - b.r } 319 320// ReadSlice reads until the first occurrence of delim in the input, 321// returning a slice pointing at the bytes in the buffer. 322// The bytes stop being valid at the next read. 323// If ReadSlice encounters an error before finding a delimiter, 324// it returns all the data in the buffer and the error itself (often io.EOF). 325// ReadSlice fails with error ErrBufferFull if the buffer fills without a delim. 326// Because the data returned from ReadSlice will be overwritten 327// by the next I/O operation, most clients should use 328// ReadBytes or ReadString instead. 329// ReadSlice returns err != nil if and only if line does not end in delim. 330func (b *Reader) ReadSlice(delim byte) (line []byte, err error) { 331 s := 0 // search start index 332 for { 333 // Search buffer. 334 if i := bytes.IndexByte(b.buf[b.r+s:b.w], delim); i >= 0 { 335 i += s 336 line = b.buf[b.r : b.r+i+1] 337 b.r += i + 1 338 break 339 } 340 341 // Pending error? 342 if b.err != nil { 343 line = b.buf[b.r:b.w] 344 b.r = b.w 345 err = b.readErr() 346 break 347 } 348 349 // Buffer full? 350 if b.Buffered() >= len(b.buf) { 351 b.r = b.w 352 line = b.buf 353 err = ErrBufferFull 354 break 355 } 356 357 s = b.w - b.r // do not rescan area we scanned before 358 359 b.fill() // buffer is not full 360 } 361 362 // Handle last byte, if any. 363 if i := len(line) - 1; i >= 0 { 364 b.lastByte = int(line[i]) 365 b.lastRuneSize = -1 366 } 367 368 return 369} 370 371// ReadLine is a low-level line-reading primitive. Most callers should use 372// ReadBytes('\n') or ReadString('\n') instead or use a Scanner. 373// 374// ReadLine tries to return a single line, not including the end-of-line bytes. 375// If the line was too long for the buffer then isPrefix is set and the 376// beginning of the line is returned. The rest of the line will be returned 377// from future calls. isPrefix will be false when returning the last fragment 378// of the line. The returned buffer is only valid until the next call to 379// ReadLine. ReadLine either returns a non-nil line or it returns an error, 380// never both. 381// 382// The text returned from ReadLine does not include the line end ("\r\n" or "\n"). 383// No indication or error is given if the input ends without a final line end. 384// Calling UnreadByte after ReadLine will always unread the last byte read 385// (possibly a character belonging to the line end) even if that byte is not 386// part of the line returned by ReadLine. 387func (b *Reader) ReadLine() (line []byte, isPrefix bool, err error) { 388 line, err = b.ReadSlice('\n') 389 if err == ErrBufferFull { 390 // Handle the case where "\r\n" straddles the buffer. 391 if len(line) > 0 && line[len(line)-1] == '\r' { 392 // Put the '\r' back on buf and drop it from line. 393 // Let the next call to ReadLine check for "\r\n". 394 if b.r == 0 { 395 // should be unreachable 396 panic("bufio: tried to rewind past start of buffer") 397 } 398 b.r-- 399 line = line[:len(line)-1] 400 } 401 return line, true, nil 402 } 403 404 if len(line) == 0 { 405 if err != nil { 406 line = nil 407 } 408 return 409 } 410 err = nil 411 412 if line[len(line)-1] == '\n' { 413 drop := 1 414 if len(line) > 1 && line[len(line)-2] == '\r' { 415 drop = 2 416 } 417 line = line[:len(line)-drop] 418 } 419 return 420} 421 422// ReadBytes reads until the first occurrence of delim in the input, 423// returning a slice containing the data up to and including the delimiter. 424// If ReadBytes encounters an error before finding a delimiter, 425// it returns the data read before the error and the error itself (often io.EOF). 426// ReadBytes returns err != nil if and only if the returned data does not end in 427// delim. 428// For simple uses, a Scanner may be more convenient. 429func (b *Reader) ReadBytes(delim byte) ([]byte, error) { 430 // Use ReadSlice to look for array, 431 // accumulating full buffers. 432 var frag []byte 433 var full [][]byte 434 var err error 435 n := 0 436 for { 437 var e error 438 frag, e = b.ReadSlice(delim) 439 if e == nil { // got final fragment 440 break 441 } 442 if e != ErrBufferFull { // unexpected error 443 err = e 444 break 445 } 446 447 // Make a copy of the buffer. 448 buf := make([]byte, len(frag)) 449 copy(buf, frag) 450 full = append(full, buf) 451 n += len(buf) 452 } 453 454 n += len(frag) 455 456 // Allocate new buffer to hold the full pieces and the fragment. 457 buf := make([]byte, n) 458 n = 0 459 // Copy full pieces and fragment in. 460 for i := range full { 461 n += copy(buf[n:], full[i]) 462 } 463 copy(buf[n:], frag) 464 return buf, err 465} 466 467// ReadString reads until the first occurrence of delim in the input, 468// returning a string containing the data up to and including the delimiter. 469// If ReadString encounters an error before finding a delimiter, 470// it returns the data read before the error and the error itself (often io.EOF). 471// ReadString returns err != nil if and only if the returned data does not end in 472// delim. 473// For simple uses, a Scanner may be more convenient. 474func (b *Reader) ReadString(delim byte) (string, error) { 475 bytes, err := b.ReadBytes(delim) 476 return string(bytes), err 477} 478 479// WriteTo implements io.WriterTo. 480// This may make multiple calls to the Read method of the underlying Reader. 481// If the underlying reader supports the WriteTo method, 482// this calls the underlying WriteTo without buffering. 483func (b *Reader) WriteTo(w io.Writer) (n int64, err error) { 484 n, err = b.writeBuf(w) 485 if err != nil { 486 return 487 } 488 489 if r, ok := b.rd.(io.WriterTo); ok { 490 m, err := r.WriteTo(w) 491 n += m 492 return n, err 493 } 494 495 if w, ok := w.(io.ReaderFrom); ok { 496 m, err := w.ReadFrom(b.rd) 497 n += m 498 return n, err 499 } 500 501 if b.w-b.r < len(b.buf) { 502 b.fill() // buffer not full 503 } 504 505 for b.r < b.w { 506 // b.r < b.w => buffer is not empty 507 m, err := b.writeBuf(w) 508 n += m 509 if err != nil { 510 return n, err 511 } 512 b.fill() // buffer is empty 513 } 514 515 if b.err == io.EOF { 516 b.err = nil 517 } 518 519 return n, b.readErr() 520} 521 522var errNegativeWrite = errors.New("bufio: writer returned negative count from Write") 523 524// writeBuf writes the Reader's buffer to the writer. 525func (b *Reader) writeBuf(w io.Writer) (int64, error) { 526 n, err := w.Write(b.buf[b.r:b.w]) 527 if n < 0 { 528 panic(errNegativeWrite) 529 } 530 b.r += n 531 return int64(n), err 532} 533 534// buffered output 535 536// Writer implements buffering for an io.Writer object. 537// If an error occurs writing to a Writer, no more data will be 538// accepted and all subsequent writes, and Flush, will return the error. 539// After all data has been written, the client should call the 540// Flush method to guarantee all data has been forwarded to 541// the underlying io.Writer. 542type Writer struct { 543 err error 544 buf []byte 545 n int 546 wr io.Writer 547} 548 549// NewWriterSize returns a new Writer whose buffer has at least the specified 550// size. If the argument io.Writer is already a Writer with large enough 551// size, it returns the underlying Writer. 552func NewWriterSize(w io.Writer, size int) *Writer { 553 // Is it already a Writer? 554 b, ok := w.(*Writer) 555 if ok && len(b.buf) >= size { 556 return b 557 } 558 if size <= 0 { 559 size = defaultBufSize 560 } 561 return &Writer{ 562 buf: make([]byte, size), 563 wr: w, 564 } 565} 566 567// NewWriter returns a new Writer whose buffer has the default size. 568func NewWriter(w io.Writer) *Writer { 569 return NewWriterSize(w, defaultBufSize) 570} 571 572// Size returns the size of the underlying buffer in bytes. 573func (b *Writer) Size() int { return len(b.buf) } 574 575// Reset discards any unflushed buffered data, clears any error, and 576// resets b to write its output to w. 577func (b *Writer) Reset(w io.Writer) { 578 b.err = nil 579 b.n = 0 580 b.wr = w 581} 582 583// Flush writes any buffered data to the underlying io.Writer. 584func (b *Writer) Flush() error { 585 if b.err != nil { 586 return b.err 587 } 588 if b.n == 0 { 589 return nil 590 } 591 n, err := b.wr.Write(b.buf[0:b.n]) 592 if n < b.n && err == nil { 593 err = io.ErrShortWrite 594 } 595 if err != nil { 596 if n > 0 && n < b.n { 597 copy(b.buf[0:b.n-n], b.buf[n:b.n]) 598 } 599 b.n -= n 600 b.err = err 601 return err 602 } 603 b.n = 0 604 return nil 605} 606 607// Available returns how many bytes are unused in the buffer. 608func (b *Writer) Available() int { return len(b.buf) - b.n } 609 610// Buffered returns the number of bytes that have been written into the current buffer. 611func (b *Writer) Buffered() int { return b.n } 612 613// Write writes the contents of p into the buffer. 614// It returns the number of bytes written. 615// If nn < len(p), it also returns an error explaining 616// why the write is short. 617func (b *Writer) Write(p []byte) (nn int, err error) { 618 for len(p) > b.Available() && b.err == nil { 619 var n int 620 if b.Buffered() == 0 { 621 // Large write, empty buffer. 622 // Write directly from p to avoid copy. 623 n, b.err = b.wr.Write(p) 624 } else { 625 n = copy(b.buf[b.n:], p) 626 b.n += n 627 b.Flush() 628 } 629 nn += n 630 p = p[n:] 631 } 632 if b.err != nil { 633 return nn, b.err 634 } 635 n := copy(b.buf[b.n:], p) 636 b.n += n 637 nn += n 638 return nn, nil 639} 640 641// WriteByte writes a single byte. 642func (b *Writer) WriteByte(c byte) error { 643 if b.err != nil { 644 return b.err 645 } 646 if b.Available() <= 0 && b.Flush() != nil { 647 return b.err 648 } 649 b.buf[b.n] = c 650 b.n++ 651 return nil 652} 653 654// WriteRune writes a single Unicode code point, returning 655// the number of bytes written and any error. 656func (b *Writer) WriteRune(r rune) (size int, err error) { 657 if r < utf8.RuneSelf { 658 err = b.WriteByte(byte(r)) 659 if err != nil { 660 return 0, err 661 } 662 return 1, nil 663 } 664 if b.err != nil { 665 return 0, b.err 666 } 667 n := b.Available() 668 if n < utf8.UTFMax { 669 if b.Flush(); b.err != nil { 670 return 0, b.err 671 } 672 n = b.Available() 673 if n < utf8.UTFMax { 674 // Can only happen if buffer is silly small. 675 return b.WriteString(string(r)) 676 } 677 } 678 size = utf8.EncodeRune(b.buf[b.n:], r) 679 b.n += size 680 return size, nil 681} 682 683// WriteString writes a string. 684// It returns the number of bytes written. 685// If the count is less than len(s), it also returns an error explaining 686// why the write is short. 687func (b *Writer) WriteString(s string) (int, error) { 688 nn := 0 689 for len(s) > b.Available() && b.err == nil { 690 n := copy(b.buf[b.n:], s) 691 b.n += n 692 nn += n 693 s = s[n:] 694 b.Flush() 695 } 696 if b.err != nil { 697 return nn, b.err 698 } 699 n := copy(b.buf[b.n:], s) 700 b.n += n 701 nn += n 702 return nn, nil 703} 704 705// ReadFrom implements io.ReaderFrom. If the underlying writer 706// supports the ReadFrom method, and b has no buffered data yet, 707// this calls the underlying ReadFrom without buffering. 708func (b *Writer) ReadFrom(r io.Reader) (n int64, err error) { 709 if b.err != nil { 710 return 0, b.err 711 } 712 if b.Buffered() == 0 { 713 if w, ok := b.wr.(io.ReaderFrom); ok { 714 n, err = w.ReadFrom(r) 715 b.err = err 716 return n, err 717 } 718 } 719 var m int 720 for { 721 if b.Available() == 0 { 722 if err1 := b.Flush(); err1 != nil { 723 return n, err1 724 } 725 } 726 nr := 0 727 for nr < maxConsecutiveEmptyReads { 728 m, err = r.Read(b.buf[b.n:]) 729 if m != 0 || err != nil { 730 break 731 } 732 nr++ 733 } 734 if nr == maxConsecutiveEmptyReads { 735 return n, io.ErrNoProgress 736 } 737 b.n += m 738 n += int64(m) 739 if err != nil { 740 break 741 } 742 } 743 if err == io.EOF { 744 // If we filled the buffer exactly, flush preemptively. 745 if b.Available() == 0 { 746 err = b.Flush() 747 } else { 748 err = nil 749 } 750 } 751 return n, err 752} 753 754// buffered input and output 755 756// ReadWriter stores pointers to a Reader and a Writer. 757// It implements io.ReadWriter. 758type ReadWriter struct { 759 *Reader 760 *Writer 761} 762 763// NewReadWriter allocates a new ReadWriter that dispatches to r and w. 764func NewReadWriter(r *Reader, w *Writer) *ReadWriter { 765 return &ReadWriter{r, w} 766} 767