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.
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.
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")
30 // Reader implements buffering for an io.Reader object.
33 rd io
.Reader
// reader provided by the client
34 r
, w
int // buf read and write positions
36 lastByte
int // last byte read for UnreadByte; -1 means invalid
37 lastRuneSize
int // size of last rune read for UnreadRune; -1 means invalid
40 const minReadBufferSize
= 16
41 const maxConsecutiveEmptyReads
= 100
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?
49 if ok
&& len(b
.buf
) >= size
{
52 if size
< minReadBufferSize
{
53 size
= minReadBufferSize
56 r
.reset(make([]byte, size
), rd
)
60 // NewReader returns a new Reader whose buffer has the default size.
61 func NewReader(rd io
.Reader
) *Reader
{
62 return NewReaderSize(rd
, defaultBufSize
)
65 // Size returns the size of the underlying buffer in bytes.
66 func (b
*Reader
) Size() int { return len(b
.buf
) }
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
) {
74 func (b
*Reader
) reset(buf
[]byte, r io
.Reader
) {
83 var errNegativeRead
= errors
.New("bufio: reader returned negative count from Read")
85 // fill reads a new chunk into the buffer.
86 func (b
*Reader
) fill() {
87 // Slide existing data to beginning.
89 copy(b
.buf
, b
.buf
[b
.r
:b
.w
])
94 if b
.w
>= len(b
.buf
) {
95 panic("bufio: tried to fill full buffer")
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
:])
102 panic(errNegativeRead
)
113 b
.err
= io
.ErrNoProgress
116 func (b
*Reader
) readErr() error
{
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.
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
) {
131 return nil, ErrNegativeCount
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
142 return b
.buf
[b
.r
:b
.w
], ErrBufferFull
145 // 0 <= n <= len(b.buf)
147 if avail
:= b
.w
- b
.r
; avail
< n
{
148 // not enough data in buffer
155 return b
.buf
[b
.r
: b
.r
+n
], err
158 // Discard skips the next n bytes, returning the number of bytes discarded.
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
) {
165 return 0, ErrNegativeCount
186 return n
- remain
, b
.readErr()
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
) {
200 if b
.Buffered() > 0 {
203 return 0, b
.readErr()
207 return 0, b
.readErr()
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
)
214 panic(errNegativeRead
)
217 b
.lastByte
= int(p
[n
-1])
220 return n
, b
.readErr()
223 // Do not use b.fill, which will loop.
226 n
, b
.err
= b
.rd
.Read(b
.buf
)
228 panic(errNegativeRead
)
231 return 0, b
.readErr()
236 // copy as much as we can
237 n
= copy(p
, b
.buf
[b
.r
:b
.w
])
239 b
.lastByte
= int(b
.buf
[b
.r
-1])
244 // ReadByte reads and returns a single byte.
245 // If no byte is available, returns an error.
246 func (b
*Reader
) ReadByte() (byte, error
) {
250 return 0, b
.readErr()
252 b
.fill() // buffer is empty
260 // UnreadByte unreads the last byte. Only the most recently read byte can be unread.
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
265 func (b
*Reader
) UnreadByte() error
{
266 if b
.lastByte
< 0 || b
.r
== 0 && b
.w
> 0 {
267 return ErrInvalidUnreadByte
269 // b.r > 0 || b.w == 0
273 // b.r == 0 && b.w == 0
276 b
.buf
[b
.r
] = byte(b
.lastByte
)
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.
285 func (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
291 return 0, 0, b
.readErr()
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
])
298 b
.lastByte
= int(b
.buf
[b
.r
-1])
299 b
.lastRuneSize
= size
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.)
307 func (b
*Reader
) UnreadRune() error
{
308 if b
.lastRuneSize
< 0 || b
.r
< b
.lastRuneSize
{
309 return ErrInvalidUnreadRune
311 b
.r
-= b
.lastRuneSize
317 // Buffered returns the number of bytes that can be read from the current buffer.
318 func (b
*Reader
) Buffered() int { return b
.w
- b
.r
}
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.
330 func (b
*Reader
) ReadSlice(delim
byte) (line
[]byte, err error
) {
331 s
:= 0 // search start index
334 if i
:= bytes
.IndexByte(b
.buf
[b
.r
+s
:b
.w
], delim
); i
>= 0 {
336 line
= b
.buf
[b
.r
: b
.r
+i
+1]
343 line
= b
.buf
[b
.r
:b
.w
]
350 if b
.Buffered() >= len(b
.buf
) {
357 s
= b
.w
- b
.r
// do not rescan area we scanned before
359 b
.fill() // buffer is not full
362 // Handle last byte, if any.
363 if i
:= len(line
) - 1; i
>= 0 {
364 b
.lastByte
= int(line
[i
])
371 // ReadLine is a low-level line-reading primitive. Most callers should use
372 // ReadBytes('\n') or ReadString('\n') instead or use a Scanner.
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,
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.
387 func (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".
395 // should be unreachable
396 panic("bufio: tried to rewind past start of buffer")
399 line
= line
[:len(line
)-1]
401 return line
, true, nil
412 if line
[len(line
)-1] == '\n' {
414 if len(line
) > 1 && line
[len(line
)-2] == '\r' {
417 line
= line
[:len(line
)-drop
]
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
428 // For simple uses, a Scanner may be more convenient.
429 func (b
*Reader
) ReadBytes(delim
byte) ([]byte, error
) {
430 // Use ReadSlice to look for array,
431 // accumulating full buffers.
438 frag
, e
= b
.ReadSlice(delim
)
439 if e
== nil { // got final fragment
442 if e
!= ErrBufferFull
{ // unexpected error
447 // Make a copy of the buffer.
448 buf
:= make([]byte, len(frag
))
450 full
= append(full
, buf
)
456 // Allocate new buffer to hold the full pieces and the fragment.
457 buf
:= make([]byte, n
)
459 // Copy full pieces and fragment in.
460 for i
:= range full
{
461 n
+= copy(buf
[n
:], full
[i
])
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
473 // For simple uses, a Scanner may be more convenient.
474 func (b
*Reader
) ReadString(delim
byte) (string, error
) {
475 bytes
, err
:= b
.ReadBytes(delim
)
476 return string(bytes
), err
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.
483 func (b
*Reader
) WriteTo(w io
.Writer
) (n
int64, err error
) {
484 n
, err
= b
.writeBuf(w
)
489 if r
, ok
:= b
.rd
.(io
.WriterTo
); ok
{
490 m
, err
:= r
.WriteTo(w
)
495 if w
, ok
:= w
.(io
.ReaderFrom
); ok
{
496 m
, err
:= w
.ReadFrom(b
.rd
)
501 if b
.w
-b
.r
< len(b
.buf
) {
502 b
.fill() // buffer not full
506 // b.r < b.w => buffer is not empty
507 m
, err
:= b
.writeBuf(w
)
512 b
.fill() // buffer is empty
519 return n
, b
.readErr()
522 var errNegativeWrite
= errors
.New("bufio: writer returned negative count from Write")
524 // writeBuf writes the Reader's buffer to the writer.
525 func (b
*Reader
) writeBuf(w io
.Writer
) (int64, error
) {
526 n
, err
:= w
.Write(b
.buf
[b
.r
:b
.w
])
528 panic(errNegativeWrite
)
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.
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.
552 func NewWriterSize(w io
.Writer
, size
int) *Writer
{
553 // Is it already a Writer?
555 if ok
&& len(b
.buf
) >= size
{
559 size
= defaultBufSize
562 buf
: make([]byte, size
),
567 // NewWriter returns a new Writer whose buffer has the default size.
568 func NewWriter(w io
.Writer
) *Writer
{
569 return NewWriterSize(w
, defaultBufSize
)
572 // Size returns the size of the underlying buffer in bytes.
573 func (b
*Writer
) Size() int { return len(b
.buf
) }
575 // Reset discards any unflushed buffered data, clears any error, and
576 // resets b to write its output to w.
577 func (b
*Writer
) Reset(w io
.Writer
) {
583 // Flush writes any buffered data to the underlying io.Writer.
584 func (b
*Writer
) Flush() error
{
591 n
, err
:= b
.wr
.Write(b
.buf
[0:b
.n
])
592 if n
< b
.n
&& err
== nil {
593 err
= io
.ErrShortWrite
596 if n
> 0 && n
< b
.n
{
597 copy(b
.buf
[0:b
.n
-n
], b
.buf
[n
:b
.n
])
607 // Available returns how many bytes are unused in the buffer.
608 func (b
*Writer
) Available() int { return len(b
.buf
) - b
.n
}
610 // Buffered returns the number of bytes that have been written into the current buffer.
611 func (b
*Writer
) Buffered() int { return b
.n
}
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.
617 func (b
*Writer
) Write(p
[]byte) (nn
int, err error
) {
618 for len(p
) > b
.Available() && b
.err
== nil {
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
)
625 n
= copy(b
.buf
[b
.n
:], p
)
635 n
:= copy(b
.buf
[b
.n
:], p
)
641 // WriteByte writes a single byte.
642 func (b
*Writer
) WriteByte(c
byte) error
{
646 if b
.Available() <= 0 && b
.Flush() != nil {
654 // WriteRune writes a single Unicode code point, returning
655 // the number of bytes written and any error.
656 func (b
*Writer
) WriteRune(r rune
) (size
int, err error
) {
657 if r
< utf8
.RuneSelf
{
658 err
= b
.WriteByte(byte(r
))
669 if b
.Flush(); b
.err
!= nil {
674 // Can only happen if buffer is silly small.
675 return b
.WriteString(string(r
))
678 size
= utf8
.EncodeRune(b
.buf
[b
.n
:], r
)
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.
687 func (b
*Writer
) WriteString(s
string) (int, error
) {
689 for len(s
) > b
.Available() && b
.err
== nil {
690 n
:= copy(b
.buf
[b
.n
:], s
)
699 n
:= copy(b
.buf
[b
.n
:], s
)
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.
708 func (b
*Writer
) ReadFrom(r io
.Reader
) (n
int64, err error
) {
712 if b
.Buffered() == 0 {
713 if w
, ok
:= b
.wr
.(io
.ReaderFrom
); ok
{
714 n
, err
= w
.ReadFrom(r
)
721 if b
.Available() == 0 {
722 if err1
:= b
.Flush(); err1
!= nil {
727 for nr
< maxConsecutiveEmptyReads
{
728 m
, err
= r
.Read(b
.buf
[b
.n
:])
729 if m
!= 0 || err
!= nil {
734 if nr
== maxConsecutiveEmptyReads
{
735 return n
, io
.ErrNoProgress
744 // If we filled the buffer exactly, flush preemptively.
745 if b
.Available() == 0 {
754 // buffered input and output
756 // ReadWriter stores pointers to a Reader and a Writer.
757 // It implements io.ReadWriter.
758 type ReadWriter
struct {
763 // NewReadWriter allocates a new ReadWriter that dispatches to r and w.
764 func NewReadWriter(r
*Reader
, w
*Writer
) *ReadWriter
{
765 return &ReadWriter
{r
, w
}