package io

import "io"

@H_301_7@io包提供了对@H_301_7@I/O原语的基本接口。本包的基本任务是包装这些原语已有的实现（如@H_301_7@os包里的原语），使之成为共享的公共接口，这些公共接口抽象出了泛用的函数并附加了一些相关的原语的操作。

因为这些接口和原语是对底层实现完全不同的低水平操作的包装，除非得到其它方面的通知，客户端不应假设它们是并发执行安全的。

Index

• Variables
• type Reader
• type Writer
• type Closer
• type Seeker
• type ReadCloser
• type ReadSeeker
• type WriteCloser
• type WriteSeeker
• type ReadWriter
• type ReadWriteCloser
• type ReadWriteSeeker
• type ReaderAt
• type WriterAt
• type ByteReader
• type ByteScanner
• type RuneReader
• type RuneScanner
• type ByteWriter
• type ReaderFrom
• type WriterTo
• type LimitedReader
• func LimitReader(r Reader,n int64) Reader
• func (l *LimitedReader) Read(p []byte) (n int,err error)
• type SectionReader
• func NewSectionReader(r ReaderAt,off int64,n int64) *SectionReader
• func (s *SectionReader) Size() int64
• 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)
• type PipeReader
• func Pipe() (*PipeReader,*PipeWriter)
• func (r *PipeReader) Read(data []byte) (n int,err error)
• func (r *PipeReader) Close() error
• func (r *PipeReader) CloseWithError(err error) error
• type PipeWriter
• func (w *PipeWriter) Write(data []byte) (n int,err error)
• func (w *PipeWriter) Close() error
• func (w *PipeWriter) CloseWithError(err error) error
• func TeeReader(r Reader,w Writer) Reader
• func MultiReader(readers ...Reader) Reader
• func MultiWriter(writers ...Writer) Writer
• func Copy(dst Writer,src Reader) (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)

Variables

var @H_301_7@EOF = errors.New("EOF")

@H_301_7@EOF当无法得到更多输入时，@H_301_7@Read方法返回@H_301_7@EOF。当函数一切正常的到达输入的结束时，就应返回@H_301_7@EOF。如果在一个结构化数据流中@H_301_7@EOF在不期望的位置出现了，则应返回错误@H_301_7@ErrUnexpectedEOF或者其它给出更多细节的错误。

var @H_301_7@ErrClosedPipe = errors.New("io: read/write on closed pipe")

当从一个已关闭的@H_301_7@Pipe读取或者写入时，会返回@H_301_7@ErrClosedPipe。

var @H_301_7@ErrNoProgress = errors.New("multiple Read calls return no data or error")

某些使用@H_301_7@io.Reader接口的客户端如果多次调用@H_301_7@Read都不返回数据也不返回错误时，就会返回本错误，一般来说是@H_301_7@io.Reader的实现有问题的标志。

var @H_301_7@ErrShortBuffer = errors.New("short buffer")

@H_301_7@ErrShortBuffer表示读取操作需要大缓冲，但提供的缓冲不够大。

var @H_301_7@ErrShortWrite = errors.New("short write")

@H_301_7@ErrShortWrite表示写入操作写入的数据比提供的少，却没有显式的返回错误。

var @H_301_7@ErrUnexpectedEOF = errors.New("unexpected EOF")

@H_301_7@ErrUnexpectedEOF表示在读取一个固定尺寸的块或者数据结构时，在读取未完全时遇到了@H_301_7@EOF。

typeReader

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

@H_301_7@Reader接口用于包装基本的读取方法。

@H_301_7@Read方法读取@H_301_7@len(p)字节数据写入@H_301_7@p。它返回写入的字节数和遇到的任何错误。即使@H_301_7@Read方法返回值@H_301_7@n < len(p)，本方法在被调用时仍可能使用@H_301_7@p的全部长度作为暂存空间。如果有部分可用数据，但不够@H_301_7@len(p)字节，@H_301_7@Read按惯例会返回可以读取到的数据，而不是等待更多数据。

当@H_301_7@Read在读取@H_301_7@n > 0个字节后遭遇错误或者到达文件结尾时，会返回读取的字节数。它可能会在该次调用返回一个非@H_301_7@nil的错误，或者在下一次调用时返回@H_301_7@0和该错误。一个常见的例子，@H_301_7@Reader接口会在输入流的结尾返回非@H_301_7@0的字节数，返回值@H_301_7@err == EOF或@H_301_7@err == nil。但不管怎样，下一次@H_301_7@Read调用必然返回@H_301_7@(0,EOF)。调用者应该总是先处理读取的@H_301_7@n > 0字节再处理错误值。这么做可以正确的处理发生在读取部分数据后的@H_301_7@I/O错误，也能正确处理@H_301_7@EOF事件。

如果@H_301_7@Read的某个实现返回@H_301_7@0字节数和@H_301_7@nil错误值，表示被阻碍；调用者应该将这种情况视为未进行操作。

typeWriter

type Writer interface { @H_301_7@Write(p []byte) (n int,sans-serif;font-size:14px;background-color:#FFFFFF;"> @H_301_7@Writer接口用于包装基本的写入方法。 
 
 @H_301_7@Write方法@H_301_7@len(p)字节数据从@H_301_7@p写入底层的数据流。它会返回写入的字节数@H_301_7@(0 <= n <= len(p))和遇到的任何导致写入提取结束的错误。@H_301_7@Write必须返回非@H_301_7@nil的错误，如果它返回的@H_301_7@n < len(p)。@H_301_7@Write不能修改切片@H_301_7@p中的数据，即使临时修改也不行。 
 
 
 typeCloser 
 
type Closer interface { @H_301_7@Close() error }
 
 @H_301_7@Closer接口用于包装基本的关闭方法。 
 
 在第一次调用之后再次被调用时，@H_301_7@Close方法的的行为是未定义的。某些实现可能会说明他们自己的行为。 
 
 
 typeSeeker 
 
type Seeker interface { @H_301_7@Seek(offset int64,whence int) (int64,error)
}
 
 @H_301_7@Seeker接口用于包装基本的移位方法。 
 
 @H_301_7@Seek方法设定下一次读写的位置：偏移量为@H_301_7@offset，校准点由@H_301_7@whence确定：@H_301_7@0表示相对于文件起始；@H_301_7@1表示相对于当前位置；@H_301_7@2表示相对于文件结尾。@H_301_7@Seek方法返回新的位置以及可能遇到的错误。 
 
 移动到一个绝对偏移量为负数的位置会导致错误。移动到任何偏移量为正数的位置都是合法的，但其下一次@H_301_7@I/O操作的具体行为则要看底层的实现。 
 
 
 typeReadCloser 
 
type ReadCloser interface { Reader Closer }
 
 @H_301_7@ReadCloser接口聚合了基本的读取和关闭操作。 
 
 
 typeReadSeeker 
 
type ReadSeeker interface { Reader Seeker }
 
 @H_301_7@ReadSeeker接口聚合了基本的读取和移位操作。 
 
 
 typeWriteCloser 
 
type WriteCloser interface { Writer Closer }
 
 @H_301_7@WriteCloser接口聚合了基本的写入和关闭操作。 
 
 
 typeWriteSeeker 
 
type WriteSeeker interface { Writer Seeker }
 
 @H_301_7@WriteSeeker接口聚合了基本的写入和移位操作。 
 
 
 typeReadWriter 
 
type ReadWriter interface { Reader Writer }
 
 @H_301_7@ReadWriter接口聚合了基本的读写操作。 
 
 
 typeReadWriteCloser 
 
type ReadWriteCloser interface { Reader Writer Closer }
 
 @H_301_7@ReadWriteCloser接口聚合了基本的读写和关闭操作。 
 
 
 typeReadWriteSeeker 
 
type ReadWriteSeeker interface { Reader Writer Seeker }
 
 @H_301_7@ReadWriteSeeker接口聚合了基本的读写和移位操作。 
 
 
 typeReaderAt 
 
type ReaderAt interface { @H_301_7@ReadAt(p []byte,off int64) (n int,sans-serif;font-size:14px;background-color:#FFFFFF;"> @H_301_7@ReaderAt接口包装了基本的@H_301_7@ReadAt方法。 
 
 @H_301_7@ReadAt从底层输入流的偏移量@H_301_7@off位置读取@H_301_7@len(p)字节数据写入@H_301_7@p，它返回读取的字节数@H_301_7@(0 <= n <= len(p))和遇到的任何错误。当@H_301_7@ReadAt方法返回值@H_301_7@n < len(p)时，它会返回一个非@H_301_7@nil的错误来说明为啥没有读取更多的字节。在这方面，@H_301_7@ReadAt是比@H_301_7@Read要严格的。即使@H_301_7@ReadAt方法返回值@H_301_7@n < len(p)，它在被调用时仍可能使用@H_301_7@p的全部长度作为暂存空间。如果有部分可用数据，但不够@H_301_7@len(p)字节，@H_301_7@ReadAt会阻塞直到获取@H_301_7@len(p)个字节数据或者遇到错误。在这方面，@H_301_7@ReadAt和@H_301_7@Read是不同的。如果@H_301_7@ReadAt返回时到达输入流的结尾，而返回值@H_301_7@n == len(p)，其返回值@H_301_7@err既可以是@H_301_7@EOF也可以是@H_301_7@nil。 
 
 如果@H_301_7@ReadAt是从某个有偏移量的底层输入流（的@H_301_7@Reader包装）读取，@H_301_7@ReadAt方法既不应影响底层的偏移量，也不应被底层的偏移量影响。 
 
 @H_301_7@ReadAt方法的调用者可以对同一输入流执行并行的@H_301_7@ReadAt调用。 
 
 
 typeWriterAt 
 
type WriterAt interface { @H_301_7@WriteAt(p []byte,sans-serif;font-size:14px;background-color:#FFFFFF;"> @H_301_7@WriterAt接口包装了基本的@H_301_7@WriteAt方法。 
 
 @H_301_7@WriteAt将@H_301_7@p全部@H_301_7@len(p)字节数据写入底层数据流的偏移量@H_301_7@off位置。它返回写入的字节数@H_301_7@(0 <= n <= len(p))和遇到的任何导致写入提取中止的错误。当其返回值@H_301_7@n < len(p)时，@H_301_7@WriteAt必须放哪会一个非@H_301_7@nil的错误。 
 
 如果@H_301_7@WriteAt写入的对象是某个有偏移量的底层输出流（的@H_301_7@Writer包装），@H_301_7@WriteAt方法既不应影响底层的偏移量，也不应被底层的偏移量影响。 
 
 @H_301_7@ReadAt方法的调用者可以对同一输入流执行并行的@H_301_7@WriteAt调用。（前提是写入范围不重叠） 
 
 
 typeByteReader 
 
type ByteReader interface { @H_301_7@ReadByte() (c byte,sans-serif;font-size:14px;background-color:#FFFFFF;"> @H_301_7@ByteReader是基本的@H_301_7@ReadByte方法的包装。 
 
 @H_301_7@ReadByte读取输入中的单个字节并返回。如果没有字节可读取，会返回错误。 
 
 
 typeByteScanner 
 
type ByteScanner interface { ByteReader @H_301_7@UnreadByte() error }
 
 @H_301_7@ByteScanner接口在基本的@H_301_7@ReadByte方法之外还添加了@H_301_7@UnreadByte方法。 
 
 @H_301_7@UnreadByte方法让下一次调用@H_301_7@ReadByte时返回之前调用@H_301_7@ReadByte时返回的同一个字节。连续调用两次@H_301_7@UnreadByte方法而中间没有调用@H_301_7@ReadByte时，可能会导致错误。 
 
 
 typeRuneReader 
 
type RuneReader interface { @H_301_7@ReadRune() (r @L_403_108@,size int,sans-serif;font-size:14px;background-color:#FFFFFF;"> @H_301_7@RuneReader是基本的@H_301_7@ReadRune方法的包装。 
 
 @H_301_7@ReadRune读取单个@H_301_7@utf-8编码的字符，返回该字符和它的字节长度。如果没有有效的字符，会返回错误。 
 
 
 typeRuneScanner 
 
type RuneScanner interface { RuneReader @H_301_7@UnreadRune() error }
 
 @H_301_7@RuneScanner接口在基本的@H_301_7@ReadRune方法之外还添加了@H_301_7@UnreadRune方法。 
 
 @H_301_7@UnreadRune方法让下一次调用@H_301_7@ReadRune时返回之前调用@H_301_7@ReadRune时返回的同一个@H_301_7@utf-8字符。连续调用两次@H_301_7@UnreadRune方法而中间没有调用@H_301_7@ReadRune时，可能会导致错误。 
 
 
 typeByteWriter 
 
type ByteWriter interface { @H_301_7@WriteByte(c byte) error }
 
 @H_301_7@ByteWriter是基本的@H_301_7@WriteByte方法的包装。 
 
 
 typeReaderFrom 
 
type ReaderFrom interface { @H_301_7@ReadFrom(r Reader) (n int64,sans-serif;font-size:14px;background-color:#FFFFFF;"> @H_301_7@ReaderFrom接口包装了基本的@H_301_7@ReadFrom方法。 
 
 @H_301_7@ReadFrom方法从@H_301_7@r读取数据直到@H_301_7@EOF或者遇到错误。返回值@H_301_7@n是读取的字节数，执行时遇到的错误（@H_301_7@EOF除外）也会被返回。 
 
 
 typeWriterTo 
 
type WriterTo interface { @H_301_7@WriteTo(w Writer) (n int64,sans-serif;font-size:14px;background-color:#FFFFFF;"> @H_301_7@WriterTo接口包装了基本的@H_301_7@WriteTo方法。 
 
 @H_301_7@WriteTo方法将数据写入@H_301_7@w直到没有数据可以写入或者遇到错误。返回值@H_301_7@n是写入的字节数，执行时遇到的任何错误也会被返回。 
 
 
 typeLimitedReader 
 
type LimitedReader struct { @H_301_7@R Reader // 底层Reader接口 @H_301_7@N int64 // 剩余可读取字节数 }
 
 @H_301_7@LimitedReader从@H_301_7@R中读取数据，但限制可以读取的数据的量为最多@H_301_7@N字节，每次调用@H_301_7@Read方法都会更新@H_301_7@N以标记剩余可以读取的字节数。 
 
 
 funcLimitReader 
 
func LimitReader(r Reader,n int64) Reader
 
 返回一个@H_301_7@Reader，它从@H_301_7@r中读取@H_301_7@n个字节后以@H_301_7@EOF停止。返回值接口的底层为@H_301_7@*LimitedReader类型。 
 
 
 func (*LimitedReader)Read 
 
func (l *LimitedReader) Read(p []byte) (n int,err error)
 
 
 typeSectionReader 
 
type SectionReader struct { // 内含隐藏或非导出字段 }
 
 @H_301_7@SectionReader实现了对底层满足@H_301_7@ReadAt接口的输入流某个片段的@H_301_7@Read、@H_301_7@ReadAt、@H_301_7@Seek方法。 
 
 
 funcNewSectionReader 
 
func NewSectionReader(r ReaderAt,off int64,n int64) *SectionReader
 
 返回一个从@H_301_7@r中的偏移量@H_301_7@off处为起始，读取@H_301_7@n个字节后以@H_301_7@EOF停止的@H_301_7@SectionReader。 
 
 
 func (*SectionReader)Size 
 
func (s *SectionReader) Size() int64
 
 Size返回该片段的字节数。 
 
 
 func (*SectionReader)Read 
 
func (s *SectionReader) Read(p []byte) (n int,err error)
 
 
 func (*SectionReader)ReadAt 
 
func (s *SectionReader) ReadAt(p []byte,err error)
 
 
 func (*SectionReader)Seek 
 
func (s *SectionReader) Seek(offset int64,error)
 
 
 typePipeReader 
 
type PipeReader struct { // 内含隐藏或非导出字段 }
 
 @H_301_7@PipeReader是一个@H_301_7@管道的读取端。 
 
 
 funcPipe 
 
func Pipe() (*PipeReader,*PipeWriter)
 
 Pipe创建一个同步的内存中的管道。它可以用于连接期望io.Reader的代码和期望io.Writer的代码。一端的读取对应另一端的写入，直接在两端拷贝数据，没有内部缓冲。可以安全的并行调用Read和Write或者Read/Write与Close方法。Close方法会在最后一次阻塞中的I/O操作结束后完成。并行调用Read或并行调用Write也是安全的：每一个独立的调用会依次进行。 
 
 
 func (*PipeReader)Read 
 
func (r *PipeReader) Read(data []byte) (n int,err error)
 
 @H_301_7@Read实现了标准@H_301_7@Reader接口：它从管道中读取数据，会阻塞直到写入端开始写入或写入端被关闭。 
 
 
 func (*PipeReader)Close 
 
func (r *PipeReader) Close() error
 
 @H_301_7@Close关闭读取器；关闭后如果对管道的写入端进行写入操作，就会返回@H_301_7@(0,ErrClosedPip)。 
 
 
 func (*PipeReader)CloseWithError 
 
func (r *PipeReader) CloseWithError(err error) error
 
 @H_301_7@CloseWithError类似@H_301_7@Close方法，但将调用@H_301_7@Write时返回的错误改为@H_301_7@err。 
 
 
 typePipeWriter 
 
type PipeWriter struct { // 内含隐藏或非导出字段 }
 
 @H_301_7@PipeWriter是一个@H_301_7@管道的写入端。 
 
 
 func (*PipeWriter)Write 
 
func (w *PipeWriter) Write(data []byte) (n int,sans-serif;font-size:14px;background-color:#FFFFFF;"> @H_301_7@Write实现了标准@H_301_7@Writer接口：它将数据写入到管道中，会阻塞直到读取器读完所有的数据或读取端被关闭。 
 
 
 func (*PipeWriter)Close 
 
func (w *PipeWriter) Close() error
 
 @H_301_7@Close关闭写入器；关闭后如果对管道的读取端进行读取操作，就会返回@H_301_7@(0,EOF)。 
 
 
 func (*PipeWriter)CloseWithError 
 
func (w *PipeWriter) CloseWithError(err error) error
 
 @H_301_7@CloseWithError类似@H_301_7@Close方法，但将调用@H_301_7@Read时返回的错误改为@H_301_7@err。 
 
 
 funcTeeReader 
 
func TeeReader(r Reader,w Writer) Reader
 
 @H_301_7@TeeReader返回一个将其从@H_301_7@r读取的数据写入@H_301_7@w的@H_301_7@Reader接口。所有通过该接口对@H_301_7@r的读取都会执行对应的对@H_301_7@w的写入。没有内部的缓冲：写入必须在读取完成前完成。写入时遇到的任何错误都会作为读取错误返回。 
 
 
 funcMultiReader 
 
func MultiReader(readers ...Reader) Reader
 
 @H_301_7@MultiReader返回一个将提供的@H_301_7@Reader在逻辑上串联起来的@H_301_7@Reader接口。他们依次被读取。当所有的输入流都读取完毕，@H_301_7@Read才会返回@H_301_7@EOF。如果@H_301_7@readers中任一个返回了非@H_301_7@nil非@H_301_7@EOF的错误，@H_301_7@Read方法会返回该错误。 
 
 
 funcMultiWriter 
 
func MultiWriter(writers ...Writer) Writer
 
 @H_301_7@MultiWriter创建一个@H_301_7@Writer接口，会将提供给其的数据写入所有创建时提供的@H_301_7@Writer接口。 
 
 
 funcCopy 
 
func Copy(dst Writer,src Reader) (written int64,sans-serif;font-size:14px;background-color:#FFFFFF;"> 将@H_301_7@src的数据拷贝到@H_301_7@dst，直到在@H_301_7@src上到达@H_301_7@EOF或发生错误。返回拷贝的字节数和遇到的第一个错误。 
 
 对成功的调用，返回值@H_301_7@err为@H_301_7@nil而非@H_301_7@EOF，因为@H_301_7@Copy定义为从@H_301_7@src读取直到@H_301_7@EOF，它不会将读取到@H_301_7@EOF视为应报告的错误。如果@H_301_7@src实现了@H_301_7@WriterTo接口，本函数会调用@H_301_7@src.WriteTo(dst)进行拷贝；否则如果@H_301_7@dst实现了@H_301_7@ReaderFrom接口，本函数会调用@H_301_7@dst.ReadFrom(src)进行拷贝。 
 
 
 funcCopyN 
 
func CopyN(dst Writer,src Reader,n int64) (written int64,sans-serif;font-size:14px;background-color:#FFFFFF;"> 从@H_301_7@src拷贝@H_301_7@n个字节数据到@H_301_7@dst，直到在@H_301_7@src上到达@H_301_7@EOF或发生错误。返回复制的字节数和遇到的第一个错误。 
 
 只有@H_301_7@err为@H_301_7@nil时，@H_301_7@written才会等于@H_301_7@n。如果@H_301_7@dst实现了@H_301_7@ReaderFrom接口，本函数很调用它实现拷贝。 
 
 
 funcReadAtLeast 
 
func ReadAtLeast(r Reader,buf []byte,min int) (n int,sans-serif;font-size:14px;background-color:#FFFFFF;"> @H_301_7@ReadAtLeast从@H_301_7@r至少读取@H_301_7@min字节数据填充进@H_301_7@buf。函数返回写入的字节数和错误（如果没有读取足够的字节）。只有没有读取到字节时才可能返回@H_301_7@EOF；如果读取了有但不够的字节时遇到了@H_301_7@EOF，函数会返回@H_301_7@ErrUnexpectedEOF。如果@H_301_7@min比@H_301_7@buf的长度还大，函数会返回@H_301_7@ErrShortBuffer。只有返回值@H_301_7@err为@H_301_7@nil时，返回值@H_301_7@n才会不小于@H_301_7@min。 
 
 
 funcReadFull 
 
func ReadFull(r Reader,buf []byte) (n int,sans-serif;font-size:14px;background-color:#FFFFFF;"> @H_301_7@ReadFull从@H_301_7@r精确地读取@H_301_7@len(buf)字节数据填充进@H_301_7@buf。函数返回写入的字节数和错误（如果没有读取足够的字节）。只有没有读取到字节时才可能返回@H_301_7@EOF；如果读取了有但不够的字节时遇到了@H_301_7@EOF，函数会返回@H_301_7@ErrUnexpectedEOF。只有返回值@H_301_7@err为@H_301_7@nil时，返回值@H_301_7@n才会等于@H_301_7@len(buf)。 
 
 
 funcWriteString 
 
func WriteString(w Writer,s string) (n int,sans-serif;font-size:14px;background-color:#FFFFFF;"> @H_301_7@WriteString函数将字符串@H_301_7@s的内容写入@H_301_7@w中。如果@H_301_7@w已经实现了@H_301_7@WriteString方法，函数会直接调用该方法。 
 原文链接：https://www.f2er.com/go/190807.html