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

View as plain text