io
Package io
import "io"
概况
索引
示例
子目录
概况
Package io 为 I/O 原语提供基本接口。它的主要工作是将这些原语的现有实现(例如包 os 中的那些原语)包装到抽象功能的共享公共接口中,以及一些其他相关原语中。
因为这些接口和原语用各种实现包装较低级别的操作,除非另有通知的客户端不应该认为它们对于并行执行是安全的。
索引
- 常量
- 变量
- func Copy(dst Writer, src Reader) (written int64, err error)
- func CopyBuffer(dst Writer, src Reader, buf []byte) (written int64, err error)
- func CopyN(dst Writer, src Reader, n int64) (written int64, err error)
- func ReadAtLeast(r Reader, buf []byte, min int) (n int, err error)
- func ReadFull(r Reader, buf []byte) (n int, err error)
- func WriteString(w Writer, s string) (n int, err error)
- type ByteReader
- type ByteScanner
- type ByteWriter
- type Closer
- type LimitedReader
- func (l *LimitedReader) Read(p []byte) (n int, err error)
- type PipeReader
- func Pipe() (*PipeReader, *PipeWriter)
- func (r *PipeReader) Close() error
- func (r *PipeReader) CloseWithError(err error) error
- func (r *PipeReader) Read(data []byte) (n int, err error)
- type PipeWriter
- func (w *PipeWriter) Close() error
- func (w *PipeWriter) CloseWithError(err error) error
- func (w *PipeWriter) Write(data []byte) (n int, err error)
- type ReadCloser
- type ReadSeeker
- type ReadWriteCloser
- type ReadWriteSeeker
- type ReadWriter
- type Reader
- func LimitReader(r Reader, n int64) Reader
- func MultiReader(readers ...Reader) Reader
- func TeeReader(r Reader, w Writer) Reader
- type ReaderAt
- type ReaderFrom
- type RuneReader
- type RuneScanner
- type SectionReader
- func NewSectionReader(r ReaderAt, off int64, n int64) *SectionReader
- func (s *SectionReader) Read(p []byte) (n int, err error)
- func (s *SectionReader) ReadAt(p []byte, off int64) (n int, err error)
- func (s *SectionReader) Seek(offset int64, whence int) (int64, error)
- func (s *SectionReader) Size() int64
- type Seeker
- type WriteCloser
- type WriteSeeker
- type Writer
- func MultiWriter(writers ...Writer) Writer
- type WriterAt
- type WriterTo
示例
Copy
包文件
常量
Seek 值。
const (
SeekStart = 0 // 寻找相对于文件的起源
SeekCurrent = 1 // 寻找相对于当前的偏移量
SeekEnd = 2 // 寻求相对于目的
)
变量
当没有更多输入可用时,EOF 是由 Read 返回的错误。函数只能返回 EOF 来表示输入的正常结束。如果 EOF 在结构化数据流中意外发生,则适当的错误是 ErrUnexpectedEOF 或其他一些错误,以提供更多详细信息。
var EOF = errors.New("EOF")
ErrClosedPipe 是用于在关闭的管道上进行读取或写入操作的错误。
var ErrClosedPipe = errors.New("io: read/write on closed pipe")
ErrNoProgress 是由一些 io.Reader 的客户端在许多 Read 的调用未能返回任何数据或错误(通常是破坏的 io.Reader 实现的标志)失败时返回的。
var ErrNoProgress = errors.New("multiple Read calls return no data or error")
ErrShortBuffer 意味着读取需要比提供的更长的缓冲区。
var ErrShortBuffer = errors.New("short buffer")
ErrShortWrite 意味着写入接受的字节数少于请求的数量,但未能返回明确的错误。
var ErrShortWrite = errors.New("short write")
ErrUnexpectedEOF 表示在读取固定大小块或数据结构的过程中遇到 EOF 。
var ErrUnexpectedEOF = errors.New("unexpected EOF")
func Copy(显示源代码)
func Copy(dst Writer, src Reader) (written int64, err error)
将副本从 src 复制到 dst ,直到在 src 上达到 EOF 或发生错误。它返回复制的字节数和复制时遇到的第一个错误(如果有的话)。
成功的复制返回err == nil,而不是err == EOF。由于 Copy 定义为从 src 读取直到 EOF,因此它不会将 Read 中的 EOF 视为要报告的错误。
如果 src 实现 WriterTo 接口,则通过调用 src.WriteTo(dst)来实现副本。否则,如果 dst 实现 ReaderFrom 接口,则通过调用 dst.ReadFrom(src)来实现副本。
示例
package main
import (
"io"
"log"
"os"
"strings"
)
func main() {
r := strings.NewReader("some io.Reader stream to be read\n")
if _, err := io.Copy(os.Stdout, r err != nil {
log.Fatal(err)
}
}
func CopyBuffer(显示源代码)
func CopyBuffer(dst Writer, src Reader, buf []byte) (written int64, err error)
CopyBuffer 与 Copy 相同,只是它通过提供的缓冲区(如果需要的话)进行分级,而不是分配临时的缓冲区。如果 buf 为零,则分配一个;否则如果它的长度为零,CopyBuffer 会发生混乱。
示例
package main
import (
"io"
"log"
"os"
"strings"
)
func main() {
r1 := strings.NewReader("first reader\n")
r2 := strings.NewReader("second reader\n")
buf := make([]byte, 8)
// 在这里使用buf ...
if _, err := io.CopyBuffer(os.Stdout, r1, buf err != nil {
log.Fatal(err)
}
// ...也在这里重复使用。 无需分配额外的缓冲区。
if _, err := io.CopyBuffer(os.Stdout, r2, buf err != nil {
log.Fatal(err)
}
}
func CopyN(显示源代码)
func CopyN(dst Writer, src Reader, n int64) (written int64, err error)
CopyN 拷贝从 src 到 dst 的 n 个字节(或直出现一个错误)。它返回拷贝的字节数和复制时遇到的最早的错误。返回时,written == n 当且仅当 err == nil 。
如果 dst 实现 ReaderFrom 接口,则使用它实现副本。
示例
package main
import (
"io"
"log"
"os"
"strings"
)
func main() {
r := strings.NewReader("some io.Reader stream to be read")
if _, err := io.CopyN(os.Stdout, r, 5 err != nil {
log.Fatal(err)
}
}
func ReadAtLeast(显示源代码)
func ReadAtLeast(r Reader, buf []byte, min int) (n int, err error)
ReadAtLeast 从 r 读入 buf,直到它读取至少最小字节。它返回复制的字节数,如果读取的字节更少,则返回错误。只有在没有字节被读取的情况下,错误才是 EOF 。如果在读取少于最小字节数后发生 EOF,则 ReadAtLeast 返回 ErrUnexpectedEOF 。如果 min 大于 buf 的长度,则 ReadAtLeast 返回 ErrShortBuffer。返回时,n> = min 当且仅当 err == nil 。
示例
package main
import (
"fmt"
"io"
"log"
"strings"
)
func main() {
r := strings.NewReader("some io.Reader stream to be read\n")
buf := make([]byte, 33)
if _, err := io.ReadAtLeast(r, buf, 4 err != nil {
log.Fatal(err)
}
fmt.Printf("%s\n", buf)
// 缓冲区小于最小读取大小。
shortBuf := make([]byte, 3)
if _, err := io.ReadAtLeast(r, shortBuf, 4 err != nil {
fmt.Println("error:", err)
}
// 最小读取大小比io.Reader流大
longBuf := make([]byte, 64)
if _, err := io.ReadAtLeast(r, longBuf, 64 err != nil {
fmt.Println("error:", err)
}
}
func ReadFull(显示源代码)
func ReadFull(r Reader, buf []byte) (n int, err error)
ReadFull 完全读取从 r 到 buf 的 len(buf) 个字节。它返回复制的字节数,如果读取的字节更少,则返回错误。只有在没有字节被读取的情况下,错误才是 EOF 。如果在读取一些但不是全部字节后发生 EOF,则 ReadFull 将返回 ErrUnexpectedEOF 。返回时,n == len(buf) 当且仅当 err == nil 。
示例
package main
import (
"fmt"
"io"
"log"
"strings"
)
func main() {
r := strings.NewReader("some io.Reader stream to be read\n")
buf := make([]byte, 4)
if _, err := io.ReadFull(r, buf err != nil {
log.Fatal(err)
}
fmt.Printf("%s\n", buf)
// 最小读取大小比io.Reader流大
longBuf := make([]byte, 64)
if _, err := io.ReadFull(r, longBuf err != nil {
fmt.Println("error:", err)
}
}
func WriteString(显示源代码)
func WriteString(w Writer, s string) (n int, err error)
WriteString 将字符串 s 的内容写入 w,它接受一个字节片段。如果 w 实现 WriteString 方法,则直接调用它。否则,w.Write 只会被调用一次。
示例
package main
import (
"io"
"os"
)
func main() {
io.WriteString(os.Stdout, "Hello World")
}
type ByteReader(显示源代码)
ByteReader 是包装 ReadByte 方法的接口。
ReadByte 读取并返回输入中的下一个字节或遇到的任何错误。如果 ReadByte 返回错误,则不消耗输入字节,并且返回的字节值未定义。
type ByteReader interface {
ReadByte() (byte, error)
}
type ByteScanner(显示源代码)
ByteScanner 是将 UnreadByte 方法添加到基本 ReadByte 方法的接口。
UnreadByte 导致下一次对 ReadByte 的调用返回与先前对 ReadByte 的调用相同的字节。在没有对 ReadByte 的中间调用的情况下调用 UnreadByte 两次可能是错误的。
type ByteScanner interface {
ByteReader
UnreadByte() error
}
type ByteWriter(显示源代码)
ByteWriter 是包装 WriteByte 方法的接口。
type ByteWriter interface {
WriteByte(c byte) error
}
type Closer(显示源代码)
Closer 是包装基本 Close 方法的接口。
第一次调用后 Close 的行为是未定义的。具体实现可以记录他们自己的行为。
type Closer interface {
Close() error
}
type LimitedReader(显示源代码)
LimitedReader 从 R 中读取数据,但将数据量限制为仅返回 N 个字节。每次读取更新 N 将反映新的剩余金额。当 N <= 0 或当基础 R 返回 EOF 时,读取返回 EOF 。
type LimitedReader struct {
R Reader // 底层阅读器
N int64 // 剩余最大字节数
}
func (*LimitedReader) Read(显示源代码)
func (l *LimitedReader) Read(p []byte) (n int, err error)
type PipeReader(显示源代码)
PipeReader 是pipe的二分之一read。
type PipeReader struct {
// 包含已过滤或未导出的字段
}
func Pipe(显示源代码)
func Pipe() (*PipeReader, *PipeWriter)
Pipe 创建一个同步内存管道。它可以用来连接代码期望一个 io.Reader 与代码期待一个 io.Writer 。
读取和写入管道是一对一匹配的,除非需要多个读取消耗单个写入。也就是说,对 PipeWriter 的每次写入都会阻塞,直到它满足 PipeReader 中完全使用写入数据的一个或多个读取。数据直接从写入复制到相应的 Read(或 Reads); 没有内部缓冲。
相互并行或使用 Close 并行调用 Read 和 Write 是安全的。并行调用读取和并行调用写入也是安全的:个别调用将按顺序进行门控。
func (*PipeReader) Close(显示源代码)
func (r *PipeReader) Close() error
Close 关闭阅读器;随后写入管道的写入一半将返回错误 ErrClosedPipe 。
func (*PipeReader) CloseWithError(显示源代码)
func (r *PipeReader) CloseWithError(err error) error
CloseWithError 关闭阅读器;随后写入管道的写入一半将返回错误 err 。
func (*PipeReader) Read(显示源代码)
func (r *PipeReader) Read(data []byte) (n int, err error)
Read 实现标准的 Read 接口:它从管道读取数据,阻塞直到写入者到达或写入结束被关闭。如果写入结束时出现错误,则该错误返回为错误;否则 err 是 EOF 。
type PipeWriter(显示源代码)
PipeWriter 是写入一半的管道。
type PipeWriter struct {
// 包含已过滤或未导出的字段
}
func (*PipeWriter) Close(显示源代码)
func (w *PipeWriter) Close() error
Close 关闭写入者;后续读取管道的一半将不返回字节和 EOF 。
func (*PipeWriter) CloseWithError(显示源代码)
func (w *PipeWriter) CloseWithError(err error) error
CloseWithError 关闭写入者;从管道的读取一半的后续读取将返回没有字节和 error 错误,或如果错误为零则为 EOF 。
CloseWithError 总是返回 nil 。
func (*PipeWriter) Write(显示源代码)
func (w *PipeWriter) Write(data []byte) (n int, err error)
Write 实现了标准的 Write 接口:它将数据写入管道,阻塞直到一个或多个读取器消耗完所有数据或读取端关闭。如果读取结束时出现错误,则该错误返回为 err ; 否则 err 是 ErrClosedPipe 。
type ReadCloser(显示源代码)
ReadCloser 是分组基本的 Read 和 Close 方法的接口。
type ReadCloser interface {
Reader
Closer
}
type ReadSeeker(显示源代码)
ReadSeeker 是将基本的 Read 和 Seek 方法分组的接口。
type ReadSeeker interface {
Reader
Seeker
}
type ReadWriteCloser(显示源代码)
ReadWriteCloser 是对基本的 Read,Write 和 Close 方法进行分组的接口。
type ReadWriteCloser interface {
Reader
Writer
Closer
}
type ReadWriteSeeker(显示源代码)
ReadWriteSeeker 是将基本的 Read,Write 和 Seek 方法分组的接口。
type ReadWriteSeeker interface {
Reader
Writer
Seeker
}
type ReadWriter(显示源代码)
ReadWriter 是分组基本读写方法的接口。
type ReadWriter interface {
Reader
Writer
}
type Reader(显示源代码)
Reader 是包装基本 Read 方法的接口。
Read 读取 len(p)个字节到 p 。它返回读取的字节数(0 <= n <= len(p))和遇到的任何错误。即使 Read 返回 n <len(p),它也可以在调用期间将全部 p 用作暂存空间。如果某些数据可用但不是 len(p) 字节,则 Read 通常返回可用的数据,而不是等待更多数据。
当 Read 在成功读取 n> 0 字节后遇到错误或文件结束条件时,它会返回读取的字节数。它可能会从相同的调用中返回(非零)错误,或者从后续调用中返回错误(和 n == 0)。这种一般情况的一个实例是,在输入流末尾返回非零字节数的 Reader 可能会返回 err == EOF 或 err == nil 。下一个 Read 应该返回 0,EOF 。
在考虑错误错误之前,Callers 应始终处理返回的 n> 0 个字节。这样做可以正确处理读取一些字节后发生的 I/O 错误以及两种允许的 EOF 行为。
除非 len(p)== 0,否则 Read 的实现不鼓励返回零字节的计数和零错误。调用者应该将返回值 0 和零作为表示什么都没有发生; 特别是它不表示 EOF 。
Implementations 不能保留 p 。
type Reader interface {
Read(p []byte) (n int, err error)
}
func LimitReader(显示源代码)
func LimitReader(r Reader, n int64) Reader
LimitReader 返回一个 Reader,它从 r 读取,但在 n 字节后用 EOF 停止。底层的实现是一个 *LimitedReader 。
示例
package main
import (
"io"
"log"
"os"
"strings"
)
func main() {
r := strings.NewReader("some io.Reader stream to be read\n")
lr := io.LimitReader(r, 4)
if _, err := io.Copy(os.Stdout, lr err != nil {
log.Fatal(err)
}
}
func MultiReader(显示源代码)
func MultiReader(readers ...Reader) Reader
MultiReader 返回一个 Reader,它是提供的输入读取器的逻辑连接。他们顺序阅读。一旦所有输入都返回 EOF,Read 将返回 EOF 。如果任何阅读器返回非零非 EOF 错误,则 Read 将返回该错误。
示例
package main
import (
"io"
"log"
"os"
"strings"
)
func main() {
r1 := strings.NewReader("first reader ")
r2 := strings.NewReader("second reader ")
r3 := strings.NewReader("third reader\n")
r := io.MultiReader(r1, r2, r3)
if _, err := io.Copy(os.Stdout, r err != nil {
log.Fatal(err)
}
}
func TeeReader(显示源代码)
func TeeReader(r Reader, w Writer) Reader
TeeReader 返回一个读写器,它读写从 r 读取的内容。从 r 执行的所有读取操作都与 w 的相应写入相匹配。没有内部缓冲 - 写入必须在读取完成之前完成。写入时遇到的任何错误都会报告为读取错误。
示例
package main
import (
"bytes"
"fmt"
"io"
"io/ioutil"
"log"
"strings"
)
func main() {
r := strings.NewReader("some io.Reader stream to be read\n")
var buf bytes.Buffer
tee := io.TeeReader(r, &buf)
printall := func(r io.Reader) {
b, err := ioutil.ReadAll(r)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%s", b)
}
printall(tee)
printall(&buf)
}
type ReaderAt(显示源代码)
ReaderAt 是包装基本 ReadAt 方法的接口。
ReadAt 将 len(p) 个字节读入底层输入源的偏移 off 开始的 p 。它返回读取的字节数 (0 <= n <= len(p)) 和遇到的任何错误。
当 ReadAt 返回 n <len(p) 时,它将返回一个非零错误,解释为什么不返回更多字节。在这方面,ReadAt 比 Read 更严格。
即使 ReadAt 返回 n <len(p),它也可能在调用期间将所有 p 用作临时空间。如果有些数据可用但不是 len(p) 字节,则 ReadAt 阻塞,直到所有数据都可用或发生错误。在这方面,ReadAt 与 Read 不同。
如果 ReadAt 返回的 n = len(p) 字节位于输入源的末尾,则 ReadAt 可能会返回 err == EOF 或 err == nil 。
如果 ReadAt 正在从具有查找偏移量的输入源读取,则 ReadAt 不应受影响,也不应受基础查找偏移量的影响。
ReadAt 的客户端可以在同一个输入源上执行并行 ReadAt 调用。
实现不能保留 p 。
type ReaderAt interface {
ReadAt(p []byte, off int64) (n int, err error)
}
type ReaderFrom(显示源代码)
ReaderFrom 是包装 ReadFrom 方法的接口。
ReadFrom 从 r 读取数据直到出现 EOF 或错误。返回值 n 是读取的字节数。读取过程中遇到的除 io.EOF 外的任何错误也会返回。
复制功能使用 ReaderFrom(如果可用)。
type ReaderFrom interface {
ReadFrom(r Reader) (n int64, err error)
}
type RuneReader(显示源代码)
RuneReader 是包装 ReadRune 方法的接口。
ReadRune 读取单个 UTF-8 编码的 Unicode 字符,并以字节为单位返回符文及其大小。如果没有可用的字符,则会设置 err 。
type RuneReader interface {
ReadRune() (r rune, size int, err error)
}
type RuneScanner(显示源代码)
RuneScanner 是将 UnreadRune 方法添加到基本 ReadRune 方法的接口。
UnreadRune 会导致下一次对 ReadRune 的调用返回与先前对 ReadRune 的调用相同的符文。在没有对 ReadRune 的中间调用的情况下调用 UnreadRune 可能是错误的。
type RuneScanner interface {
RuneReader
UnreadRune() error
}
type SectionReader(显示源代码)
SectionReader 在基础 ReaderAt 的一部分上实现 Read,Seek 和 ReadAt 。
type SectionReader struct {
// 包含已过滤或未导出的字段
}
示例
package main
import (
"io"
"log"
"os"
"strings"
)
func main() {
r := strings.NewReader("some io.Reader stream to be read\n")
s := io.NewSectionReader(r, 5, 17)
if _, err := io.Copy(os.Stdout, s err != nil {
log.Fatal(err)
}
}
func NewSectionReader(显示源代码)
func NewSectionReader(r ReaderAt, off int64, n int64) *SectionReader
NewSectionReader 返回一个 SectionReader,它从 r 处开始读取 offset,并在 n 字节后用 EOF 停止。
func (*SectionReader) Read(显示源代码)
func (s *SectionReader) Read(p []byte) (n int, err error)
func (*SectionReader) ReadAt(显示源代码)
func (s *SectionReader) ReadAt(p []byte, off int64) (n int, err error)
示例
package main
import (
"fmt"
"io"
"log"
"strings"
)
func main() {
r := strings.NewReader("some io.Reader stream to be read\n")
s := io.NewSectionReader(r, 5, 16)
buf := make([]byte, 6)
if _, err := s.ReadAt(buf, 10 err != nil {
log.Fatal(err)
}
fmt.Printf("%s\n", buf)
}
func (*SectionReader) Seek(显示源代码)
func (s *SectionReader) Seek(offset int64, whence int) (int64, error)
示例
package main
import (
"fmt"
"io"
"log"
"strings"
)
func main() {
r := strings.NewReader("some io.Reader stream to be read\n")
s := io.NewSectionReader(r, 5, 16)
if _, err := s.Seek(10, io.SeekStart err != nil {
log.Fatal(err)
}
buf := make([]byte, 6)
if _, err := s.Read(buf err != nil {
log.Fatal(err)
}
fmt.Printf("%s\n", buf)
}
func (*SectionReader) Size(显示源代码)
func (s *SectionReader) Size() int64
大小以字节为单位返回该部分的大小。
type Seeker(显示源代码)
Seeker 是包装基本 Seek 方法的接口。
Seek 设置下一个读取或写入偏移量的偏移量,根据此解释:SeekStart 表示相对于文件的开始,SeekCurrent 表示相对于当前偏移量,SeekEnd 表示相对于结束。Seek 返回相对于文件开始的新偏移量和一个错误(如果有的话)。
在文件开始之前寻找偏移量是一个错误。寻求任何正偏移量是合法的,但后续对基础对象的 I/O 操作的行为取决于实现。
type Seeker interface {
Seek(offset int64, whence int) (int64, error)
}
type WriteCloser(显示源代码)
WriteCloser 是分组基本 Write 和 Close 方法的接口。
type WriteCloser interface {
Writer
Closer
}
type WriteSeeker(显示源代码)
WriteSeeker 是将基本写入和查找方法分组的接口。
type WriteSeeker interface {
Writer
Seeker
}
type Writer(显示源代码)
Writer 是包装基本 Write 方法的接口。
写从 p 写入 len(p) 个字节到底层数据流。它返回从p (0 <= n <= len(p)) 写入的字节数,以及遇到任何导致写入提前停止的错误。如果返回 n < len(p),则写入必须返回非零错误。写入不能修改片数据,即使是暂时的。
实现不能保留 p 。
type Writer interface {
Write(p []byte) (n int, err error)
}
func MultiWriter(显示源代码)
func MultiWriter(writers ...Writer) Writer
MultiWriter 创建一个写入器,将其写入所有提供的写入器,类似于 Unix tee(1) 命令。
示例
package main
import (
"bytes"
"fmt"
"io"
"log"
"strings"
)
func main() {
r := strings.NewReader("some io.Reader stream to be read\n")
var buf1, buf2 bytes.Buffer
w := io.MultiWriter(&buf1, &buf2)
if _, err := io.Copy(w, r err != nil {
log.Fatal(err)
}
fmt.Print(buf1.String())
fmt.Print(buf2.String())
}
type WriterAt(显示源代码)
WriterAt 是包装基本 WriteAt 方法的接口。
WriteAt 将 p 的 len(p) 个字节写入偏移关闭的基础数据流。它返回从 p (0 <= n <= len(p))写入的字节数,以及遇到任何导致写入提前停止的错误。如果返回 n < len(p),WriteAt 必须返回非零错误。
如果 WriteAt 正在使用搜索偏移量写入目标,则 WriteAt 不应受影响,也不应受底层搜索偏移量的影响。
如果范围不重叠,则 WriteAt 的客户端可以在同一个目的地上执行并行 WriteAt 调用。
实现不能保留 p 。
type WriterAt interface {
WriteAt(p []byte, off int64) (n int, err error)
}
type WriterTo(显示源代码)
WriterTo 是包装 WriteTo 方法的接口。
WriteTo 将数据写入 w,直到没有更多数据要写入或出现错误时为止。返回值 n 是写入的字节数。写入过程中遇到的任何错误也会返回。
复制功能使用 WriterTo(如果可用)。
type WriterTo interface {
WriteTo(w Writer) (n int64, err error)
}
子目录
Name | Synopsis |
---|---|
ioutil | Package ioutil实现了一些 I/O 实用程序功能。 |