* builtins.def (BUILT_IN_SETJMP): Revert latest change.
[official-gcc.git] / libgo / go / io / io.go
blob28dab08e46cef187706e24fc976d25c5c04c3392
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.
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
15 import (
16 "errors"
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
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")
30 // ErrShortBuffer means that a read required a longer buffer than was provided.
31 var ErrShortBuffer = errors.New("short buffer")
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")
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")
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")
49 // Reader is the interface that wraps the basic Read method.
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.
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.
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.
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.
76 // Implementations must not retain p.
77 type Reader interface {
78 Read(p []byte) (n int, err error)
81 // Writer is the interface that wraps the basic Write method.
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.
89 // Implementations must not retain p.
90 type Writer interface {
91 Write(p []byte) (n int, err error)
94 // Closer is the interface that wraps the basic Close method.
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
102 // Seeker is the interface that wraps the basic Seek method.
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.
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)
119 // ReadWriter is the interface that groups the basic Read and Write methods.
120 type ReadWriter interface {
121 Reader
122 Writer
125 // ReadCloser is the interface that groups the basic Read and Close methods.
126 type ReadCloser interface {
127 Reader
128 Closer
131 // WriteCloser is the interface that groups the basic Write and Close methods.
132 type WriteCloser interface {
133 Writer
134 Closer
137 // ReadWriteCloser is the interface that groups the basic Read, Write and Close methods.
138 type ReadWriteCloser interface {
139 Reader
140 Writer
141 Closer
144 // ReadSeeker is the interface that groups the basic Read and Seek methods.
145 type ReadSeeker interface {
146 Reader
147 Seeker
150 // WriteSeeker is the interface that groups the basic Write and Seek methods.
151 type WriteSeeker interface {
152 Writer
153 Seeker
156 // ReadWriteSeeker is the interface that groups the basic Read, Write and Seek methods.
157 type ReadWriteSeeker interface {
158 Reader
159 Writer
160 Seeker
163 // ReaderFrom is the interface that wraps the ReadFrom method.
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.
169 // The Copy function uses ReaderFrom if available.
170 type ReaderFrom interface {
171 ReadFrom(r Reader) (n int64, err error)
174 // WriterTo is the interface that wraps the WriteTo method.
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.
180 // The Copy function uses WriterTo if available.
181 type WriterTo interface {
182 WriteTo(w Writer) (n int64, err error)
185 // ReaderAt is the interface that wraps the basic ReadAt method.
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.
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.
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.
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.
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.
207 // Clients of ReadAt can execute parallel ReadAt calls on the
208 // same input source.
210 // Implementations must not retain p.
211 type ReaderAt interface {
212 ReadAt(p []byte, off int64) (n int, err error)
215 // WriterAt is the interface that wraps the basic WriteAt method.
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).
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.
226 // Clients of WriteAt can execute parallel WriteAt calls on the same
227 // destination if the ranges do not overlap.
229 // Implementations must not retain p.
230 type WriterAt interface {
231 WriteAt(p []byte, off int64) (n int, err error)
234 // ByteReader is the interface that wraps the ReadByte method.
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 type ByteReader interface {
240 ReadByte() (byte, error)
243 // ByteScanner is the interface that adds the UnreadByte method to the
244 // basic ReadByte method.
246 // UnreadByte causes the next call to ReadByte to return the same byte
247 // as the previous call to ReadByte.
248 // It may be an error to call UnreadByte twice without an intervening
249 // call to ReadByte.
250 type ByteScanner interface {
251 ByteReader
252 UnreadByte() error
255 // ByteWriter is the interface that wraps the WriteByte method.
256 type ByteWriter interface {
257 WriteByte(c byte) error
260 // RuneReader is the interface that wraps the ReadRune method.
262 // ReadRune reads a single UTF-8 encoded Unicode character
263 // and returns the rune and its size in bytes. If no character is
264 // available, err will be set.
265 type RuneReader interface {
266 ReadRune() (r rune, size int, err error)
269 // RuneScanner is the interface that adds the UnreadRune method to the
270 // basic ReadRune method.
272 // UnreadRune causes the next call to ReadRune to return the same rune
273 // as the previous call to ReadRune.
274 // It may be an error to call UnreadRune twice without an intervening
275 // call to ReadRune.
276 type RuneScanner interface {
277 RuneReader
278 UnreadRune() error
281 // stringWriter is the interface that wraps the WriteString method.
282 type stringWriter interface {
283 WriteString(s string) (n int, err error)
286 // WriteString writes the contents of the string s to w, which accepts a slice of bytes.
287 // If w implements a WriteString method, it is invoked directly.
288 // Otherwise, w.Write is called exactly once.
289 func WriteString(w Writer, s string) (n int, err error) {
290 if sw, ok := w.(stringWriter); ok {
291 return sw.WriteString(s)
293 return w.Write([]byte(s))
296 // ReadAtLeast reads from r into buf until it has read at least min bytes.
297 // It returns the number of bytes copied and an error if fewer bytes were read.
298 // The error is EOF only if no bytes were read.
299 // If an EOF happens after reading fewer than min bytes,
300 // ReadAtLeast returns ErrUnexpectedEOF.
301 // If min is greater than the length of buf, ReadAtLeast returns ErrShortBuffer.
302 // On return, n >= min if and only if err == nil.
303 func ReadAtLeast(r Reader, buf []byte, min int) (n int, err error) {
304 if len(buf) < min {
305 return 0, ErrShortBuffer
307 for n < min && err == nil {
308 var nn int
309 nn, err = r.Read(buf[n:])
310 n += nn
312 if n >= min {
313 err = nil
314 } else if n > 0 && err == EOF {
315 err = ErrUnexpectedEOF
317 return
320 // ReadFull reads exactly len(buf) bytes from r into buf.
321 // It returns the number of bytes copied and an error if fewer bytes were read.
322 // The error is EOF only if no bytes were read.
323 // If an EOF happens after reading some but not all the bytes,
324 // ReadFull returns ErrUnexpectedEOF.
325 // On return, n == len(buf) if and only if err == nil.
326 func ReadFull(r Reader, buf []byte) (n int, err error) {
327 return ReadAtLeast(r, buf, len(buf))
330 // CopyN copies n bytes (or until an error) from src to dst.
331 // It returns the number of bytes copied and the earliest
332 // error encountered while copying.
333 // On return, written == n if and only if err == nil.
335 // If dst implements the ReaderFrom interface,
336 // the copy is implemented using it.
337 func CopyN(dst Writer, src Reader, n int64) (written int64, err error) {
338 written, err = Copy(dst, LimitReader(src, n))
339 if written == n {
340 return n, nil
342 if written < n && err == nil {
343 // src stopped early; must have been EOF.
344 err = EOF
346 return
349 // Copy copies from src to dst until either EOF is reached
350 // on src or an error occurs. It returns the number of bytes
351 // copied and the first error encountered while copying, if any.
353 // A successful Copy returns err == nil, not err == EOF.
354 // Because Copy is defined to read from src until EOF, it does
355 // not treat an EOF from Read as an error to be reported.
357 // If src implements the WriterTo interface,
358 // the copy is implemented by calling src.WriteTo(dst).
359 // Otherwise, if dst implements the ReaderFrom interface,
360 // the copy is implemented by calling dst.ReadFrom(src).
361 func Copy(dst Writer, src Reader) (written int64, err error) {
362 return copyBuffer(dst, src, nil)
365 // CopyBuffer is identical to Copy except that it stages through the
366 // provided buffer (if one is required) rather than allocating a
367 // temporary one. If buf is nil, one is allocated; otherwise if it has
368 // zero length, CopyBuffer panics.
369 func CopyBuffer(dst Writer, src Reader, buf []byte) (written int64, err error) {
370 if buf != nil && len(buf) == 0 {
371 panic("empty buffer in io.CopyBuffer")
373 return copyBuffer(dst, src, buf)
376 // copyBuffer is the actual implementation of Copy and CopyBuffer.
377 // if buf is nil, one is allocated.
378 func copyBuffer(dst Writer, src Reader, buf []byte) (written int64, err error) {
379 // If the reader has a WriteTo method, use it to do the copy.
380 // Avoids an allocation and a copy.
381 if wt, ok := src.(WriterTo); ok {
382 return wt.WriteTo(dst)
384 // Similarly, if the writer has a ReadFrom method, use it to do the copy.
385 if rt, ok := dst.(ReaderFrom); ok {
386 return rt.ReadFrom(src)
388 if buf == nil {
389 buf = make([]byte, 32*1024)
391 for {
392 nr, er := src.Read(buf)
393 if nr > 0 {
394 nw, ew := dst.Write(buf[0:nr])
395 if nw > 0 {
396 written += int64(nw)
398 if ew != nil {
399 err = ew
400 break
402 if nr != nw {
403 err = ErrShortWrite
404 break
407 if er != nil {
408 if er != EOF {
409 err = er
411 break
414 return written, err
417 // LimitReader returns a Reader that reads from r
418 // but stops with EOF after n bytes.
419 // The underlying implementation is a *LimitedReader.
420 func LimitReader(r Reader, n int64) Reader { return &LimitedReader{r, n} }
422 // A LimitedReader reads from R but limits the amount of
423 // data returned to just N bytes. Each call to Read
424 // updates N to reflect the new amount remaining.
425 // Read returns EOF when N <= 0 or when the underlying R returns EOF.
426 type LimitedReader struct {
427 R Reader // underlying reader
428 N int64 // max bytes remaining
431 func (l *LimitedReader) Read(p []byte) (n int, err error) {
432 if l.N <= 0 {
433 return 0, EOF
435 if int64(len(p)) > l.N {
436 p = p[0:l.N]
438 n, err = l.R.Read(p)
439 l.N -= int64(n)
440 return
443 // NewSectionReader returns a SectionReader that reads from r
444 // starting at offset off and stops with EOF after n bytes.
445 func NewSectionReader(r ReaderAt, off int64, n int64) *SectionReader {
446 return &SectionReader{r, off, off, off + n}
449 // SectionReader implements Read, Seek, and ReadAt on a section
450 // of an underlying ReaderAt.
451 type SectionReader struct {
452 r ReaderAt
453 base int64
454 off int64
455 limit int64
458 func (s *SectionReader) Read(p []byte) (n int, err error) {
459 if s.off >= s.limit {
460 return 0, EOF
462 if max := s.limit - s.off; int64(len(p)) > max {
463 p = p[0:max]
465 n, err = s.r.ReadAt(p, s.off)
466 s.off += int64(n)
467 return
470 var errWhence = errors.New("Seek: invalid whence")
471 var errOffset = errors.New("Seek: invalid offset")
473 func (s *SectionReader) Seek(offset int64, whence int) (int64, error) {
474 switch whence {
475 default:
476 return 0, errWhence
477 case SeekStart:
478 offset += s.base
479 case SeekCurrent:
480 offset += s.off
481 case SeekEnd:
482 offset += s.limit
484 if offset < s.base {
485 return 0, errOffset
487 s.off = offset
488 return offset - s.base, nil
491 func (s *SectionReader) ReadAt(p []byte, off int64) (n int, err error) {
492 if off < 0 || off >= s.limit-s.base {
493 return 0, EOF
495 off += s.base
496 if max := s.limit - off; int64(len(p)) > max {
497 p = p[0:max]
498 n, err = s.r.ReadAt(p, off)
499 if err == nil {
500 err = EOF
502 return n, err
504 return s.r.ReadAt(p, off)
507 // Size returns the size of the section in bytes.
508 func (s *SectionReader) Size() int64 { return s.limit - s.base }
510 // TeeReader returns a Reader that writes to w what it reads from r.
511 // All reads from r performed through it are matched with
512 // corresponding writes to w. There is no internal buffering -
513 // the write must complete before the read completes.
514 // Any error encountered while writing is reported as a read error.
515 func TeeReader(r Reader, w Writer) Reader {
516 return &teeReader{r, w}
519 type teeReader struct {
520 r Reader
521 w Writer
524 func (t *teeReader) Read(p []byte) (n int, err error) {
525 n, err = t.r.Read(p)
526 if n > 0 {
527 if n, err := t.w.Write(p[:n]); err != nil {
528 return n, err
531 return