Imported Upstream version 59upstream/59

2 files changed, 49 insertions, 20 deletions

diff --git a/src/pkg/io/io.go b/src/pkg/io/io.go
index 846dcacb5..b879fe5b7 100644
--- a/src/pkg/io/io.go
+++ b/src/pkg/io/io.go
@@ -12,9 +12,11 @@ import "os"
 
 // Error represents an unexpected I/O behavior.
 type Error struct {
-	os.ErrorString
+	ErrorString string
 }
 
+func (err *Error) String() string { return err.ErrorString }
+
 // ErrShortWrite means that a write accepted fewer bytes than requested
 // but failed to return an explicit error.
 var ErrShortWrite os.Error = &Error{"short write"}
@@ -29,15 +31,24 @@ var ErrUnexpectedEOF os.Error = &Error{"unexpected EOF"}
 // Reader is the interface that wraps the basic Read method.
 //
 // Read reads up to len(p) bytes into p.  It returns the number of bytes
-// read (0 <= n <= len(p)) and any error encountered.
-// Even if Read returns n < len(p),
-// it may use all of p as scratch space during the call.
+// read (0 <= n <= len(p)) and any error encountered.  Even if Read
+// returns n < len(p), it may use all of p as scratch space during the call.
 // If some data is available but not len(p) bytes, Read conventionally
-// returns what is available rather than block waiting for more.
+// returns what is available instead of waiting for more.
 //
-// At the end of the input stream, Read returns 0, os.EOF.
-// Read may return a non-zero number of bytes with a non-nil err.
-// In particular, a Read that exhausts the input may return n > 0, os.EOF.
+// When Read encounters an error or end-of-file condition after
+// successfully reading n > 0 bytes, it returns the number of
+// bytes read.  It may return the (non-nil) error from the same call
+// or return the error (and n == 0) from a subsequent call.
+// An instance of this general case is that a Reader returning
+// a non-zero number of bytes at the end of the input stream may
+// return either err == os.EOF or err == nil.  The next Read should
+// return 0, os.EOF regardless.
+//
+// Callers should always process the n > 0 bytes returned before
+// considering the error err.  Doing so correctly handles I/O errors
+// that happen after reading some bytes and also both of the
+// allowed EOF behaviors.
 type Reader interface {
 	Read(p []byte) (n int, err os.Error)
 }
@@ -125,19 +136,22 @@ type WriterTo interface {
 // ReaderAt is the interface that wraps the basic ReadAt method.
 //
 // ReadAt reads len(p) bytes into p starting at offset off in the
-// underlying data stream.  It returns the number of bytes
+// underlying input source.  It returns the number of bytes
 // read (0 <= n <= len(p)) and any error encountered.
 //
-// Even if ReadAt returns n < len(p),
-// it may use all of p as scratch space during the call.
-// If some data is available but not len(p) bytes, ReadAt blocks
-// until either all the data is available or an error occurs.
+// When ReadAt returns n < len(p), it returns a non-nil error
+// explaining why more bytes were not returned.  In this respect,
+// ReadAt is stricter than Read.
+//
+// Even if ReadAt returns n < len(p), it may use all of p as scratch
+// space during the call.  If some data is available but not len(p) bytes,
+// ReadAt blocks until either all the data is available or an error occurs.
+// In this respect ReadAt is different from Read.
 //
-// At the end of the input stream, ReadAt returns 0, os.EOF.
-// ReadAt may return a non-zero number of bytes with a non-nil err.
-// In particular, a ReadAt that exhausts the input may return n > 0, os.EOF.
+// If the n = len(p) bytes returned by ReadAt are at the end of the
+// input source, ReadAt may return either err == os.EOF or err == nil.
 //
-// If ReadAt is reading from an data stream with a seek offset,
+// If ReadAt is reading from an input source with a seek offset,
 // ReadAt should not affect nor be affected by the underlying
 // seek offset.
 type ReaderAt interface {
@@ -195,8 +209,16 @@ type RuneScanner interface {
 	UnreadRune() os.Error
 }
 
+// stringWriter is the interface that wraps the WriteString method.
+type stringWriter interface {
+	WriteString(s string) (n int, err os.Error)
+}
+
 // WriteString writes the contents of the string s to w, which accepts an array of bytes.
 func WriteString(w Writer, s string) (n int, err os.Error) {
+	if sw, ok := w.(stringWriter); ok {
+		return sw.WriteString(s)
+	}
 	return w.Write([]byte(s))
 }
 
@@ -235,7 +257,10 @@ func ReadFull(r Reader, buf []byte) (n int, err os.Error) {
 }
 
 // Copyn copies n bytes (or until an error) from src to dst.
-// It returns the number of bytes copied and the error, if any.
+// It returns the number of bytes copied and the earliest
+// error encountered while copying.  Because Read can
+// return the full amount requested as well as an error
+// (including os.EOF), so can Copyn.
 //
 // If dst implements the ReaderFrom interface,
 // the copy is implemented by calling dst.ReadFrom(src).
@@ -281,7 +306,11 @@ func Copyn(dst Writer, src Reader, n int64) (written int64, err os.Error) {
 
 // Copy copies from src to dst until either EOF is reached
 // on src or an error occurs.  It returns the number of bytes
-// copied and the error, if any.
+// copied and the first error encountered while copying, if any.
+//
+// A successful Copy returns err == nil, not err == os.EOF.
+// Because Copy is defined to read from src until EOF, it does
+// not treat an EOF from Read as an error to be reported.
 //
 // If dst implements the ReaderFrom interface,
 // the copy is implemented by calling dst.ReadFrom(src).
diff --git a/src/pkg/io/ioutil/ioutil.go b/src/pkg/io/ioutil/ioutil.go
index 5f1eecaab..f79bf87f5 100644
--- a/src/pkg/io/ioutil/ioutil.go
+++ b/src/pkg/io/ioutil/ioutil.go
@@ -63,7 +63,7 @@ func WriteFile(filename string, data []byte, perm uint32) os.Error {
 	return err
 }
 
-// A dirList implements sort.Interface.
+// A fileInfoList implements sort.Interface.
 type fileInfoList []*os.FileInfo
 
 func (f fileInfoList) Len() int           { return len(f) }