Go 语言 io 文档的阅读摘录

本文基于 https://golang.org/pkg/io/ 在 2020 年 10 月 22 日的版本。

Overview

主要用于封装其他的 I/O primitives。不应假定并行执行是安全的。

Copy

拷贝直到 EOF 或出错。返回拷贝的字节数或首个遇到的错误。成功的 Copy 应该是 err==nil 而非 err==EOF。优先使用 src 的 WriteTo，其次是 dst 的 ReadFrom。

CopyBuffer

使用指定 buffer 的 Copy。可指定 buf==nil，会分配一个，在 src 不是 LimitedReader 的情况下默认大小为 32*1024。

Copy 和 CopyBuffer 调用的都是 func copyBuffer(dst Writer, src Reader, buf []byte) (written int64, err error)。Copy 指定 buf==nil；而 CopyBuffer 在调用前会检查 buf!=nil && len(buf)==0 的情况，在这种情况下 panic。

CopyN

拷贝 n 字节或直到出错，返回写入字节数及错误。当且仅当 err==nil 时 written==n。

Pipe

连接期望 io.Reader 的代码和期望 io.Writer 的代码，返回(*PipeReader, *PipeWriter)。PipeWriter 将在数据被 PipeReader 完全消费前阻塞。¹数据将直接从 Write 拷贝到 Read，没有内部的缓冲区。并行调用是安全的。

ReadAtLeast

从 r 中读入 buf 直到至少读了 min 字节（因为调用的是 Read，实际读取的字节数 n 可能超过 min）。提前 EOF 返回的错误不是 EOF 而是 ErrUnexpectedEOF。若 min>=len(buf)则返回 ErrShortBuffer。当且仅当 err==nil 时 n>=min。如果 r 在已经读取 min 字节时返回错误，则错误会被丢弃。

ReadFull

读 len(buf)个字节。只有没有读取到字节时才会返回 EOF。²

WriteString

若 w 实现了 StringWriter 接口则优先调用 WriteString 方法，否则调用 w.Write()。

ByteReader

ReadByte 返回下一字节或错误。如果返回错误，则输入字节不会被消耗，返回的字节值是未定义的。可以通过用 bufio.Reader 包裹一个 Reader 来增加这个方法。

ByteScanner

增加 UnreadByte 方法。³UnreadByte 后下一次 ReadByte 返回的内容会和前一次 ReadByte 相同。如果两次 UnreadByte 调用之间没有调用 ReadByte，则可能出错。

ByteWriter

WriteByte。

Closer

Close。多次调用 Close 的行为是未定义的，具体的实现可以在文档中记录它们自己的表现。

LimitedReader

从 R 中读，限制最多读 N 字节。N 是 max bytes remaining，每一次调用 Read 都会更新 N。当 N<=0 或 R 返回 EOF 时，Read 返回 EOF。

Read。

PipeReader

Close。

CloseWithError。返回值总是 nil。不会覆盖先前已有的错误。

Read。

PipeWriter

Close。

CloseWithError。

Write。

ReadCloser

顾名思义。

ReadSeeker

同上。

ReadWriteCloser

同上。

ReadWriteSeeker

同上。

ReadWriter

同上。

Reader

Read。如果数据不足 len(p)字节，则会返回而不是等待。EOF 可以在本次或下一次返回，例如输入流的最后在返回非零个字节的同时，可能返回 err==EOF 或 err==nil，而下一次 Read 会返回 0, EOF。调用者应该在考虑错误前，处理返回的非零个字节。Read 的实现不推荐返回 0, nil，除非 p==0。调用者应该把 0, nil 当成没有事情发生，特别要注意这不代表着 EOF。

LimitReader

在 n 个字节后以 EOF 停止。底层的实现是一个*LimitedReader。

MultiReader

串联 Reader，顺序读取，参数中在前者先读。所有输入均返回 EOF 则返回 EOF，若有返回非空非 EOF 错误则返回这个错误。

TeeReader⁴

从 r 读取写入 w 的一个 Reader。没有内部缓存区。写入时的错误会被报告为读取错误。

ReaderAt

ReadAt。从偏移位置 off 开始读 len(p)个字节。如果 n\<len(p)则会返回一个非空 error。（从这方面来说，ReadAt 比 Read 严格。）如果数据不足 len(p)字节，则 ReadAt 会阻塞，直到所有 len(p)字节数据都可获得，或者错误发生。（这也是 ReadAt 和 Read 的一个不同之处。）如果在输入的末端，返回的可以是 err==EOF 或 err==nil。如果从一个有 seek offset 的输入源读取，那么 ReadAt 不应影响其下的 seek offset 或被其影响。ReadAt 的客户端可以在同一个输入源中同时执行并行的 ReadAt 调用。实现不能继续持有 p。

ReaderFrom

ReadFrom。从 r 中读取，直到 EOF 或出错。⁵

RuneReader

ReadRune。

RuneScanner

增加 UnreadRune 方法。

SectionReader

在底层 ReaderAt 的一个 section 上实现 Read、Seek 和 ReadAt。

Read。

ReadAt。

Seek。

Size。

Seeker

Seek。设置下一个 Read 或 Write 的偏移量，相对于设定的 whence 即文件开头、文件结尾或当前偏移位置。返回相对开头的新偏移量。试图 seek 到开头之前的结果是一个错误。seek 到任意正的偏移量都是合法的，但在其下的对象上随后的 I/O 操作取决于实现。

StringWriter

WriteString。

WriteCloser

顾名思义。

WriteSeeker

同上。

Writer

Write。如果 n\<len(p)，则 Write 必须返回一个非空错误。Write 不能改变切片中的数据，即使只是暂时性的。

MultiWriter

创建一个 Writer，将写入的内容复写写入到所有的提供的 Writer 里面。⁶每一次写入会写到每一个列表中的 Writer，单次一个。如果其中一个发生错误，则整个写入过程将停止，并且返回错误，不会继续在列表中继续下去。

WriterAt

WriteAt。⁷

WriterTo

WriteTo。向 w 中写入，直到没有更多数据，或者出现错误。