Source file src/pkg/bufio/bufio.go
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
34 r, w int
35 err error
36 lastByte int
37 lastRuneSize int
38 }
39
40 const minReadBufferSize = 16
41
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?
47 b, ok := rd.(*Reader)
48 if ok && len(b.buf) >= size {
49 return b
50 }
51 if size < minReadBufferSize {
52 size = minReadBufferSize
53 }
54 return &Reader{
55 buf: make([]byte, size),
56 rd: rd,
57 lastByte: -1,
58 lastRuneSize: -1,
59 }
60 }
61
62 // NewReader returns a new Reader whose buffer has the default size.
63 func NewReader(rd io.Reader) *Reader {
64 return NewReaderSize(rd, defaultBufSize)
65 }
66
67 // fill reads a new chunk into the buffer.
68 func (b *Reader) fill() {
69 // Slide existing data to beginning.
70 if b.r > 0 {
71 copy(b.buf, b.buf[b.r:b.w])
72 b.w -= b.r
73 b.r = 0
74 }
75
76 // Read new data.
77 n, e := b.rd.Read(b.buf[b.w:])
78 b.w += n
79 if e != nil {
80 b.err = e
81 }
82 }
83
84 func (b *Reader) readErr() error {
85 err := b.err
86 b.err = nil
87 return err
88 }
89
90 // Peek returns the next n bytes without advancing the reader. The bytes stop
91 // being valid at the next read call. If Peek returns fewer than n bytes, it
92 // also returns an error explaining why the read is short. The error is
93 // ErrBufferFull if n is larger than b's buffer size.
94 func (b *Reader) Peek(n int) ([]byte, error) {
95 if n < 0 {
96 return nil, ErrNegativeCount
97 }
98 if n > len(b.buf) {
99 return nil, ErrBufferFull
100 }
101 for b.w-b.r < n && b.err == nil {
102 b.fill()
103 }
104 m := b.w - b.r
105 if m > n {
106 m = n
107 }
108 var err error
109 if m < n {
110 err = b.readErr()
111 if err == nil {
112 err = ErrBufferFull
113 }
114 }
115 return b.buf[b.r : b.r+m], err
116 }
117
118 // Read reads data into p.
119 // It returns the number of bytes read into p.
120 // It calls Read at most once on the underlying Reader,
121 // hence n may be less than len(p).
122 // At EOF, the count will be zero and err will be io.EOF.
123 func (b *Reader) Read(p []byte) (n int, err error) {
124 n = len(p)
125 if n == 0 {
126 return 0, b.readErr()
127 }
128 if b.w == b.r {
129 if b.err != nil {
130 return 0, b.readErr()
131 }
132 if len(p) >= len(b.buf) {
133 // Large read, empty buffer.
134 // Read directly into p to avoid copy.
135 n, b.err = b.rd.Read(p)
136 if n > 0 {
137 b.lastByte = int(p[n-1])
138 b.lastRuneSize = -1
139 }
140 return n, b.readErr()
141 }
142 b.fill()
143 if b.w == b.r {
144 return 0, b.readErr()
145 }
146 }
147
148 if n > b.w-b.r {
149 n = b.w - b.r
150 }
151 copy(p[0:n], b.buf[b.r:])
152 b.r += n
153 b.lastByte = int(b.buf[b.r-1])
154 b.lastRuneSize = -1
155 return n, nil
156 }
157
158 // ReadByte reads and returns a single byte.
159 // If no byte is available, returns an error.
160 func (b *Reader) ReadByte() (c byte, err error) {
161 b.lastRuneSize = -1
162 for b.w == b.r {
163 if b.err != nil {
164 return 0, b.readErr()
165 }
166 b.fill()
167 }
168 c = b.buf[b.r]
169 b.r++
170 b.lastByte = int(c)
171 return c, nil
172 }
173
174 // UnreadByte unreads the last byte. Only the most recently read byte can be unread.
175 func (b *Reader) UnreadByte() error {
176 b.lastRuneSize = -1
177 if b.r == b.w && b.lastByte >= 0 {
178 b.w = 1
179 b.r = 0
180 b.buf[0] = byte(b.lastByte)
181 b.lastByte = -1
182 return nil
183 }
184 if b.r <= 0 {
185 return ErrInvalidUnreadByte
186 }
187 b.r--
188 b.lastByte = -1
189 return nil
190 }
191
192 // ReadRune reads a single UTF-8 encoded Unicode character and returns the
193 // rune and its size in bytes. If the encoded rune is invalid, it consumes one byte
194 // and returns unicode.ReplacementChar (U+FFFD) with a size of 1.
195 func (b *Reader) ReadRune() (r rune, size int, err error) {
196 for b.r+utf8.UTFMax > b.w && !utf8.FullRune(b.buf[b.r:b.w]) && b.err == nil {
197 b.fill()
198 }
199 b.lastRuneSize = -1
200 if b.r == b.w {
201 return 0, 0, b.readErr()
202 }
203 r, size = rune(b.buf[b.r]), 1
204 if r >= 0x80 {
205 r, size = utf8.DecodeRune(b.buf[b.r:b.w])
206 }
207 b.r += size
208 b.lastByte = int(b.buf[b.r-1])
209 b.lastRuneSize = size
210 return r, size, nil
211 }
212
213 // UnreadRune unreads the last rune. If the most recent read operation on
214 // the buffer was not a ReadRune, UnreadRune returns an error. (In this
215 // regard it is stricter than UnreadByte, which will unread the last byte
216 // from any read operation.)
217 func (b *Reader) UnreadRune() error {
218 if b.lastRuneSize < 0 || b.r == 0 {
219 return ErrInvalidUnreadRune
220 }
221 b.r -= b.lastRuneSize
222 b.lastByte = -1
223 b.lastRuneSize = -1
224 return nil
225 }
226
227 // Buffered returns the number of bytes that can be read from the current buffer.
228 func (b *Reader) Buffered() int { return b.w - b.r }
229
230 // ReadSlice reads until the first occurrence of delim in the input,
231 // returning a slice pointing at the bytes in the buffer.
232 // The bytes stop being valid at the next read call.
233 // If ReadSlice encounters an error before finding a delimiter,
234 // it returns all the data in the buffer and the error itself (often io.EOF).
235 // ReadSlice fails with error ErrBufferFull if the buffer fills without a delim.
236 // Because the data returned from ReadSlice will be overwritten
237 // by the next I/O operation, most clients should use
238 // ReadBytes or ReadString instead.
239 // ReadSlice returns err != nil if and only if line does not end in delim.
240 func (b *Reader) ReadSlice(delim byte) (line []byte, err error) {
241 // Look in buffer.
242 if i := bytes.IndexByte(b.buf[b.r:b.w], delim); i >= 0 {
243 line1 := b.buf[b.r : b.r+i+1]
244 b.r += i + 1
245 return line1, nil
246 }
247
248 // Read more into buffer, until buffer fills or we find delim.
249 for {
250 if b.err != nil {
251 line := b.buf[b.r:b.w]
252 b.r = b.w
253 return line, b.readErr()
254 }
255
256 n := b.Buffered()
257 b.fill()
258
259 // Search new part of buffer
260 if i := bytes.IndexByte(b.buf[n:b.w], delim); i >= 0 {
261 line := b.buf[0 : n+i+1]
262 b.r = n + i + 1
263 return line, nil
264 }
265
266 // Buffer is full?
267 if b.Buffered() >= len(b.buf) {
268 b.r = b.w
269 return b.buf, ErrBufferFull
270 }
271 }
272 panic("not reached")
273 }
274
275 // ReadLine tries to return a single line, not including the end-of-line bytes.
276 // If the line was too long for the buffer then isPrefix is set and the
277 // beginning of the line is returned. The rest of the line will be returned
278 // from future calls. isPrefix will be false when returning the last fragment
279 // of the line. The returned buffer is only valid until the next call to
280 // ReadLine. ReadLine either returns a non-nil line or it returns an error,
281 // never both.
282 func (b *Reader) ReadLine() (line []byte, isPrefix bool, err error) {
283 line, err = b.ReadSlice('\n')
284 if err == ErrBufferFull {
285 // Handle the case where "\r\n" straddles the buffer.
286 if len(line) > 0 && line[len(line)-1] == '\r' {
287 // Put the '\r' back on buf and drop it from line.
288 // Let the next call to ReadLine check for "\r\n".
289 if b.r == 0 {
290 // should be unreachable
291 panic("bufio: tried to rewind past start of buffer")
292 }
293 b.r--
294 line = line[:len(line)-1]
295 }
296 return line, true, nil
297 }
298
299 if len(line) == 0 {
300 if err != nil {
301 line = nil
302 }
303 return
304 }
305 err = nil
306
307 if line[len(line)-1] == '\n' {
308 drop := 1
309 if len(line) > 1 && line[len(line)-2] == '\r' {
310 drop = 2
311 }
312 line = line[:len(line)-drop]
313 }
314 return
315 }
316
317 // ReadBytes reads until the first occurrence of delim in the input,
318 // returning a slice containing the data up to and including the delimiter.
319 // If ReadBytes encounters an error before finding a delimiter,
320 // it returns the data read before the error and the error itself (often io.EOF).
321 // ReadBytes returns err != nil if and only if the returned data does not end in
322 // delim.
323 func (b *Reader) ReadBytes(delim byte) (line []byte, err error) {
324 // Use ReadSlice to look for array,
325 // accumulating full buffers.
326 var frag []byte
327 var full [][]byte
328 err = nil
329
330 for {
331 var e error
332 frag, e = b.ReadSlice(delim)
333 if e == nil { // got final fragment
334 break
335 }
336 if e != ErrBufferFull { // unexpected error
337 err = e
338 break
339 }
340
341 // Make a copy of the buffer.
342 buf := make([]byte, len(frag))
343 copy(buf, frag)
344 full = append(full, buf)
345 }
346
347 // Allocate new buffer to hold the full pieces and the fragment.
348 n := 0
349 for i := range full {
350 n += len(full[i])
351 }
352 n += len(frag)
353
354 // Copy full pieces and fragment in.
355 buf := make([]byte, n)
356 n = 0
357 for i := range full {
358 n += copy(buf[n:], full[i])
359 }
360 copy(buf[n:], frag)
361 return buf, err
362 }
363
364 // ReadString reads until the first occurrence of delim in the input,
365 // returning a string containing the data up to and including the delimiter.
366 // If ReadString encounters an error before finding a delimiter,
367 // it returns the data read before the error and the error itself (often io.EOF).
368 // ReadString returns err != nil if and only if the returned data does not end in
369 // delim.
370 func (b *Reader) ReadString(delim byte) (line string, err error) {
371 bytes, e := b.ReadBytes(delim)
372 return string(bytes), e
373 }
374
375 // buffered output
376
377 // Writer implements buffering for an io.Writer object.
378 // If an error occurs writing to a Writer, no more data will be
379 // accepted and all subsequent writes will return the error.
380 type Writer struct {
381 err error
382 buf []byte
383 n int
384 wr io.Writer
385 }
386
387 // NewWriterSize returns a new Writer whose buffer has at least the specified
388 // size. If the argument io.Writer is already a Writer with large enough
389 // size, it returns the underlying Writer.
390 func NewWriterSize(wr io.Writer, size int) *Writer {
391 // Is it already a Writer?
392 b, ok := wr.(*Writer)
393 if ok && len(b.buf) >= size {
394 return b
395 }
396 if size <= 0 {
397 size = defaultBufSize
398 }
399 b = new(Writer)
400 b.buf = make([]byte, size)
401 b.wr = wr
402 return b
403 }
404
405 // NewWriter returns a new Writer whose buffer has the default size.
406 func NewWriter(wr io.Writer) *Writer {
407 return NewWriterSize(wr, defaultBufSize)
408 }
409
410 // Flush writes any buffered data to the underlying io.Writer.
411 func (b *Writer) Flush() error {
412 if b.err != nil {
413 return b.err
414 }
415 if b.n == 0 {
416 return nil
417 }
418 n, e := b.wr.Write(b.buf[0:b.n])
419 if n < b.n && e == nil {
420 e = io.ErrShortWrite
421 }
422 if e != nil {
423 if n > 0 && n < b.n {
424 copy(b.buf[0:b.n-n], b.buf[n:b.n])
425 }
426 b.n -= n
427 b.err = e
428 return e
429 }
430 b.n = 0
431 return nil
432 }
433
434 // Available returns how many bytes are unused in the buffer.
435 func (b *Writer) Available() int { return len(b.buf) - b.n }
436
437 // Buffered returns the number of bytes that have been written into the current buffer.
438 func (b *Writer) Buffered() int { return b.n }
439
440 // Write writes the contents of p into the buffer.
441 // It returns the number of bytes written.
442 // If nn < len(p), it also returns an error explaining
443 // why the write is short.
444 func (b *Writer) Write(p []byte) (nn int, err error) {
445 for len(p) > b.Available() && b.err == nil {
446 var n int
447 if b.Buffered() == 0 {
448 // Large write, empty buffer.
449 // Write directly from p to avoid copy.
450 n, b.err = b.wr.Write(p)
451 } else {
452 n = copy(b.buf[b.n:], p)
453 b.n += n
454 b.Flush()
455 }
456 nn += n
457 p = p[n:]
458 }
459 if b.err != nil {
460 return nn, b.err
461 }
462 n := copy(b.buf[b.n:], p)
463 b.n += n
464 nn += n
465 return nn, nil
466 }
467
468 // WriteByte writes a single byte.
469 func (b *Writer) WriteByte(c byte) error {
470 if b.err != nil {
471 return b.err
472 }
473 if b.Available() <= 0 && b.Flush() != nil {
474 return b.err
475 }
476 b.buf[b.n] = c
477 b.n++
478 return nil
479 }
480
481 // WriteRune writes a single Unicode code point, returning
482 // the number of bytes written and any error.
483 func (b *Writer) WriteRune(r rune) (size int, err error) {
484 if r < utf8.RuneSelf {
485 err = b.WriteByte(byte(r))
486 if err != nil {
487 return 0, err
488 }
489 return 1, nil
490 }
491 if b.err != nil {
492 return 0, b.err
493 }
494 n := b.Available()
495 if n < utf8.UTFMax {
496 if b.Flush(); b.err != nil {
497 return 0, b.err
498 }
499 n = b.Available()
500 if n < utf8.UTFMax {
501 // Can only happen if buffer is silly small.
502 return b.WriteString(string(r))
503 }
504 }
505 size = utf8.EncodeRune(b.buf[b.n:], r)
506 b.n += size
507 return size, nil
508 }
509
510 // WriteString writes a string.
511 // It returns the number of bytes written.
512 // If the count is less than len(s), it also returns an error explaining
513 // why the write is short.
514 func (b *Writer) WriteString(s string) (int, error) {
515 nn := 0
516 for len(s) > b.Available() && b.err == nil {
517 n := copy(b.buf[b.n:], s)
518 b.n += n
519 nn += n
520 s = s[n:]
521 b.Flush()
522 }
523 if b.err != nil {
524 return nn, b.err
525 }
526 n := copy(b.buf[b.n:], s)
527 b.n += n
528 nn += n
529 return nn, nil
530 }
531
532 // buffered input and output
533
534 // ReadWriter stores pointers to a Reader and a Writer.
535 // It implements io.ReadWriter.
536 type ReadWriter struct {
537 *Reader
538 *Writer
539 }
540
541 // NewReadWriter allocates a new ReadWriter that dispatches to r and w.
542 func NewReadWriter(r *Reader, w *Writer) *ReadWriter {
543 return &ReadWriter{r, w}
544 }