libgo/go/io/io.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 // This package 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 package io
  10
  11 import "os"
  12
  13 // Error represents an unexpected I/O behavior.
  14 type Error struct {
  15         os.ErrorString
  16 }
  17
  18 // ErrShortWrite means that a write accepted fewer bytes than requested
  19 // but failed to return an explicit error.
  20 var ErrShortWrite os.Error = &Error{"short write"}
  21
  22 // ErrShortBuffer means that a read required a longer buffer than was provided.
  23 var ErrShortBuffer os.Error = &Error{"short buffer"}
  24
  25 // ErrUnexpectedEOF means that os.EOF was encountered in the
  26 // middle of reading a fixed-size block or data structure.
  27 var ErrUnexpectedEOF os.Error = &Error{"unexpected EOF"}
  28
  29 // Reader is the interface that wraps the basic Read method.
  30 //
  31 // Read reads up to len(p) bytes into p.  It returns the number of bytes
  32 // read (0 <= n <= len(p)) and any error encountered.
  33 // Even if Read returns n < len(p),
  34 // it may use all of p as scratch space during the call.
  35 // If some data is available but not len(p) bytes, Read conventionally
  36 // returns what is available rather than block waiting for more.
  37 //
  38 // At the end of the input stream, Read returns 0, os.EOF.
  39 // Read may return a non-zero number of bytes with a non-nil err.
  40 // In particular, a Read that exhausts the input may return n > 0, os.EOF.
  41 type Reader interface {
  42         Read(p []byte) (n int, err os.Error)
  43 }
  44
  45 // Writer is the interface that wraps the basic Write method.
  46 //
  47 // Write writes len(p) bytes from p to the underlying data stream.
  48 // It returns the number of bytes written from p (0 <= n <= len(p))
  49 // and any error encountered that caused the write to stop early.
  50 // Write must return a non-nil error if it returns n < len(p).
  51 type Writer interface {
  52         Write(p []byte) (n int, err os.Error)
  53 }
  54
  55 // Closer is the interface that wraps the basic Close method.
  56 type Closer interface {
  57         Close() os.Error
  58 }
  59
  60 // Seeker is the interface that wraps the basic Seek method.
  61 //
  62 // Seek sets the offset for the next Read or Write to offset,
  63 // interpreted according to whence: 0 means relative to the origin of
  64 // the file, 1 means relative to the current offset, and 2 means
  65 // relative to the end.  Seek returns the new offset and an Error, if
  66 // any.
  67 type Seeker interface {
  68         Seek(offset int64, whence int) (ret int64, err os.Error)
  69 }
  70
  71 // ReadWriter is the interface that groups the basic Read and Write methods.
  72 type ReadWriter interface {
  73         Reader
  74         Writer
  75 }
  76
  77 // ReadCloser is the interface that groups the basic Read and Close methods.
  78 type ReadCloser interface {
  79         Reader
  80         Closer
  81 }
  82
  83 // WriteCloser is the interface that groups the basic Write and Close methods.
  84 type WriteCloser interface {
  85         Writer
  86         Closer
  87 }
  88
  89 // ReadWriteCloser is the interface that groups the basic Read, Write and Close methods.
  90 type ReadWriteCloser interface {
  91         Reader
  92         Writer
  93         Closer
  94 }
  95
  96 // ReadSeeker is the interface that groups the basic Read and Seek methods.
  97 type ReadSeeker interface {
  98         Reader
  99         Seeker
 100 }
 101
 102 // WriteSeeker is the interface that groups the basic Write and Seek methods.
 103 type WriteSeeker interface {
 104         Writer
 105         Seeker
 106 }
 107
 108 // ReadWriteSeeker is the interface that groups the basic Read, Write and Seek methods.
 109 type ReadWriteSeeker interface {
 110         Reader
 111         Writer
 112         Seeker
 113 }
 114
 115 // ReaderFrom is the interface that wraps the ReadFrom method.
 116 type ReaderFrom interface {
 117         ReadFrom(r Reader) (n int64, err os.Error)
 118 }
 119
 120 // WriterTo is the interface that wraps the WriteTo method.
 121 type WriterTo interface {
 122         WriteTo(w Writer) (n int64, err os.Error)
 123 }
 124
 125 // ReaderAt is the interface that wraps the basic ReadAt method.
 126 //
 127 // ReadAt reads len(p) bytes into p starting at offset off in the
 128 // underlying data stream.  It returns the number of bytes
 129 // read (0 <= n <= len(p)) and any error encountered.
 130 //
 131 // Even if ReadAt returns n < len(p),
 132 // it may use all of p as scratch space during the call.
 133 // If some data is available but not len(p) bytes, ReadAt blocks
 134 // until either all the data is available or an error occurs.
 135 //
 136 // At the end of the input stream, ReadAt returns 0, os.EOF.
 137 // ReadAt may return a non-zero number of bytes with a non-nil err.
 138 // In particular, a ReadAt that exhausts the input may return n > 0, os.EOF.
 139 type ReaderAt interface {
 140         ReadAt(p []byte, off int64) (n int, err os.Error)
 141 }
 142
 143 // WriterAt is the interface that wraps the basic WriteAt method.
 144 //
 145 // WriteAt writes len(p) bytes from p to the underlying data stream
 146 // at offset off.  It returns the number of bytes written from p (0 <= n <= len(p))
 147 // and any error encountered that caused the write to stop early.
 148 // WriteAt must return a non-nil error if it returns n < len(p).
 149 type WriterAt interface {
 150         WriteAt(p []byte, off int64) (n int, err os.Error)
 151 }
 152
 153 // ReadByter is the interface that wraps the ReadByte method.
 154 //
 155 // ReadByte reads and returns the next byte from the input.
 156 // If no byte is available, err will be set.
 157 type ReadByter interface {
 158         ReadByte() (c byte, err os.Error)
 159 }
 160
 161 // WriteString writes the contents of the string s to w, which accepts an array of bytes.
 162 func WriteString(w Writer, s string) (n int, err os.Error) {
 163         return w.Write([]byte(s))
 164 }
 165
 166 // ReadAtLeast reads from r into buf until it has read at least min bytes.
 167 // It returns the number of bytes copied and an error if fewer bytes were read.
 168 // The error is os.EOF only if no bytes were read.
 169 // If an EOF happens after reading fewer than min bytes,
 170 // ReadAtLeast returns ErrUnexpectedEOF.
 171 // If min is greater than the length of buf, ReadAtLeast returns ErrShortBuffer.
 172 func ReadAtLeast(r Reader, buf []byte, min int) (n int, err os.Error) {
 173         if len(buf) < min {
 174                 return 0, ErrShortBuffer
 175         }
 176         for n < min {
 177                 nn, e := r.Read(buf[n:])
 178                 if nn > 0 {
 179                         n += nn
 180                 }
 181                 if e != nil {
 182                         if e == os.EOF && n > 0 {
 183                                 e = ErrUnexpectedEOF
 184                         }
 185                         return n, e
 186                 }
 187         }
 188         return
 189 }
 190
 191 // ReadFull reads exactly len(buf) bytes from r into buf.
 192 // It returns the number of bytes copied and an error if fewer bytes were read.
 193 // The error is os.EOF only if no bytes were read.
 194 // If an EOF happens after reading some but not all the bytes,
 195 // ReadFull returns ErrUnexpectedEOF.
 196 func ReadFull(r Reader, buf []byte) (n int, err os.Error) {
 197         return ReadAtLeast(r, buf, len(buf))
 198 }
 199
 200 // Copyn copies n bytes (or until an error) from src to dst.
 201 // It returns the number of bytes copied and the error, if any.
 202 //
 203 // If dst implements the ReaderFrom interface,
 204 // the copy is implemented by calling dst.ReadFrom(src).
 205 func Copyn(dst Writer, src Reader, n int64) (written int64, err os.Error) {
 206         // If the writer has a ReadFrom method, use it to do the copy.
 207         // Avoids a buffer allocation and a copy.
 208         if rt, ok := dst.(ReaderFrom); ok {
 209                 written, err = rt.ReadFrom(LimitReader(src, n))
 210                 if written < n && err == nil {
 211                         // rt stopped early; must have been EOF.
 212                         err = os.EOF
 213                 }
 214                 return
 215         }
 216         buf := make([]byte, 32*1024)
 217         for written < n {
 218                 l := len(buf)
 219                 if d := n - written; d < int64(l) {
 220                         l = int(d)
 221                 }
 222                 nr, er := src.Read(buf[0:l])
 223                 if nr > 0 {
 224                         nw, ew := dst.Write(buf[0:nr])
 225                         if nw > 0 {
 226                                 written += int64(nw)
 227                         }
 228                         if ew != nil {
 229                                 err = ew
 230                                 break
 231                         }
 232                         if nr != nw {
 233                                 err = ErrShortWrite
 234                                 break
 235                         }
 236                 }
 237                 if er != nil {
 238                         err = er
 239                         break
 240                 }
 241         }
 242         return written, err
 243 }
 244
 245 // Copy copies from src to dst until either EOF is reached
 246 // on src or an error occurs.  It returns the number of bytes
 247 // copied and the error, if any.
 248 //
 249 // If dst implements the ReaderFrom interface,
 250 // the copy is implemented by calling dst.ReadFrom(src).
 251 // Otherwise, if src implements the WriterTo interface,
 252 // the copy is implemented by calling src.WriteTo(dst).
 253 func Copy(dst Writer, src Reader) (written int64, err os.Error) {
 254         // If the writer has a ReadFrom method, use it to do the copy.
 255         // Avoids an allocation and a copy.
 256         if rt, ok := dst.(ReaderFrom); ok {
 257                 return rt.ReadFrom(src)
 258         }
 259         // Similarly, if the reader has a WriteTo method, use it to do the copy.
 260         if wt, ok := src.(WriterTo); ok {
 261                 return wt.WriteTo(dst)
 262         }
 263         buf := make([]byte, 32*1024)
 264         for {
 265                 nr, er := src.Read(buf)
 266                 if nr > 0 {
 267                         nw, ew := dst.Write(buf[0:nr])
 268                         if nw > 0 {
 269                                 written += int64(nw)
 270                         }
 271                         if ew != nil {
 272                                 err = ew
 273                                 break
 274                         }
 275                         if nr != nw {
 276                                 err = ErrShortWrite
 277                                 break
 278                         }
 279                 }
 280                 if er == os.EOF {
 281                         break
 282                 }
 283                 if er != nil {
 284                         err = er
 285                         break
 286                 }
 287         }
 288         return written, err
 289 }
 290
 291 // LimitReader returns a Reader that reads from r
 292 // but stops with os.EOF after n bytes.
 293 func LimitReader(r Reader, n int64) Reader { return &limitedReader{r, n} }
 294
 295 type limitedReader struct {
 296         r Reader
 297         n int64
 298 }
 299
 300 func (l *limitedReader) Read(p []byte) (n int, err os.Error) {
 301         if l.n <= 0 {
 302                 return 0, os.EOF
 303         }
 304         if int64(len(p)) > l.n {
 305                 p = p[0:l.n]
 306         }
 307         n, err = l.r.Read(p)
 308         l.n -= int64(n)
 309         return
 310 }
 311
 312 // NewSectionReader returns a SectionReader that reads from r
 313 // starting at offset off and stops with os.EOF after n bytes.
 314 func NewSectionReader(r ReaderAt, off int64, n int64) *SectionReader {
 315         return &SectionReader{r, off, off, off + n}
 316 }
 317
 318 // SectionReader implements Read, Seek, and ReadAt on a section
 319 // of an underlying ReaderAt.
 320 type SectionReader struct {
 321         r     ReaderAt
 322         base  int64
 323         off   int64
 324         limit int64
 325 }
 326
 327 func (s *SectionReader) Read(p []byte) (n int, err os.Error) {
 328         if s.off >= s.limit {
 329                 return 0, os.EOF
 330         }
 331         if max := s.limit - s.off; int64(len(p)) > max {
 332                 p = p[0:max]
 333         }
 334         n, err = s.r.ReadAt(p, s.off)
 335         s.off += int64(n)
 336         return
 337 }
 338
 339 func (s *SectionReader) Seek(offset int64, whence int) (ret int64, err os.Error) {
 340         switch whence {
 341         default:
 342                 return 0, os.EINVAL
 343         case 0:
 344                 offset += s.base
 345         case 1:
 346                 offset += s.off
 347         case 2:
 348                 offset += s.limit
 349         }
 350         if offset < s.base || offset > s.limit {
 351                 return 0, os.EINVAL
 352         }
 353         s.off = offset
 354         return offset - s.base, nil
 355 }
 356
 357 func (s *SectionReader) ReadAt(p []byte, off int64) (n int, err os.Error) {
 358         if off < 0 || off >= s.limit-s.base {
 359                 return 0, os.EOF
 360         }
 361         off += s.base
 362         if max := s.limit - off; int64(len(p)) > max {
 363                 p = p[0:max]
 364         }
 365         return s.r.ReadAt(p, off)
 366 }
 367
 368 // Size returns the size of the section in bytes.
 369 func (s *SectionReader) Size() int64 { return s.limit - s.base }