Go语言标准库_输入／输出

转载节选自《Go语言标准库》

Reader 接口

type Reader interface {
    Read(p []byte) (n int, err error)
}

Read 将 len(p) 个字节读取到 p 中。它返回读取的字节数 n（0 <= n <= len(p)） 以及任何遇到的错误。即使 Read 返回的 n < len(p)，它也会在调用过程中使用 p 的全部作为暂存空间。若一些数据可用但不到 len(p) 个字节，Read 会照例返回可用的数据，而不是等待更多数据。

当 Read 在成功读取 n > 0 个字节后遇到一个错误或 EOF (end-of-file)，它就会返回读取的字节数。它会从相同的调用中返回（非nil的）错误或从随后的调用中返回错误（同时 n == 0）。 一般情况的一个例子就是 Reader 在输入流结束时会返回一个非零的字节数，同时返回的 err 不是 EOF 就是 nil。无论如何，下一个 Read 都应当返回 0, EOF。

调用者应当总在考虑到错误 err 前处理 n > 0 的字节。这样做可以在读取一些字节，以及允许的 EOF 行为后正确地处理 I/O 错误。

Writer

type Writer interface {
    Write(p []byte) (n int, err error)
}

Write 将 len(p) 个字节从 p 中写入到基本数据流中。它返回从 p 中被写入的字节数 n（0 <= n <= len(p)）以及任何遇到的引起写入提前停止的错误。若 Write 返回的 n < len(p)，它就必须返回一个 非nil 的错误。

实现了 io.Reader 接口或 io.Writer 接口的类型

• os.File 同时实现了 io.Reader 和 io.Writer
• strings.Reader 实现了 io.Reader
• bufio.Reader/Writer 分别实现了 io.Reader 和 io.Writer
• bytes.Buffer 同时实现了 io.Reader 和 io.Writer
• bytes.Reader 实现了 io.Reader
• compress/gzip.Reader/Writer 分别实现了 io.Reader 和 io.Writer
• crypto/cipher.StreamReader/StreamWriter 分别实现了 io.Reader 和 io.Writer
• crypto/tls.Conn 同时实现了 io.Reader 和 io.Writer
• encoding/csv.Reader/Writer 分别实现了 io.Reader 和 io.Writer
• mime/multipart.Part 实现了 io.Reader
  ?

ReaderAt/WriterAt 接口

type ReaderAt interface {
    ReadAt(p []byte, off int64) (n int, err error)
}

ReadAt 从基本输入源的偏移量 off 处开始，将 len(p) 个字节读取到 p 中。它返回读取的字节数 n（0 <= n <= len(p)）以及任何遇到的错误。

当 ReadAt 返回的 n < len(p) 时，它就会返回一个 非nil 的错误来解释 为什么没有返回更多的字节。在这一点上，ReadAt 比 Read 更严格。

即使 ReadAt 返回的 n < len(p)，它也会在调用过程中使用 p 的全部作为暂存空间。若一些数据可用但不到 len(p) 字节，ReadAt 就会阻塞直到所有数据都可用或产生一个错误。 在这一点上 ReadAt 不同于 Read。

若 n = len(p) 个字节在输入源的的结尾处由 ReadAt 返回，那么这时 err == EOF 或者 err == nil。

若 ReadAt 按查找偏移量从输入源读取，ReadAt 应当既不影响基本查找偏移量也不被它所影响。

ReadAt 的客户端可对相同的输入源并行执行 ReadAt 调用。

type WriterAt interface {
    WriteAt(p []byte, off int64) (n int, err error)
}

WriteAt 从 p 中将 len(p) 个字节写入到偏移量 off 处的基本数据流中。它返回从 p 中被写入的字节数 n（0 <= n <= len(p)）以及任何遇到的引起写入提前停止的错误。若 WriteAt 返回的 n < len(p)，它就必须返回一个 非nil 的错误。

若 WriteAt 按查找偏移量写入到目标中，WriteAt 应当既不影响基本查找偏移量也不被它所影响。

若区域没有重叠，WriteAt 的客户端可对相同的目标并行执行 WriteAt 调用。

ReaderFrom/WriterTo 接口

type ReaderFrom interface {
    ReadFrom(r Reader) (n int64, err error)
}

ReadFrom 从 r 中读取数据，直到 EOF 或发生错误。其返回值 n 为读取的字节数。除 io.EOF 之外，在读取过程中遇到的任何错误也将被返回。

如果 ReaderFrom 可用，Copy 函数就会使用它。

type WriterTo interface {
    WriteTo(w Writer) (n int64, err error)
}

WriteTo 将数据写入 w 中，直到没有数据可写或发生错误。其返回值 n 为写入的字节数。 在写入过程中遇到的任何错误也将被返回。

如果 WriterTo 可用，Copy 函数就会使用它。

Seeker 接口

type Seeker interface {
    Seek(offset int64, whence int) (ret int64, err error)
}

Seek 设置下一次 Read 或 Write 的偏移量为 offset，它的解释取决于 whence： 0 表示相对于文件的起始处，1 表示相对于当前的偏移，而 2 表示相对于其结尾处。 Seek 返回新的偏移量和一个错误，如果有的话。

whence 的值，在 os 包中定义了相应的常量，应该使用这些常量

const (
    SEEK_SET int = 0 // seek relative to the origin of the file
    SEEK_CUR int = 1 // seek relative to the current offset
    SEEK_END int = 2 // seek relative to the end
)

Closer接口

type Closer interface {
    Close() error
}

ByteReader 和 ByteWriter

type ByteReader interface {
    ReadByte() (c byte, err error)
}

type ByteWriter interface {
    WriteByte(c byte) error
}

在标准库中，有如下类型实现了 io.ByteReader 或 io.ByteWriter:

• bufio.Reader/Writer 分别实现了io.ByteReader 和 io.ByteWriter
• bytes.Buffer 同时实现了 io.ByteReader 和 io.ByteWriter
• bytes.Reader 实现了 io.ByteReader
• strings.Reader 实现了 io.ByteReader

ByteScanner、RuneReader 和 RuneScanner