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.
21 // Errors introduced by this package.
26 func (err *Error) Error() string { return err.ErrorString }
29 ErrInvalidUnreadByte error = &Error{"bufio: invalid use of UnreadByte"}
30 ErrInvalidUnreadRune error = &Error{"bufio: invalid use of UnreadRune"}
31 ErrBufferFull error = &Error{"bufio: buffer full"}
32 ErrNegativeCount error = &Error{"bufio: negative count"}
33 errInternal error = &Error{"bufio: internal error"}
36 // BufSizeError is the error representing an invalid buffer size.
39 func (b BufSizeError) Error() string {
40 return "bufio: bad buffer size " + strconv.Itoa(int(b))
45 // Reader implements buffering for an io.Reader object.
55 // NewReaderSize creates a new Reader whose buffer has the specified size,
56 // which must be greater than one. If the argument io.Reader is already a
57 // Reader with large enough size, it returns the underlying Reader.
58 // It returns the Reader and any error.
59 func NewReaderSize(rd io.Reader, size int) (*Reader, error) {
61 return nil, BufSizeError(size)
63 // Is it already a Reader?
65 if ok && len(b.buf) >= size {
69 b.buf = make([]byte, size)
76 // NewReader returns a new Reader whose buffer has the default size.
77 func NewReader(rd io.Reader) *Reader {
78 b, err := NewReaderSize(rd, defaultBufSize)
80 // cannot happen - defaultBufSize is a valid size
86 // fill reads a new chunk into the buffer.
87 func (b *Reader) fill() {
88 // Slide existing data to beginning.
90 copy(b.buf, b.buf[b.r:b.w])
96 n, e := b.rd.Read(b.buf[b.w:])
103 func (b *Reader) readErr() error {
109 // Peek returns the next n bytes without advancing the reader. The bytes stop
110 // being valid at the next read call. If Peek returns fewer than n bytes, it
111 // also returns an error explaining why the read is short. The error is
112 // ErrBufferFull if n is larger than b's buffer size.
113 func (b *Reader) Peek(n int) ([]byte, error) {
115 return nil, ErrNegativeCount
118 return nil, ErrBufferFull
120 for b.w-b.r < n && b.err == nil {
128 if m < n && err == nil {
131 return b.buf[b.r : b.r+m], err
134 // Read reads data into p.
135 // It returns the number of bytes read into p.
136 // It calls Read at most once on the underlying Reader,
137 // hence n may be less than len(p).
138 // At EOF, the count will be zero and err will be io.EOF.
139 func (b *Reader) Read(p []byte) (n int, err error) {
142 return 0, b.readErr()
146 return 0, b.readErr()
148 if len(p) >= len(b.buf) {
149 // Large read, empty buffer.
150 // Read directly into p to avoid copy.
151 n, b.err = b.rd.Read(p)
153 b.lastByte = int(p[n-1])
156 return n, b.readErr()
160 return 0, b.readErr()
167 copy(p[0:n], b.buf[b.r:])
169 b.lastByte = int(b.buf[b.r-1])
174 // ReadByte reads and returns a single byte.
175 // If no byte is available, returns an error.
176 func (b *Reader) ReadByte() (c byte, err error) {
180 return 0, b.readErr()
190 // UnreadByte unreads the last byte. Only the most recently read byte can be unread.
191 func (b *Reader) UnreadByte() error {
193 if b.r == b.w && b.lastByte >= 0 {
196 b.buf[0] = byte(b.lastByte)
201 return ErrInvalidUnreadByte
208 // ReadRune reads a single UTF-8 encoded Unicode character and returns the
209 // rune and its size in bytes.
210 func (b *Reader) ReadRune() (r rune, size int, err error) {
211 for b.r+utf8.UTFMax > b.w && !utf8.FullRune(b.buf[b.r:b.w]) && b.err == nil {
216 return 0, 0, b.readErr()
218 r, size = rune(b.buf[b.r]), 1
220 r, size = utf8.DecodeRune(b.buf[b.r:b.w])
223 b.lastByte = int(b.buf[b.r-1])
224 b.lastRuneSize = size
228 // UnreadRune unreads the last rune. If the most recent read operation on
229 // the buffer was not a ReadRune, UnreadRune returns an error. (In this
230 // regard it is stricter than UnreadByte, which will unread the last byte
231 // from any read operation.)
232 func (b *Reader) UnreadRune() error {
233 if b.lastRuneSize < 0 || b.r == 0 {
234 return ErrInvalidUnreadRune
236 b.r -= b.lastRuneSize
242 // Buffered returns the number of bytes that can be read from the current buffer.
243 func (b *Reader) Buffered() int { return b.w - b.r }
245 // ReadSlice reads until the first occurrence of delim in the input,
246 // returning a slice pointing at the bytes in the buffer.
247 // The bytes stop being valid at the next read call.
248 // If ReadSlice encounters an error before finding a delimiter,
249 // it returns all the data in the buffer and the error itself (often io.EOF).
250 // ReadSlice fails with error ErrBufferFull if the buffer fills without a delim.
251 // Because the data returned from ReadSlice will be overwritten
252 // by the next I/O operation, most clients should use
253 // ReadBytes or ReadString instead.
254 // ReadSlice returns err != nil if and only if line does not end in delim.
255 func (b *Reader) ReadSlice(delim byte) (line []byte, err error) {
257 if i := bytes.IndexByte(b.buf[b.r:b.w], delim); i >= 0 {
258 line1 := b.buf[b.r : b.r+i+1]
263 // Read more into buffer, until buffer fills or we find delim.
266 line := b.buf[b.r:b.w]
268 return line, b.readErr()
274 // Search new part of buffer
275 if i := bytes.IndexByte(b.buf[n:b.w], delim); i >= 0 {
276 line := b.buf[0 : n+i+1]
282 if b.Buffered() >= len(b.buf) {
284 return b.buf, ErrBufferFull
290 // ReadLine tries to return a single line, not including the end-of-line bytes.
291 // If the line was too long for the buffer then isPrefix is set and the
292 // beginning of the line is returned. The rest of the line will be returned
293 // from future calls. isPrefix will be false when returning the last fragment
294 // of the line. The returned buffer is only valid until the next call to
295 // ReadLine. ReadLine either returns a non-nil line or it returns an error,
297 func (b *Reader) ReadLine() (line []byte, isPrefix bool, err error) {
298 line, err = b.ReadSlice('\n')
299 if err == ErrBufferFull {
300 // Handle the case where "\r\n" straddles the buffer.
301 if len(line) > 0 && line[len(line)-1] == '\r' {
302 // Put the '\r' back on buf and drop it from line.
303 // Let the next call to ReadLine check for "\r\n".
305 // should be unreachable
306 panic("bufio: tried to rewind past start of buffer")
309 line = line[:len(line)-1]
311 return line, true, nil
322 if line[len(line)-1] == '\n' {
324 if len(line) > 1 && line[len(line)-2] == '\r' {
327 line = line[:len(line)-drop]
332 // ReadBytes reads until the first occurrence of delim in the input,
333 // returning a slice containing the data up to and including the delimiter.
334 // If ReadBytes encounters an error before finding a delimiter,
335 // it returns the data read before the error and the error itself (often io.EOF).
336 // ReadBytes returns err != nil if and only if the returned data does not end in
338 func (b *Reader) ReadBytes(delim byte) (line []byte, err error) {
339 // Use ReadSlice to look for array,
340 // accumulating full buffers.
347 frag, e = b.ReadSlice(delim)
348 if e == nil { // got final fragment
351 if e != ErrBufferFull { // unexpected error
356 // Make a copy of the buffer.
357 buf := make([]byte, len(frag))
359 full = append(full, buf)
362 // Allocate new buffer to hold the full pieces and the fragment.
364 for i := range full {
369 // Copy full pieces and fragment in.
370 buf := make([]byte, n)
372 for i := range full {
373 n += copy(buf[n:], full[i])
379 // ReadString reads until the first occurrence of delim in the input,
380 // returning a string containing the data up to and including the delimiter.
381 // If ReadString encounters an error before finding a delimiter,
382 // it returns the data read before the error and the error itself (often io.EOF).
383 // ReadString returns err != nil if and only if the returned data does not end in
385 func (b *Reader) ReadString(delim byte) (line string, err error) {
386 bytes, e := b.ReadBytes(delim)
387 return string(bytes), e
392 // Writer implements buffering for an io.Writer object.
400 // NewWriterSize creates a new Writer whose buffer has the specified size,
401 // which must be greater than zero. If the argument io.Writer is already a
402 // Writer with large enough size, it returns the underlying Writer.
403 // It returns the Writer and any error.
404 func NewWriterSize(wr io.Writer, size int) (*Writer, error) {
406 return nil, BufSizeError(size)
408 // Is it already a Writer?
409 b, ok := wr.(*Writer)
410 if ok && len(b.buf) >= size {
414 b.buf = make([]byte, size)
419 // NewWriter returns a new Writer whose buffer has the default size.
420 func NewWriter(wr io.Writer) *Writer {
421 b, err := NewWriterSize(wr, defaultBufSize)
423 // cannot happen - defaultBufSize is valid size
429 // Flush writes any buffered data to the underlying io.Writer.
430 func (b *Writer) Flush() error {
437 n, e := b.wr.Write(b.buf[0:b.n])
438 if n < b.n && e == nil {
442 if n > 0 && n < b.n {
443 copy(b.buf[0:b.n-n], b.buf[n:b.n])
453 // Available returns how many bytes are unused in the buffer.
454 func (b *Writer) Available() int { return len(b.buf) - b.n }
456 // Buffered returns the number of bytes that have been written into the current buffer.
457 func (b *Writer) Buffered() int { return b.n }
459 // Write writes the contents of p into the buffer.
460 // It returns the number of bytes written.
461 // If nn < len(p), it also returns an error explaining
462 // why the write is short.
463 func (b *Writer) Write(p []byte) (nn int, err error) {
464 for len(p) > b.Available() && b.err == nil {
466 if b.Buffered() == 0 {
467 // Large write, empty buffer.
468 // Write directly from p to avoid copy.
469 n, b.err = b.wr.Write(p)
471 n = copy(b.buf[b.n:], p)
481 n := copy(b.buf[b.n:], p)
487 // WriteByte writes a single byte.
488 func (b *Writer) WriteByte(c byte) error {
492 if b.Available() <= 0 && b.Flush() != nil {
500 // WriteRune writes a single Unicode code point, returning
501 // the number of bytes written and any error.
502 func (b *Writer) WriteRune(r rune) (size int, err error) {
503 if r < utf8.RuneSelf {
504 err = b.WriteByte(byte(r))
515 if b.Flush(); b.err != nil {
520 // Can only happen if buffer is silly small.
521 return b.WriteString(string(r))
524 size = utf8.EncodeRune(b.buf[b.n:], r)
529 // WriteString writes a string.
530 // It returns the number of bytes written.
531 // If the count is less than len(s), it also returns an error explaining
532 // why the write is short.
533 func (b *Writer) WriteString(s string) (int, error) {
535 for len(s) > b.Available() && b.err == nil {
536 n := copy(b.buf[b.n:], s)
545 n := copy(b.buf[b.n:], s)
551 // buffered input and output
553 // ReadWriter stores pointers to a Reader and a Writer.
554 // It implements io.ReadWriter.
555 type ReadWriter struct {
560 // NewReadWriter allocates a new ReadWriter that dispatches to r and w.
561 func NewReadWriter(r *Reader, w *Writer) *ReadWriter {
562 return &ReadWriter{r, w}