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 }