Black Lives Matter. Support the Equal Justice Initiative.

Source file src/io/io.go

Documentation: io

     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 io provides basic interfaces to I/O primitives.
     6  // Its primary job is to wrap existing implementations of such primitives,
     7  // such as those in package os, into shared public interfaces that
     8  // abstract the functionality, plus some other related primitives.
     9  //
    10  // Because these interfaces and primitives wrap lower-level operations with
    11  // various implementations, unless otherwise informed clients should not
    12  // assume they are safe for parallel execution.
    13  package io
    14  
    15  import (
    16  	"errors"
    17  )
    18  
    19  // Seek whence values.
    20  const (
    21  	SeekStart   = 0 // seek relative to the origin of the file
    22  	SeekCurrent = 1 // seek relative to the current offset
    23  	SeekEnd     = 2 // seek relative to the end
    24  )
    25  
    26  // ErrShortWrite means that a write accepted fewer bytes than requested
    27  // but failed to return an explicit error.
    28  var ErrShortWrite = errors.New("short write")
    29  
    30  // ErrShortBuffer means that a read required a longer buffer than was provided.
    31  var ErrShortBuffer = errors.New("short buffer")
    32  
    33  // EOF is the error returned by Read when no more input is available.
    34  // Functions should return EOF only to signal a graceful end of input.
    35  // If the EOF occurs unexpectedly in a structured data stream,
    36  // the appropriate error is either ErrUnexpectedEOF or some other error
    37  // giving more detail.
    38  var EOF = errors.New("EOF")
    39  
    40  // ErrUnexpectedEOF means that EOF was encountered in the
    41  // middle of reading a fixed-size block or data structure.
    42  var ErrUnexpectedEOF = errors.New("unexpected EOF")
    43  
    44  // ErrNoProgress is returned by some clients of an io.Reader when
    45  // many calls to Read have failed to return any data or error,
    46  // usually the sign of a broken io.Reader implementation.
    47  var ErrNoProgress = errors.New("multiple Read calls return no data or error")
    48  
    49  // Reader is the interface that wraps the basic Read method.
    50  //
    51  // Read reads up to len(p) bytes into p. It returns the number of bytes
    52  // read (0 <= n <= len(p)) and any error encountered. Even if Read
    53  // returns n < len(p), it may use all of p as scratch space during the call.
    54  // If some data is available but not len(p) bytes, Read conventionally
    55  // returns what is available instead of waiting for more.
    56  //
    57  // When Read encounters an error or end-of-file condition after
    58  // successfully reading n > 0 bytes, it returns the number of
    59  // bytes read. It may return the (non-nil) error from the same call
    60  // or return the error (and n == 0) from a subsequent call.
    61  // An instance of this general case is that a Reader returning
    62  // a non-zero number of bytes at the end of the input stream may
    63  // return either err == EOF or err == nil. The next Read should
    64  // return 0, EOF.
    65  //
    66  // Callers should always process the n > 0 bytes returned before
    67  // considering the error err. Doing so correctly handles I/O errors
    68  // that happen after reading some bytes and also both of the
    69  // allowed EOF behaviors.
    70  //
    71  // Implementations of Read are discouraged from returning a
    72  // zero byte count with a nil error, except when len(p) == 0.
    73  // Callers should treat a return of 0 and nil as indicating that
    74  // nothing happened; in particular it does not indicate EOF.
    75  //
    76  // Implementations must not retain p.
    77  type Reader interface {
    78  	Read(p []byte) (n int, err error)
    79  }
    80  
    81  // Writer is the interface that wraps the basic Write method.
    82  //
    83  // Write writes len(p) bytes from p to the underlying data stream.
    84  // It returns the number of bytes written from p (0 <= n <= len(p))
    85  // and any error encountered that caused the write to stop early.
    86  // Write must return a non-nil error if it returns n < len(p).
    87  // Write must not modify the slice data, even temporarily.
    88  //
    89  // Implementations must not retain p.
    90  type Writer interface {
    91  	Write(p []byte) (n int, err error)
    92  }
    93  
    94  // Closer is the interface that wraps the basic Close method.
    95  //
    96  // The behavior of Close after the first call is undefined.
    97  // Specific implementations may document their own behavior.
    98  type Closer interface {
    99  	Close() error
   100  }
   101  
   102  // Seeker is the interface that wraps the basic Seek method.
   103  //
   104  // Seek sets the offset for the next Read or Write to offset,
   105  // interpreted according to whence:
   106  // SeekStart means relative to the start of the file,
   107  // SeekCurrent means relative to the current offset, and
   108  // SeekEnd means relative to the end.
   109  // Seek returns the new offset relative to the start of the
   110  // file and an error, if any.
   111  //
   112  // Seeking to an offset before the start of the file is an error.
   113  // Seeking to any positive offset is legal, but the behavior of subsequent
   114  // I/O operations on the underlying object is implementation-dependent.
   115  type Seeker interface {
   116  	Seek(offset int64, whence int) (int64, error)
   117  }
   118  
   119  // ReadWriter is the interface that groups the basic Read and Write methods.
   120  type ReadWriter interface {
   121  	Reader
   122  	Writer
   123  }
   124  
   125  // ReadCloser is the interface that groups the basic Read and Close methods.
   126  type ReadCloser interface {
   127  	Reader
   128  	Closer
   129  }
   130  
   131  // WriteCloser is the interface that groups the basic Write and Close methods.
   132  type WriteCloser interface {
   133  	Writer
   134  	Closer
   135  }
   136  
   137  // ReadWriteCloser is the interface that groups the basic Read, Write and Close methods.
   138  type ReadWriteCloser interface {
   139  	Reader
   140  	Writer
   141  	Closer
   142  }
   143  
   144  // ReadSeeker is the interface that groups the basic Read and Seek methods.
   145  type ReadSeeker interface {
   146  	Reader
   147  	Seeker
   148  }
   149  
   150  // WriteSeeker is the interface that groups the basic Write and Seek methods.
   151  type WriteSeeker interface {
   152  	Writer
   153  	Seeker
   154  }
   155  
   156  // ReadWriteSeeker is the interface that groups the basic Read, Write and Seek methods.
   157  type ReadWriteSeeker interface {
   158  	Reader
   159  	Writer
   160  	Seeker
   161  }
   162  
   163  // ReaderFrom is the interface that wraps the ReadFrom method.
   164  //
   165  // ReadFrom reads data from r until EOF or error.
   166  // The return value n is the number of bytes read.
   167  // Any error except io.EOF encountered during the read is also returned.
   168  //
   169  // The Copy function uses ReaderFrom if available.
   170  type ReaderFrom interface {
   171  	ReadFrom(r Reader) (n int64, err error)
   172  }
   173  
   174  // WriterTo is the interface that wraps the WriteTo method.
   175  //
   176  // WriteTo writes data to w until there's no more data to write or
   177  // when an error occurs. The return value n is the number of bytes
   178  // written. Any error encountered during the write is also returned.
   179  //
   180  // The Copy function uses WriterTo if available.
   181  type WriterTo interface {
   182  	WriteTo(w Writer) (n int64, err error)
   183  }
   184  
   185  // ReaderAt is the interface that wraps the basic ReadAt method.
   186  //
   187  // ReadAt reads len(p) bytes into p starting at offset off in the
   188  // underlying input source. It returns the number of bytes
   189  // read (0 <= n <= len(p)) and any error encountered.
   190  //
   191  // When ReadAt returns n < len(p), it returns a non-nil error
   192  // explaining why more bytes were not returned. In this respect,
   193  // ReadAt is stricter than Read.
   194  //
   195  // Even if ReadAt returns n < len(p), it may use all of p as scratch
   196  // space during the call. If some data is available but not len(p) bytes,
   197  // ReadAt blocks until either all the data is available or an error occurs.
   198  // In this respect ReadAt is different from Read.
   199  //
   200  // If the n = len(p) bytes returned by ReadAt are at the end of the
   201  // input source, ReadAt may return either err == EOF or err == nil.
   202  //
   203  // If ReadAt is reading from an input source with a seek offset,
   204  // ReadAt should not affect nor be affected by the underlying
   205  // seek offset.
   206  //
   207  // Clients of ReadAt can execute parallel ReadAt calls on the
   208  // same input source.
   209  //
   210  // Implementations must not retain p.
   211  type ReaderAt interface {
   212  	ReadAt(p []byte, off int64) (n int, err error)
   213  }
   214  
   215  // WriterAt is the interface that wraps the basic WriteAt method.
   216  //
   217  // WriteAt writes len(p) bytes from p to the underlying data stream
   218  // at offset off. It returns the number of bytes written from p (0 <= n <= len(p))
   219  // and any error encountered that caused the write to stop early.
   220  // WriteAt must return a non-nil error if it returns n < len(p).
   221  //
   222  // If WriteAt is writing to a destination with a seek offset,
   223  // WriteAt should not affect nor be affected by the underlying
   224  // seek offset.
   225  //
   226  // Clients of WriteAt can execute parallel WriteAt calls on the same
   227  // destination if the ranges do not overlap.
   228  //
   229  // Implementations must not retain p.
   230  type WriterAt interface {
   231  	WriteAt(p []byte, off int64) (n int, err error)
   232  }
   233  
   234  // ByteReader is the interface that wraps the ReadByte method.
   235  //
   236  // ReadByte reads and returns the next byte from the input or
   237  // any error encountered. If ReadByte returns an error, no input
   238  // byte was consumed, and the returned byte value is undefined.
   239  //
   240  // ReadByte provides an efficient interface for byte-at-time
   241  // processing. A Reader that does not implement  ByteReader
   242  // can be wrapped using bufio.NewReader to add this method.
   243  type ByteReader interface {
   244  	ReadByte() (byte, error)
   245  }
   246  
   247  // ByteScanner is the interface that adds the UnreadByte method to the
   248  // basic ReadByte method.
   249  //
   250  // UnreadByte causes the next call to ReadByte to return the same byte
   251  // as the previous call to ReadByte.
   252  // It may be an error to call UnreadByte twice without an intervening
   253  // call to ReadByte.
   254  type ByteScanner interface {
   255  	ByteReader
   256  	UnreadByte() error
   257  }
   258  
   259  // ByteWriter is the interface that wraps the WriteByte method.
   260  type ByteWriter interface {
   261  	WriteByte(c byte) error
   262  }
   263  
   264  // RuneReader is the interface that wraps the ReadRune method.
   265  //
   266  // ReadRune reads a single UTF-8 encoded Unicode character
   267  // and returns the rune and its size in bytes. If no character is
   268  // available, err will be set.
   269  type RuneReader interface {
   270  	ReadRune() (r rune, size int, err error)
   271  }
   272  
   273  // RuneScanner is the interface that adds the UnreadRune method to the
   274  // basic ReadRune method.
   275  //
   276  // UnreadRune causes the next call to ReadRune to return the same rune
   277  // as the previous call to ReadRune.
   278  // It may be an error to call UnreadRune twice without an intervening
   279  // call to ReadRune.
   280  type RuneScanner interface {
   281  	RuneReader
   282  	UnreadRune() error
   283  }
   284  
   285  // StringWriter is the interface that wraps the WriteString method.
   286  type StringWriter interface {
   287  	WriteString(s string) (n int, err error)
   288  }
   289  
   290  // WriteString writes the contents of the string s to w, which accepts a slice of bytes.
   291  // If w implements StringWriter, its WriteString method is invoked directly.
   292  // Otherwise, w.Write is called exactly once.
   293  func WriteString(w Writer, s string) (n int, err error) {
   294  	if sw, ok := w.(StringWriter); ok {
   295  		return sw.WriteString(s)
   296  	}
   297  	return w.Write([]byte(s))
   298  }
   299  
   300  // ReadAtLeast reads from r into buf until it has read at least min bytes.
   301  // It returns the number of bytes copied and an error if fewer bytes were read.
   302  // The error is EOF only if no bytes were read.
   303  // If an EOF happens after reading fewer than min bytes,
   304  // ReadAtLeast returns ErrUnexpectedEOF.
   305  // If min is greater than the length of buf, ReadAtLeast returns ErrShortBuffer.
   306  // On return, n >= min if and only if err == nil.
   307  // If r returns an error having read at least min bytes, the error is dropped.
   308  func ReadAtLeast(r Reader, buf []byte, min int) (n int, err error) {
   309  	if len(buf) < min {
   310  		return 0, ErrShortBuffer
   311  	}
   312  	for n < min && err == nil {
   313  		var nn int
   314  		nn, err = r.Read(buf[n:])
   315  		n += nn
   316  	}
   317  	if n >= min {
   318  		err = nil
   319  	} else if n > 0 && err == EOF {
   320  		err = ErrUnexpectedEOF
   321  	}
   322  	return
   323  }
   324  
   325  // ReadFull reads exactly len(buf) bytes from r into buf.
   326  // It returns the number of bytes copied and an error if fewer bytes were read.
   327  // The error is EOF only if no bytes were read.
   328  // If an EOF happens after reading some but not all the bytes,
   329  // ReadFull returns ErrUnexpectedEOF.
   330  // On return, n == len(buf) if and only if err == nil.
   331  // If r returns an error having read at least len(buf) bytes, the error is dropped.
   332  func ReadFull(r Reader, buf []byte) (n int, err error) {
   333  	return ReadAtLeast(r, buf, len(buf))
   334  }
   335  
   336  // CopyN copies n bytes (or until an error) from src to dst.
   337  // It returns the number of bytes copied and the earliest
   338  // error encountered while copying.
   339  // On return, written == n if and only if err == nil.
   340  //
   341  // If dst implements the ReaderFrom interface,
   342  // the copy is implemented using it.
   343  func CopyN(dst Writer, src Reader, n int64) (written int64, err error) {
   344  	written, err = Copy(dst, LimitReader(src, n))
   345  	if written == n {
   346  		return n, nil
   347  	}
   348  	if written < n && err == nil {
   349  		// src stopped early; must have been EOF.
   350  		err = EOF
   351  	}
   352  	return
   353  }
   354  
   355  // Copy copies from src to dst until either EOF is reached
   356  // on src or an error occurs. It returns the number of bytes
   357  // copied and the first error encountered while copying, if any.
   358  //
   359  // A successful Copy returns err == nil, not err == EOF.
   360  // Because Copy is defined to read from src until EOF, it does
   361  // not treat an EOF from Read as an error to be reported.
   362  //
   363  // If src implements the WriterTo interface,
   364  // the copy is implemented by calling src.WriteTo(dst).
   365  // Otherwise, if dst implements the ReaderFrom interface,
   366  // the copy is implemented by calling dst.ReadFrom(src).
   367  func Copy(dst Writer, src Reader) (written int64, err error) {
   368  	return copyBuffer(dst, src, nil)
   369  }
   370  
   371  // CopyBuffer is identical to Copy except that it stages through the
   372  // provided buffer (if one is required) rather than allocating a
   373  // temporary one. If buf is nil, one is allocated; otherwise if it has
   374  // zero length, CopyBuffer panics.
   375  //
   376  // If either src implements WriterTo or dst implements ReaderFrom,
   377  // buf will not be used to perform the copy.
   378  func CopyBuffer(dst Writer, src Reader, buf []byte) (written int64, err error) {
   379  	if buf != nil && len(buf) == 0 {
   380  		panic("empty buffer in io.CopyBuffer")
   381  	}
   382  	return copyBuffer(dst, src, buf)
   383  }
   384  
   385  // copyBuffer is the actual implementation of Copy and CopyBuffer.
   386  // if buf is nil, one is allocated.
   387  func copyBuffer(dst Writer, src Reader, buf []byte) (written int64, err error) {
   388  	// If the reader has a WriteTo method, use it to do the copy.
   389  	// Avoids an allocation and a copy.
   390  	if wt, ok := src.(WriterTo); ok {
   391  		return wt.WriteTo(dst)
   392  	}
   393  	// Similarly, if the writer has a ReadFrom method, use it to do the copy.
   394  	if rt, ok := dst.(ReaderFrom); ok {
   395  		return rt.ReadFrom(src)
   396  	}
   397  	if buf == nil {
   398  		size := 32 * 1024
   399  		if l, ok := src.(*LimitedReader); ok && int64(size) > l.N {
   400  			if l.N < 1 {
   401  				size = 1
   402  			} else {
   403  				size = int(l.N)
   404  			}
   405  		}
   406  		buf = make([]byte, size)
   407  	}
   408  	for {
   409  		nr, er := src.Read(buf)
   410  		if nr > 0 {
   411  			nw, ew := dst.Write(buf[0:nr])
   412  			if nw > 0 {
   413  				written += int64(nw)
   414  			}
   415  			if ew != nil {
   416  				err = ew
   417  				break
   418  			}
   419  			if nr != nw {
   420  				err = ErrShortWrite
   421  				break
   422  			}
   423  		}
   424  		if er != nil {
   425  			if er != EOF {
   426  				err = er
   427  			}
   428  			break
   429  		}
   430  	}
   431  	return written, err
   432  }
   433  
   434  // LimitReader returns a Reader that reads from r
   435  // but stops with EOF after n bytes.
   436  // The underlying implementation is a *LimitedReader.
   437  func LimitReader(r Reader, n int64) Reader { return &LimitedReader{r, n} }
   438  
   439  // A LimitedReader reads from R but limits the amount of
   440  // data returned to just N bytes. Each call to Read
   441  // updates N to reflect the new amount remaining.
   442  // Read returns EOF when N <= 0 or when the underlying R returns EOF.
   443  type LimitedReader struct {
   444  	R Reader // underlying reader
   445  	N int64  // max bytes remaining
   446  }
   447  
   448  func (l *LimitedReader) Read(p []byte) (n int, err error) {
   449  	if l.N <= 0 {
   450  		return 0, EOF
   451  	}
   452  	if int64(len(p)) > l.N {
   453  		p = p[0:l.N]
   454  	}
   455  	n, err = l.R.Read(p)
   456  	l.N -= int64(n)
   457  	return
   458  }
   459  
   460  // NewSectionReader returns a SectionReader that reads from r
   461  // starting at offset off and stops with EOF after n bytes.
   462  func NewSectionReader(r ReaderAt, off int64, n int64) *SectionReader {
   463  	return &SectionReader{r, off, off, off + n}
   464  }
   465  
   466  // SectionReader implements Read, Seek, and ReadAt on a section
   467  // of an underlying ReaderAt.
   468  type SectionReader struct {
   469  	r     ReaderAt
   470  	base  int64
   471  	off   int64
   472  	limit int64
   473  }
   474  
   475  func (s *SectionReader) Read(p []byte) (n int, err error) {
   476  	if s.off >= s.limit {
   477  		return 0, EOF
   478  	}
   479  	if max := s.limit - s.off; int64(len(p)) > max {
   480  		p = p[0:max]
   481  	}
   482  	n, err = s.r.ReadAt(p, s.off)
   483  	s.off += int64(n)
   484  	return
   485  }
   486  
   487  var errWhence = errors.New("Seek: invalid whence")
   488  var errOffset = errors.New("Seek: invalid offset")
   489  
   490  func (s *SectionReader) Seek(offset int64, whence int) (int64, error) {
   491  	switch whence {
   492  	default:
   493  		return 0, errWhence
   494  	case SeekStart:
   495  		offset += s.base
   496  	case SeekCurrent:
   497  		offset += s.off
   498  	case SeekEnd:
   499  		offset += s.limit
   500  	}
   501  	if offset < s.base {
   502  		return 0, errOffset
   503  	}
   504  	s.off = offset
   505  	return offset - s.base, nil
   506  }
   507  
   508  func (s *SectionReader) ReadAt(p []byte, off int64) (n int, err error) {
   509  	if off < 0 || off >= s.limit-s.base {
   510  		return 0, EOF
   511  	}
   512  	off += s.base
   513  	if max := s.limit - off; int64(len(p)) > max {
   514  		p = p[0:max]
   515  		n, err = s.r.ReadAt(p, off)
   516  		if err == nil {
   517  			err = EOF
   518  		}
   519  		return n, err
   520  	}
   521  	return s.r.ReadAt(p, off)
   522  }
   523  
   524  // Size returns the size of the section in bytes.
   525  func (s *SectionReader) Size() int64 { return s.limit - s.base }
   526  
   527  // TeeReader returns a Reader that writes to w what it reads from r.
   528  // All reads from r performed through it are matched with
   529  // corresponding writes to w. There is no internal buffering -
   530  // the write must complete before the read completes.
   531  // Any error encountered while writing is reported as a read error.
   532  func TeeReader(r Reader, w Writer) Reader {
   533  	return &teeReader{r, w}
   534  }
   535  
   536  type teeReader struct {
   537  	r Reader
   538  	w Writer
   539  }
   540  
   541  func (t *teeReader) Read(p []byte) (n int, err error) {
   542  	n, err = t.r.Read(p)
   543  	if n > 0 {
   544  		if n, err := t.w.Write(p[:n]); err != nil {
   545  			return n, err
   546  		}
   547  	}
   548  	return
   549  }
   550  

View as plain text