Package io

Package io provides the basic interfaces to write Go programs.
It is the first package to consider when dealing with I/O.

Interfaces

Constants

Variables

Functions

Interface Reader

A Reader is an object that can be read from. Its zero value is an valid Reader that returns no data and no error.

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

The Read method reads up to len(p) bytes from the data source into the returned data.

Interface Writer

A Writer is an object that can be written to. Its zero value is an valid Writer that accepts no data and no error.

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

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

Interface Closer

A Closer is a destination that can be closed.

type Closer interface {
	Close() error
}

Interface ReadWriter

A ReadWriter is the combination of a Reader and a Writer.

type ReadWriter interface {
	Reader
	Writer
}

Interface Seeker

A Seeker implements the Seek method, which adjusts the offset of the next Read or Write to be on a byte boundary specified by offset, relative to how.

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

Seek whence is one of the following:

const (
	SeekStart   = 0 // relative to the start of the file
	SeekCurrent = 1 // relative to the current offset
	SeekEnd     = 2 // relative to the end of the file
)

Type SectionReader

A SectionReader implements the io.Reader, io.ReaderAt, io.WriterTo, io.Seeker, io.ByteScanner, and io.RuneScanner interfaces for a section of an underlying reader.

type SectionReader struct {
	// R is the underlying reader.
	R ReaderAt
	// Offset is the starting offset of the section in the underlying reader.
	Offset int64
	// Size is the size of the section.
	Size int64
	// contains filtered or unexported fields
}

NewSectionReader creates a new SectionReader that reads from R. The section is defined by the byte range [offset, offset+size).

func NewSectionReader(r ReaderAt, offset int64, size int64) *SectionReader

Type LimitedReader

A LimitedReader reads from R but stops after n bytes have been read. If the underlying R is ReadCloser, the Close method will also be wrapped.

type LimitedReader struct {
	R Reader // the underlying reader
	N int64  // the maximum number of bytes remaining to read
}

Read reads from the underlying R up to N bytes. It returns the number of bytes read and any error encountered.

func (l *LimitedReader) Read(p []byte) (n int, err error)

Type MultiReader

A MultiReader creates an Reader that is the logical OR of the more Readers. The zero value for MultiReader is not a valid Reader.

type MultiReader struct {
	// contains filtered or unexported fields
}

NewMultiReader creates a MultiReader that reads from the given readers in order.

func NewMultiReader(r ...Reader) Reader

Type MultiWriter

A MultiWriter creates an Writer that duplicates its writes to all the provided Writers, then returns the number of bytes written to each.

type MultiWriter struct {
	// contains filtered or unexported fields
}

NewMultiWriter creates a MultiWriter that writes to each of the given writers in order.

func NewMultiWriter(w ...Writer) Writer

Type TeeReader

A TeeReader reads from r but writes what it reads to the provided Writer w. TeeReader implements the same methods as Reader.

type TeeReader struct {
	// contains filtered or unexported fields
}

NewTeeReader creates a new TeeReader that reads from r and writes to w.

func NewTeeReader(r Reader, w Writer) Reader

Constant EOF

EOF is the sentinel error that corresponds to reading past the end of a file or stream.

const EOF = -1

Variable ErrUnexpectedEOF

ErrUnexpectedEOF is returned by some Readers when an unexpected end of input is encountered.

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

Variable ErrNoProgress

ErrNoProgress is returned by some implementations of Read when the operation cannot make any progress.

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

Function Copy

Copy copies from src to dst until either EOF is reached on src or an error occurs on either src or dst. It returns the number of bytes copied and any error encountered.

The error is any error that occurs halting Copy. If both src and dst return an error, the error from dst is returned.

func Copy(dst Writer, src Reader) (written int64, err error)

Example: Copying data


package main

import (
	"bytes"
	"io"
	"log"
)

func main() {
	src := bytes.NewBufferString("Hello, Go!")
	dst := new(bytes.Buffer)

	n, err := io.Copy(dst, src)
	if err != nil {
		log.Fatalf("Failed to copy: %v", err)
	}

	log.Printf("Copied %d bytes: %q\n", n, dst.String())
}

Function CopyN

CopyN copies exactly n bytes from src to dst and returns a non-nil error if either EOF is reached before n bytes are read or an error occurs on either Read or Write. It returns the number of bytes copied and the first error encountered.

func CopyN(dst Writer, src Reader, n int64) (written int64, err error)

Function ReadAll

ReadAll reads from r until an error or EOF and returns the data it read. A successful call returns err == nil, not err == EOF. Because ReadAll the data it reads, it can be inefficient. For a more efficient Reader, see the bufio.Reader.

func ReadAll(r Reader) ([]byte, error)

Function ReadAtLeast

ReadAtLeast reads from r into buf until either len(buf) bytes are in buf or an error is encountered. It returns the number of bytes read and the error. If the error is not io.EOF, it is the error that was encountered.

func ReadAtLeast(r Reader, buf []byte) (n int, err error)

Function WriteString

WriteString is equivalent to Write, but always writes the entire string.

func WriteString(w Writer, s string) (n int, err error)