The Go Programming Language

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

release.r60.3. Except as noted, this content is licensed under a Creative Commons Attribution 3.0 License.