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.
40 const minReadBufferSize
= 16
42 // NewReaderSize returns a new Reader whose buffer has at least the specified
43 // size. If the argument io.Reader is already a Reader with large enough
44 // size, it returns the underlying Reader.
45 func NewReaderSize(rd io
.Reader
, size
int) *Reader
{
46 // Is it already a Reader?
48 if ok
&& len(b
.buf
) >= size
{
51 if size
< minReadBufferSize
{
52 size
= minReadBufferSize
55 r
.reset(make([]byte, size
), rd
)
59 // NewReader returns a new Reader whose buffer has the default size.
60 func NewReader(rd io
.Reader
) *Reader
{
61 return NewReaderSize(rd
, defaultBufSize
)
64 // Reset discards any buffered data, resets all state, and switches
65 // the buffered reader to read from r.
66 func (b
*Reader
) Reset(r io
.Reader
) {
70 func (b
*Reader
) reset(buf
[]byte, r io
.Reader
) {
79 var errNegativeRead
= errors
.New("bufio: reader returned negative count from Read")
81 // fill reads a new chunk into the buffer.
82 func (b
*Reader
) fill() {
83 // Slide existing data to beginning.
85 copy(b
.buf
, b
.buf
[b
.r
:b
.w
])
91 n
, err
:= b
.rd
.Read(b
.buf
[b
.w
:])
93 panic(errNegativeRead
)
101 func (b
*Reader
) readErr() error
{
107 // Peek returns the next n bytes without advancing the reader. The bytes stop
108 // being valid at the next read call. If Peek returns fewer than n bytes, it
109 // also returns an error explaining why the read is short. The error is
110 // ErrBufferFull if n is larger than b's buffer size.
111 func (b
*Reader
) Peek(n
int) ([]byte, error
) {
113 return nil, ErrNegativeCount
116 return nil, ErrBufferFull
118 for b
.w
-b
.r
< n
&& b
.err
== nil {
132 return b
.buf
[b
.r
: b
.r
+m
], err
135 // Read reads data into p.
136 // It returns the number of bytes read into p.
137 // It calls Read at most once on the underlying Reader,
138 // hence n may be less than len(p).
139 // At EOF, the count will be zero and err will be io.EOF.
140 func (b
*Reader
) Read(p
[]byte) (n
int, err error
) {
143 return 0, b
.readErr()
147 return 0, b
.readErr()
149 if len(p
) >= len(b
.buf
) {
150 // Large read, empty buffer.
151 // Read directly into p to avoid copy.
152 n
, b
.err
= b
.rd
.Read(p
)
154 b
.lastByte
= int(p
[n
-1])
157 return n
, b
.readErr()
161 return 0, b
.readErr()
168 copy(p
[0:n
], b
.buf
[b
.r
:])
170 b
.lastByte
= int(b
.buf
[b
.r
-1])
175 // ReadByte reads and returns a single byte.
176 // If no byte is available, returns an error.
177 func (b
*Reader
) ReadByte() (c
byte, err error
) {
181 return 0, b
.readErr()
191 // UnreadByte unreads the last byte. Only the most recently read byte can be unread.
192 func (b
*Reader
) UnreadByte() error
{
194 if b
.r
== b
.w
&& b
.lastByte
>= 0 {
197 b
.buf
[0] = byte(b
.lastByte
)
202 return ErrInvalidUnreadByte
209 // ReadRune reads a single UTF-8 encoded Unicode character and returns the
210 // rune and its size in bytes. If the encoded rune is invalid, it consumes one byte
211 // and returns unicode.ReplacementChar (U+FFFD) with a size of 1.
212 func (b
*Reader
) ReadRune() (r rune
, size
int, err error
) {
213 for b
.r
+utf8
.UTFMax
> b
.w
&& !utf8
.FullRune(b
.buf
[b
.r
:b
.w
]) && b
.err
== nil {
218 return 0, 0, b
.readErr()
220 r
, size
= rune(b
.buf
[b
.r
]), 1
222 r
, size
= utf8
.DecodeRune(b
.buf
[b
.r
:b
.w
])
225 b
.lastByte
= int(b
.buf
[b
.r
-1])
226 b
.lastRuneSize
= size
230 // UnreadRune unreads the last rune. If the most recent read operation on
231 // the buffer was not a ReadRune, UnreadRune returns an error. (In this
232 // regard it is stricter than UnreadByte, which will unread the last byte
233 // from any read operation.)
234 func (b
*Reader
) UnreadRune() error
{
235 if b
.lastRuneSize
< 0 || b
.r
== 0 {
236 return ErrInvalidUnreadRune
238 b
.r
-= b
.lastRuneSize
244 // Buffered returns the number of bytes that can be read from the current buffer.
245 func (b
*Reader
) Buffered() int { return b
.w
- b
.r
}
247 // ReadSlice reads until the first occurrence of delim in the input,
248 // returning a slice pointing at the bytes in the buffer.
249 // The bytes stop being valid at the next read.
250 // If ReadSlice encounters an error before finding a delimiter,
251 // it returns all the data in the buffer and the error itself (often io.EOF).
252 // ReadSlice fails with error ErrBufferFull if the buffer fills without a delim.
253 // Because the data returned from ReadSlice will be overwritten
254 // by the next I/O operation, most clients should use
255 // ReadBytes or ReadString instead.
256 // ReadSlice returns err != nil if and only if line does not end in delim.
257 func (b
*Reader
) ReadSlice(delim
byte) (line
[]byte, err error
) {
259 if i
:= bytes
.IndexByte(b
.buf
[b
.r
:b
.w
], delim
); i
>= 0 {
260 line1
:= b
.buf
[b
.r
: b
.r
+i
+1]
265 // Read more into buffer, until buffer fills or we find delim.
268 line
:= b
.buf
[b
.r
:b
.w
]
270 return line
, b
.readErr()
276 // Search new part of buffer
277 if i
:= bytes
.IndexByte(b
.buf
[n
:b
.w
], delim
); i
>= 0 {
278 line
:= b
.buf
[0 : n
+i
+1]
284 if b
.Buffered() >= len(b
.buf
) {
286 return b
.buf
, ErrBufferFull
291 // ReadLine is a low-level line-reading primitive. Most callers should use
292 // ReadBytes('\n') or ReadString('\n') instead or use a Scanner.
294 // ReadLine tries to return a single line, not including the end-of-line bytes.
295 // If the line was too long for the buffer then isPrefix is set and the
296 // beginning of the line is returned. The rest of the line will be returned
297 // from future calls. isPrefix will be false when returning the last fragment
298 // of the line. The returned buffer is only valid until the next call to
299 // ReadLine. ReadLine either returns a non-nil line or it returns an error,
302 // The text returned from ReadLine does not include the line end ("\r\n" or "\n").
303 // No indication or error is given if the input ends without a final line end.
304 func (b
*Reader
) ReadLine() (line
[]byte, isPrefix
bool, err error
) {
305 line
, err
= b
.ReadSlice('\n')
306 if err
== ErrBufferFull
{
307 // Handle the case where "\r\n" straddles the buffer.
308 if len(line
) > 0 && line
[len(line
)-1] == '\r' {
309 // Put the '\r' back on buf and drop it from line.
310 // Let the next call to ReadLine check for "\r\n".
312 // should be unreachable
313 panic("bufio: tried to rewind past start of buffer")
316 line
= line
[:len(line
)-1]
318 return line
, true, nil
329 if line
[len(line
)-1] == '\n' {
331 if len(line
) > 1 && line
[len(line
)-2] == '\r' {
334 line
= line
[:len(line
)-drop
]
339 // ReadBytes reads until the first occurrence of delim in the input,
340 // returning a slice containing the data up to and including the delimiter.
341 // If ReadBytes encounters an error before finding a delimiter,
342 // it returns the data read before the error and the error itself (often io.EOF).
343 // ReadBytes returns err != nil if and only if the returned data does not end in
345 // For simple uses, a Scanner may be more convenient.
346 func (b
*Reader
) ReadBytes(delim
byte) (line
[]byte, err error
) {
347 // Use ReadSlice to look for array,
348 // accumulating full buffers.
355 frag
, e
= b
.ReadSlice(delim
)
356 if e
== nil { // got final fragment
359 if e
!= ErrBufferFull
{ // unexpected error
364 // Make a copy of the buffer.
365 buf
:= make([]byte, len(frag
))
367 full
= append(full
, buf
)
370 // Allocate new buffer to hold the full pieces and the fragment.
372 for i
:= range full
{
377 // Copy full pieces and fragment in.
378 buf
:= make([]byte, n
)
380 for i
:= range full
{
381 n
+= copy(buf
[n
:], full
[i
])
387 // ReadString reads until the first occurrence of delim in the input,
388 // returning a string containing the data up to and including the delimiter.
389 // If ReadString encounters an error before finding a delimiter,
390 // it returns the data read before the error and the error itself (often io.EOF).
391 // ReadString returns err != nil if and only if the returned data does not end in
393 // For simple uses, a Scanner may be more convenient.
394 func (b
*Reader
) ReadString(delim
byte) (line
string, err error
) {
395 bytes
, err
:= b
.ReadBytes(delim
)
400 // WriteTo implements io.WriterTo.
401 func (b
*Reader
) WriteTo(w io
.Writer
) (n
int64, err error
) {
402 n
, err
= b
.writeBuf(w
)
407 if r
, ok
:= b
.rd
.(io
.WriterTo
); ok
{
408 m
, err
:= r
.WriteTo(w
)
413 for b
.fill(); b
.r
< b
.w
; b
.fill() {
414 m
, err
:= b
.writeBuf(w
)
425 return n
, b
.readErr()
428 // writeBuf writes the Reader's buffer to the writer.
429 func (b
*Reader
) writeBuf(w io
.Writer
) (int64, error
) {
430 n
, err
:= w
.Write(b
.buf
[b
.r
:b
.w
])
437 // Writer implements buffering for an io.Writer object.
438 // If an error occurs writing to a Writer, no more data will be
439 // accepted and all subsequent writes will return the error.
440 // After all data has been written, the client should call the
441 // Flush method to guarantee all data has been forwarded to
442 // the underlying io.Writer.
450 // NewWriterSize returns a new Writer whose buffer has at least the specified
451 // size. If the argument io.Writer is already a Writer with large enough
452 // size, it returns the underlying Writer.
453 func NewWriterSize(w io
.Writer
, size
int) *Writer
{
454 // Is it already a Writer?
456 if ok
&& len(b
.buf
) >= size
{
460 size
= defaultBufSize
463 buf
: make([]byte, size
),
468 // NewWriter returns a new Writer whose buffer has the default size.
469 func NewWriter(w io
.Writer
) *Writer
{
470 return NewWriterSize(w
, defaultBufSize
)
473 // Reset discards any unflushed buffered data, clears any error, and
474 // resets b to write its output to w.
475 func (b
*Writer
) Reset(w io
.Writer
) {
481 // Flush writes any buffered data to the underlying io.Writer.
482 func (b
*Writer
) Flush() error
{
487 func (b
*Writer
) flush() error
{
494 n
, err
:= b
.wr
.Write(b
.buf
[0:b
.n
])
495 if n
< b
.n
&& err
== nil {
496 err
= io
.ErrShortWrite
499 if n
> 0 && n
< b
.n
{
500 copy(b
.buf
[0:b
.n
-n
], b
.buf
[n
:b
.n
])
510 // Available returns how many bytes are unused in the buffer.
511 func (b
*Writer
) Available() int { return len(b
.buf
) - b
.n
}
513 // Buffered returns the number of bytes that have been written into the current buffer.
514 func (b
*Writer
) Buffered() int { return b
.n
}
516 // Write writes the contents of p into the buffer.
517 // It returns the number of bytes written.
518 // If nn < len(p), it also returns an error explaining
519 // why the write is short.
520 func (b
*Writer
) Write(p
[]byte) (nn
int, err error
) {
521 for len(p
) > b
.Available() && b
.err
== nil {
523 if b
.Buffered() == 0 {
524 // Large write, empty buffer.
525 // Write directly from p to avoid copy.
526 n
, b
.err
= b
.wr
.Write(p
)
528 n
= copy(b
.buf
[b
.n
:], p
)
538 n
:= copy(b
.buf
[b
.n
:], p
)
544 // WriteByte writes a single byte.
545 func (b
*Writer
) WriteByte(c
byte) error
{
549 if b
.Available() <= 0 && b
.flush() != nil {
557 // WriteRune writes a single Unicode code point, returning
558 // the number of bytes written and any error.
559 func (b
*Writer
) WriteRune(r rune
) (size
int, err error
) {
560 if r
< utf8
.RuneSelf
{
561 err
= b
.WriteByte(byte(r
))
572 if b
.flush(); b
.err
!= nil {
577 // Can only happen if buffer is silly small.
578 return b
.WriteString(string(r
))
581 size
= utf8
.EncodeRune(b
.buf
[b
.n
:], r
)
586 // WriteString writes a string.
587 // It returns the number of bytes written.
588 // If the count is less than len(s), it also returns an error explaining
589 // why the write is short.
590 func (b
*Writer
) WriteString(s
string) (int, error
) {
592 for len(s
) > b
.Available() && b
.err
== nil {
593 n
:= copy(b
.buf
[b
.n
:], s
)
602 n
:= copy(b
.buf
[b
.n
:], s
)
608 // ReadFrom implements io.ReaderFrom.
609 func (b
*Writer
) ReadFrom(r io
.Reader
) (n
int64, err error
) {
610 if b
.Buffered() == 0 {
611 if w
, ok
:= b
.wr
.(io
.ReaderFrom
); ok
{
617 if b
.Available() == 0 {
618 if err1
:= b
.flush(); err1
!= nil {
622 m
, err
= r
.Read(b
.buf
[b
.n
:])
633 // If we filled the buffer exactly, flush pre-emptively.
634 if b
.Available() == 0 {
643 // buffered input and output
645 // ReadWriter stores pointers to a Reader and a Writer.
646 // It implements io.ReadWriter.
647 type ReadWriter
struct {
652 // NewReadWriter allocates a new ReadWriter that dispatches to r and w.
653 func NewReadWriter(r
*Reader
, w
*Writer
) *ReadWriter
{
654 return &ReadWriter
{r
, w
}