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