// Copyright 2009 The Go Authors. All rights reserved.

// Use of this source code is governed by a BSD-style

// license that can be found in the LICENSE file.

package io

// 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.

// If some data is available but not len(p) bytes, Read conventionally

// returns what is available instead of waiting for more.

//

// 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 == EOF or err == nil. The next Read should

// return 0, EOF.

//

// 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.

//

// If len(p) == 0, Read should always return n == 0. It may return a

// non-nil error if some error condition is known, such as EOF.

//

// Implementations of Read are discouraged from returning a

// zero byte count with a nil error, except when len(p) == 0.

// Callers should treat a return of 0 and nil as indicating that

// nothing happened; in particular it does not indicate EOF.

//

// Implementations must not retain p.

type Reader interface {

Read(p []byte) (n int, err error)

}

// Writer is the interface that wraps the basic Write method.

//

// Write writes len(p) bytes from p to the underlying data stream.

// It returns the number of bytes written from p (0 <= n <= len(p))

// and any error encountered that caused the write to stop early.

// Write must return a non-nil error if it returns n < len(p).

// Write must not modify the slice data, even temporarily.

//

// Implementations must not retain p.

type Writer interface {

Write(p []byte) (n int, err error)

}

// Closer is the interface that wraps the basic Close method.

//

// The behavior of Close after the first call is undefined.

// Specific implementations may document their own behavior.

type Closer interface {

Close() error

}

// Seeker is the interface that wraps the basic Seek method.

//

// Seek sets the offset for the next Read or Write to offset,

// interpreted according to whence:

// [SeekStart] means relative to the start of the file,

// [SeekCurrent] means relative to the current offset, and

// [SeekEnd] means relative to the end

// (for example, offset = -2 specifies the penultimate byte of the file).

// Seek returns the new offset relative to the start of the

// file or an error, if any.

//

// Seeking to an offset before the start of the file is an error.

// Seeking to any positive offset may be allowed, but if the new offset exceeds

// the size of the underlying object the behavior of subsequent I/O operations

// is implementation-dependent.

type Seeker interface {

Seek(offset int64, whence int) (int64, error)

}

// ReadWriter is the interface that groups the basic Read and Write methods.

type ReadWriter interface {

Read(p []byte) (n int, err error)

Write(p []byte) (n int, err error)

}

// ReadCloser is the interface that groups the basic Read and Close methods.

type ReadCloser interface {

Read(p []byte) (n int, err error)

Close() error

}

// WriteCloser is the interface that groups the basic Write and Close methods.

type WriteCloser interface {

Write(p []byte) (n int, err error)

Close() error

}

// ReadWriteCloser is the interface that groups the basic Read, Write and Close methods.

type ReadWriteCloser interface {

Read(p []byte) (n int, err error)

Write(p []byte) (n int, err error)

Close() error

}

// ReadSeeker is the interface that groups the basic Read and Seek methods.

type ReadSeeker interface {

Read(p []byte) (n int, err error)

Seek(offset int64, whence int) (int64, error)

}

// ReadSeekCloser is the interface that groups the basic Read, Seek and Close methods.

type ReadSeekCloser interface {

Read(p []byte) (n int, err error)

Seek(offset int64, whence int) (int64, error)

Close() error

}

// WriteSeeker is the interface that groups the basic Write and Seek methods.

type WriteSeeker interface {

Write(p []byte) (n int, err error)

Seek(offset int64, whence int) (int64, error)

}

// ReadWriteSeeker is the interface that groups the basic Read, Write and Seek methods.

type ReadWriteSeeker interface {

Read(p []byte) (n int, err error)

Write(p []byte) (n int, err error)

Seek(offset int64, whence int) (int64, error)

}

// ReaderFrom is the interface that wraps the ReadFrom method.

//

// ReadFrom reads data from r until EOF or error.

// The return value n is the number of bytes read.

// Any error except EOF encountered during the read is also returned.

type ReaderFrom interface {

ReadFrom(r Reader) (n int64, err error)

}

// WriterTo is the interface that wraps the WriteTo method.

//

// WriteTo writes data to w until there's no more data to write or

// when an error occurs. The return value n is the number of bytes

// written. Any error encountered during the write is also returned.

type WriterTo interface {

WriteTo(w Writer) (n int64, err error)

}

// ReaderAt is the interface that wraps the basic ReadAt method.

//

// ReadAt reads len(p) bytes into p starting at offset off in the

// underlying input source. It returns the number of bytes

// read (0 <= n <= len(p)) and any error encountered.

//

// 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.

//

// If the n = len(p) bytes returned by ReadAt are at the end of the

// input source, ReadAt may return either err == EOF or err == nil.

//

// If ReadAt is reading from an input source with a seek offset,

// ReadAt should not affect nor be affected by the underlying

// seek offset.

//

// Clients of ReadAt can execute parallel ReadAt calls on the

// same input source.

//

// Implementations must not retain p.

type ReaderAt interface {

ReadAt(p []byte, off int64) (n int, err error)

}

// WriterAt is the interface that wraps the basic WriteAt method.

//

// WriteAt writes len(p) bytes from p to the underlying data stream

// at offset off. It returns the number of bytes written from p (0 <= n <= len(p))

// and any error encountered that caused the write to stop early.

// WriteAt must return a non-nil error if it returns n < len(p).

//

// If WriteAt is writing to a destination with a seek offset,

// WriteAt should not affect nor be affected by the underlying

// seek offset.

//

// Clients of WriteAt can execute parallel WriteAt calls on the same

// destination if the ranges do not overlap.

//

// Implementations must not retain p.

type WriterAt interface {

WriteAt(p []byte, off int64) (n int, err error)

}

// ByteReader is the interface that wraps the ReadByte method.

//

// ReadByte reads and returns the next byte from the input or

// any error encountered. If ReadByte returns an error, no input

// byte was consumed, and the returned byte value is undefined.

//

// ReadByte provides an efficient interface for byte-at-time

// processing. A [Reader] that does not implement ByteReader

// can be wrapped using bufio.NewReader to add this method.

type ByteReader interface {

ReadByte() (byte, error)

}

// ByteScanner is the interface that adds the UnreadByte method to the

// basic ReadByte method.

//

// UnreadByte causes the next call to ReadByte to return the last byte read.

// If the last operation was not a successful call to ReadByte, UnreadByte may

// return an error, unread the last byte read (or the byte prior to the

// last-unread byte), or (in implementations that support the [Seeker] interface)

// seek to one byte before the current offset.

type ByteScanner interface {

ReadByte() (byte, error)

UnreadByte() error

}

// ByteWriter is the interface that wraps the WriteByte method.

type ByteWriter interface {

WriteByte(c byte) error

}

// RuneSizeResult is the result of a [RuneReader.ReadRune] operation:

// the rune read, its size in bytes, and any error encountered.

type RuneSizeResult struct {

Rune rune

Size int

Err error

}

// RuneReader is the interface that wraps the ReadRune method.

//

// ReadRune reads a single encoded Unicode character

// and returns the rune and its size in bytes. If no character is

// available, err will be set.

type RuneReader interface {

ReadRune() RuneSizeResult

}

// RuneScanner is the interface that adds the UnreadRune method to the

// basic ReadRune method.

//

// UnreadRune causes the next call to ReadRune to return the last rune read.

// If the last operation was not a successful call to ReadRune, UnreadRune may

// return an error, unread the last rune read (or the rune prior to the

// last-unread rune), or (in implementations that support the [Seeker] interface)

// seek to the start of the rune before the current offset.

type RuneScanner interface {

ReadRune() RuneSizeResult

UnreadRune() error

}

// StringWriter is the interface that wraps the WriteString method.

type StringWriter interface {

WriteString(s string) (n int, err error)

}