Описание пакета io языка программирования Go

• 1: Описание функций пакета io
• 2: Описание типов пакета io языка программирования GO
• 3: Пакет для работы с файловой системой io/fs

const (
    SeekStart   = 0 // поиск относительно начала файла
    SeekCurrent = 1 // поиск относительно текущего смещения
    SeekEnd     = 2 // поиск относительно конца)

var EOF = errors.New(«EOF»)

var ErrClosedPipe = errors.New(«io: read/write on closed pipe»)

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

var ErrShortBuffer = errors.New(«короткий буфер»)

var ErrShortWrite = errors.New(«короткая запись»)

var ErrUnexpectedEOF = errors.New(«неожиданный EOF»)

1 - Описание функций пакета io

func Copy

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

Copy копирует данные из src в dst до тех пор, пока не будет достигнут EOF в src или не произойдет ошибка. Функция возвращает количество скопированных байтов и первую ошибку, возникшую при копировании, если таковая имеется.

Успешная функция Copy возвращает err == nil, а не err == EOF. Поскольку функция Copy определена для чтения из src до EOF, она не рассматривает EOF из Read как ошибку, о которой следует сообщать.

Если 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)
	}

}

Output:

some io.Reader stream to be read

func CopyBuffer

func CopyBuffer(dst Writer, src Reader, buf []byte) (written int64, err error)

CopyBuffer идентична Copy, за исключением того, что она проходит через предоставленный буфер (если он требуется), а не выделяет временный. Если buf равна nil, выделяется один; в противном случае, если она имеет нулевую длину, CopyBuffer вызывает панику.

Если src реализует WriterTo или dst реализует ReaderFrom, buf не будет использоваться для выполнения копирования.

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 is used here...
	if _, err := io.CopyBuffer(os.Stdout, r1, buf); err != nil {
		log.Fatal(err)
	}

	// ... reused here also. No need to allocate an extra buffer.
	if _, err := io.CopyBuffer(os.Stdout, r2, buf); err != nil {
		log.Fatal(err)
	}

}

Output:

first reader
second reader

func CopyN

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

CopyN копирует n байт (или до возникновения ошибки) из src в dst. Он возвращает количество скопированных байтов и самую раннюю ошибку, возникшую во время копирования. При возвращении 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, 4); err != nil {
		log.Fatal(err)
	}

}

Output:

some

func Pipe

func Pipe() (*PipeReader, *PipeWriter)

Pipe создает синхронный конвейер в памяти. Его можно использовать для соединения кода, ожидающего io.Reader, с кодом, ожидающим io.Writer.

Чтение и запись в канале сопоставляются один к одному, за исключением случаев, когда для потребления одной записи требуется несколько чтений. То есть каждая запись в PipeWriter блокируется до тех пор, пока не будет удовлетворено одно или несколько чтений из PipeReader, которые полностью потребляют записанные данные. Данные копируются непосредственно из записи в соответствующее чтение (или чтения); внутренней буферизации нет.

Безопасно вызывать Read и Write параллельно друг с другом или с Close. Параллельные вызовы Read и параллельные вызовы Write также безопасны: отдельные вызовы будут последовательно блокироваться.

package main

import (
	"fmt"
	"io"
	"log"
	"os"
)

func main() {
	r, w := io.Pipe()

	go func() {
		fmt.Fprint(w, "some io.Reader stream to be read\n")
		w.Close()
	}()

	if _, err := io.Copy(os.Stdout, r); err != nil {
		log.Fatal(err)
	}

}

Output:

some io.Reader stream to be read

func ReadAll

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

ReadAll читает из r до ошибки или EOF и возвращает прочитанные данные. Успешный вызов возвращает err == nil, а не err == EOF. Поскольку ReadAll определено для чтения из src до EOF, оно не рассматривает EOF из Read как ошибку, о которой следует сообщать.

package main

import (
	"fmt"
	"io"
	"log"
	"strings"
)

func main() {
	r := strings.NewReader("Go is a general-purpose language designed with systems programming in mind.")

	b, err := io.ReadAll(r)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("%s", b)

}

Output:

Go is a general-purpose language designed with systems programming in mind.

func ReadAtLeast

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

ReadAtLeast читает из r в buf, пока не прочитает как минимум min байт. Он возвращает количество скопированных байтов и ошибку, если было прочитано меньше байтов. Ошибка EOF возникает только в том случае, если не было прочитано ни одного байта. Если EOF возникает после чтения менее min байтов, ReadAtLeast возвращает ErrUnexpectedEOF. Если min больше длины buf, ReadAtLeast возвращает ErrShortBuffer. При возвращении n >= min, если и только если err == nil. Если r возвращает ошибку, прочитав не менее min байтов, ошибка игнорируется.

package main

import (
	"fmt"
	"io"
	"log"
	"strings"
)

func main() {
	r := strings.NewReader("some io.Reader stream to be read\n")

	buf := make([]byte, 14)
	if _, err := io.ReadAtLeast(r, buf, 4); err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%s\n", buf)

	// buffer smaller than minimal read size.
	shortBuf := make([]byte, 3)
	if _, err := io.ReadAtLeast(r, shortBuf, 4); err != nil {
		fmt.Println("error:", err)
	}

	// minimal read size bigger than io.Reader stream
	longBuf := make([]byte, 64)
	if _, err := io.ReadAtLeast(r, longBuf, 64); err != nil {
		fmt.Println("error:", err)
	}

}

Output:

some io.Reader
error: short buffer
error: unexpected EOF

func ReadFull

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

ReadFull читает ровно len(buf) байтов из r в buf. Он возвращает количество скопированных байтов и ошибку, если было прочитано меньше байтов. Ошибка EOF возникает только в том случае, если не было прочитано ни одного байта. Если EOF возникает после чтения некоторых, но не всех байтов, ReadFull возвращает ErrUnexpectedEOF. При возвращении n == len(buf) тогда и только тогда, когда err == nil. Если r возвращает ошибку после чтения по крайней мере len(buf) байтов, ошибка игнорируется.

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)

	// minimal read size bigger than io.Reader stream
	longBuf := make([]byte, 64)
	if _, err := io.ReadFull(r, longBuf); err != nil {
		fmt.Println("error:", err)
	}

}

Output:

some
error: unexpected EOF

func WriteString

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

WriteString записывает содержимое строки s в w, который принимает набор байтов. Если w реализует StringWriter, [StringWriter.WriteString] вызывается напрямую. В противном случае [Writer.Write] вызывается ровно один раз.

package main

import (
	"io"
	"log"
	"os"
)

func main() {
	if _, err := io.WriteString(os.Stdout, "Hello World"); err != nil {
		log.Fatal(err)
	}

}

Output:

Hello World

2 - Описание типов пакета io языка программирования GO

type ByteReader

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

ByteReader — это интерфейс, который оборачивает метод ReadByte.

ReadByte считывает и возвращает следующий байт из ввода или любую возникшую ошибку. Если ReadByte возвращает ошибку, входной байт не был обработан, и возвращаемое значение байта не определено.

ReadByte предоставляет эффективный интерфейс для обработки по одному байту за раз. Reader, который не реализует ByteReader, можно обернуть с помощью bufio.NewReader, чтобы добавить этот метод.

type ByteScanner

type ByteScanner interface {
    ByteReader
    UnreadByte() error
}

ByteScanner — это интерфейс, который добавляет метод UnreadByte к базовому методу ReadByte.

UnreadByte заставляет следующий вызов ReadByte возвращать последний прочитанный байт. Если последняя операция не была успешным вызовом ReadByte, UnreadByte может вернуть ошибку, не прочитать последний прочитанный байт (или байт, предшествующий последнему непрочитанному байту), или (в реализациях, поддерживающих интерфейс Seeker) перейти на один байт перед текущим смещением.

type ByteWriter

type ByteWriter interface {
    WriteByte(c byte) error
}

ByteWriter — это интерфейс, который оборачивает метод WriteByte.

type Closer

type Closer interface {
    Close() error
}

Closer — это интерфейс, который оборачивает базовый метод Close.

Поведение Close после первого вызова не определено. Конкретные реализации могут документировать свое собственное поведение.

type LimitedReader

type LimitedReader struct {
    R Reader // базовый читатель
    N int64  // максимальное количество оставшихся байтов
}

LimitedReader читает из R, но ограничивает количество возвращаемых данных до N байтов. Каждый вызов Read обновляет N, чтобы отразить новое количество оставшихся данных. Read возвращает EOF, когда N <= 0 или когда базовый R возвращает EOF.

func (*LimitedReader) Read

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

package main

import (
	"fmt"
	"io"
	"strings"
)

func main() {
	// Создаем источник данных - строка длиной 100 символов
	data := strings.Repeat("abcdefghij", 10) // 100 байт
	reader := strings.NewReader(data)

	// Создаем LimitedReader, который прочитает только первые 35 байт
	limitedReader := &io.LimitedReader{
		R: reader, // базовый reader
		N: 35,     // лимит в 35 байт
	}

	// Буфер для чтения
	buf := make([]byte, 10) // читаем по 10 байт за раз

	var totalRead int
	for {
		// Читаем данные
		n, err := limitedReader.Read(buf)
		if err != nil {
			if err == io.EOF {
				fmt.Println("\nДостигнут лимит или конец данных")
			} else {
				fmt.Println("\nОшибка чтения:", err)
			}
			break
		}

		totalRead += n
		fmt.Printf("Прочитано %d байт: %q\n", n, buf[:n])
		fmt.Printf("Осталось прочитать: %d байт\n", limitedReader.N)
	}

	fmt.Println("Всего прочитано:", totalRead, "байт")
	fmt.Println("Осталось данных в основном reader:", reader.Len(), "байт")
}

Прочитано 10 байт: "abcdefghij"
Осталось прочитать: 25 байт
Прочитано 10 байт: "abcdefghij"
Осталось прочитать: 15 байт
Прочитано 10 байт: "abcdefghij"
Осталось прочитать: 5 байт
Прочитано 5 байт: "abcde"
Осталось прочитать: 0 байт

Достигнут лимит или конец данных
Всего прочитано: 35 байт
Осталось данных в основном reader: 65 байт

type OffsetWriter

type OffsetWriter struct {
    // содержит отфильтрованные или неэкспортируемые поля
}

package main

import (
	"fmt"
	"io"
	"os"
)

func main() {
	// Создаем временный файл
	tmpFile, err := os.CreateTemp("", "offset-writer-demo")
	if err != nil {
		panic(err)
	}
	defer os.Remove(tmpFile.Name())
	defer tmpFile.Close()

	// Заполняем файл пробельными символами для наглядности
	_, err = tmpFile.WriteString("=== Начало файла ===\n" + 
		strings.Repeat(".", 100) + "\n=== Конец файла ===")
	if err != nil {
		panic(err)
	}

	// Создаем OffsetWriter с начальным смещением 20 байт
	ow := io.NewOffsetWriter(tmpFile, 20)

	// 1. Используем Write - пишет с текущего смещения
	fmt.Println("\n1. Запись через Write()")
	_, err = ow.Write([]byte("ПЕРВАЯ ЗАПИСЬ"))
	if err != nil {
		panic(err)
	}
	printFileContent(tmpFile.Name())

	// 2. Используем Seek для изменения позиции
	fmt.Println("\n2. Seek(10, io.SeekCurrent)")
	newPos, err := ow.Seek(10, io.SeekCurrent) // Перемещаемся на +10 байт от текущей позиции
	if err != nil {
		panic(err)
	}
	fmt.Printf("Новая позиция: %d\n", newPos)

	// 3. Еще одна запись через Write
	_, err = ow.Write([]byte("ВТОРАЯ ЗАПИСЬ"))
	if err != nil {
		panic(err)
	}
	printFileContent(tmpFile.Name())

	// 4. Используем WriteAt - пишет по абсолютному смещению (не меняет текущую позицию)
	fmt.Println("\n4. WriteAt() по смещению 5")
	_, err = ow.WriteAt([]byte("ТРЕТЬЯ"), 5)
	if err != nil {
		panic(err)
	}
	printFileContent(tmpFile.Name())

	// 5. Проверяем текущую позицию после WriteAt
	pos, _ := ow.Seek(0, io.SeekCurrent)
	fmt.Printf("\n5. Текущая позиция после WriteAt: %d\n", pos)

	// 6. Возвращаемся в начало и пишем еще
	fmt.Println("\n6. Seek(0, io.SeekStart) + Write()")
	ow.Seek(0, io.SeekStart)
	ow.Write([]byte("НАЧАЛО"))
	printFileContent(tmpFile.Name())
}

func printFileContent(filename string) {
	data, _ := os.ReadFile(filename)
	fmt.Println("Содержимое файла:")
	fmt.Println(string(data))
	fmt.Println("Длина:", len(data), "байт")
	fmt.Println(strings.Repeat("-", 50))
}

1. Запись через Write()
Содержимое файла:
=== Начало файла ===
ПЕРВАЯ ЗАПИСЬ....................
=== Конец файла ===
Длина: 132 байт
--------------------------------------------------

2. Seek(10, io.SeekCurrent)
Новая позиция: 42

3. Запись через Write()
Содержимое файла:
=== Начало файла ===
ПЕРВАЯ ЗАПИСЬ..........ВТОРАЯ ЗАПИСЬ.....
=== Конец файла ===
Длина: 154 байт
--------------------------------------------------

4. WriteAt() по смещению 5
Содержимое файла:
=== Начало файла ===
ПЕРТЬЯ ЗАПИСЬ..........ВТОРАЯ ЗАПИСЬ.....
=== Конец файла ===
Длина: 154 байт
--------------------------------------------------

5. Текущая позиция после WriteAt: 42

6. Seek(0, io.SeekStart) + Write()
Содержимое файла:
=== Начало файла ===
НАЧАЛО ЗАПИСЬ..........ВТОРАЯ ЗАПИСЬ.....
=== Конец файла ===
Длина: 154 байт
--------------------------------------------------

func NewOffsetWriter

func NewOffsetWriter(w WriterAt, off int64) *OffsetWriter

NewOffsetWriter возвращает OffsetWriter, который записывает в w, начиная с смещения off.

func (*OffsetWriter) Seek

func (o *OffsetWriter) Seek(offset int64, whence int) (int64, error)

func (*OffsetWriter) Write

func (o *OffsetWriter) Write(p []byte) (n int, err error)

func (*OffsetWriter) WriteAt

func (o *OffsetWriter) WriteAt(p []byte, off int64) (n int, err error)

type PipeReader

type PipeReader struct {
    // содержит отфильтрованные или неэкспортируемые поля
}

PipeReader — это читающая часть канала (pipe).

package main

import (
	"fmt"
	"io"
	"time"
)

func main() {
	// Создаем pipe
	pipeReader, pipeWriter := io.Pipe()

	// Горутина для чтения из канала
	go func() {
		buf := make([]byte, 256)

		// 1. Обычное чтение
		n, err := pipeReader.Read(buf)
		if err != nil {
			fmt.Printf("Ошибка чтения: %v\n", err)
			return
		}
		fmt.Printf("Прочитано %d байт: %s\n", n, buf[:n])

		// 2. Попытка чтения после закрытия записи
		n, err = pipeReader.Read(buf)
		if err == io.EOF {
			fmt.Println("Канал закрыт (EOF)")
		} else if err != nil {
			fmt.Printf("Ошибка чтения: %v\n", err)
		}

		// 3. Чтение после CloseWithError
		_, err = pipeReader.Read(buf)
		if err != nil {
			fmt.Printf("Ошибка после CloseWithError: %v\n", err)
		}
	}()

	// Горутина для записи в канал
	go func() {
		// Записываем данные
		_, err := pipeWriter.Write([]byte("Тестовые данные"))
		if err != nil {
			fmt.Printf("Ошибка записи: %v\n", err)
		}

		// Закрываем запись (обычное закрытие)
		pipeWriter.Close()

		// Даем время на обработку
		time.Sleep(100 * time.Millisecond)

		// Пытаемся записать после закрытия чтения
		_, err = pipeWriter.Write([]byte("Новые данные"))
		if err == io.ErrClosedPipe {
			fmt.Println("Попытка записи в закрытый канал (ErrClosedPipe)")
		}
	}()

	// Даем время на выполнение
	time.Sleep(200 * time.Millisecond)

	// Закрываем читатель с ошибкой
	err := pipeReader.CloseWithError(fmt.Errorf("кастомная ошибка"))
	if err != nil {
		fmt.Printf("Ошибка при CloseWithError: %v\n", err)
	}

	// Пытаемся записать после CloseWithError
	_, err = pipeWriter.Write([]byte("Последние данные"))
	if err != nil {
		fmt.Printf("Ошибка записи после CloseWithError: %v\n", err)
	}

	time.Sleep(100 * time.Millisecond)
}

Прочитано 28 байт: Тестовые данные
Канал закрыт (EOF)
Попытка записи в закрытый канал (ErrClosedPipe)
Ошибка после CloseWithError: кастомная ошибка
Ошибка записи после CloseWithError: io: read/write on closed pipe

func (*PipeReader) Close

func (r *PipeReader) Close() error

Close закрывает читатель; последующие записи в записывающую половину канала будут возвращать ошибку ErrClosedPipe.

func (*PipeReader) CloseWithError

func (r *PipeReader) CloseWithError(err error) error

CloseWithError закрывает читатель; последующие записи в записывающую половину канала будут возвращать ошибку err.

CloseWithError никогда не перезаписывает предыдущую ошибку, если она существует, и всегда возвращает nil.

func (*PipeReader) Read

func (r *PipeReader) Read(data []byte) (n int, err error)

Read реализует стандартный интерфейс Read: он считывает данные из канала, блокируя до тех пор, пока не появится записывающее устройство или не будет закрыта записывающая часть. Если записывающая часть закрыта с ошибкой, эта ошибка возвращается как err; в противном случае err равен EOF.

type PipeWriter

type PipeWriter struct {
    // содержит отфильтрованные или неэкспортируемые поля
}

PipeWriter — это записывающая часть канала (pipe).

func (*PipeWriter) Close

func (w *PipeWriter) Close() error

Close закрывает записывающее устройство; последующие чтения из читающей половины канала не будут возвращать байты и EOF.

func (*PipeWriter) CloseWithError

func (w *PipeWriter) CloseWithError(err error) error

CloseWithError закрывает запись; последующие чтения из части трубы, отвечающей за чтение, не будут возвращать байты и будут возвращать ошибку err или EOF, если err равна nil.

CloseWithError никогда не перезаписывает предыдущую ошибку, если она существует, и всегда возвращает nil.

func (*PipeWriter) Write

func (w *PipeWriter) Write(data []byte) (n int, err error)

Write реализует стандартный интерфейс Write: он записывает данные в канал, блокируя его до тех пор, пока один или несколько читателей не потребят все данные или читающая сторона не будет закрыта. Если читающая сторона закрыта с ошибкой, эта ошибка возвращается как err; в противном случае err равна ErrClosedPipe.

type ReadCloser

type ReadCloser интерфейс {
    Reader
    Closer
}

ReadCloser — это интерфейс, который группирует основные методы Read и Close.

// Есть строка (она реализует Reader)
data := strings.NewReader("Привет, мир!")

// Но нам нужно передать ReadCloser
rc := io.NopCloser(data)

// Теперь можно использовать везде, где требуется ReadCloser
// При вызове rc.Close() ничего не произойдет

func NopCloser

func NopCloser(r Reader) ReadCloser

NopCloser возвращает ReadCloser с методом Close, не выполняющим никаких действий, который оборачивает предоставленный Reader r. Если r реализует WriterTo, возвращаемый ReadCloser будет реализовывать WriterTo, перенаправляя вызовы r.

type ReadSeekCloser

type ReadSeekCloser интерфейс {
    Reader
    Seeker
    Closer
}

ReadSeekCloser — интерфейс, который группирует основные методы Read, Seek и Close.

func processFile(rsc io.ReadSeekCloser) error {
    data := make([]byte, 100)
    
    // Чтение
    if _, err := rsc.Read(data); err != nil {
        return err
    }
    
    // Перемещение в начало
    if _, err := rsc.Seek(0, io.SeekStart); err != nil {
        return err
    }
    
    // Закрытие
    defer rsc.Close()
    return nil
}

// Использование
file, _ := os.Open("data.txt")
processFile(file)  // *os.File реализует ReadSeekCloser

func analyze(data io.ReadSeeker) {
    // Первое чтение
    buf := make([]byte, 10)
    data.Read(buf)
    
    // Возврат в начало
    data.Seek(0, io.SeekStart)
}

// Использование
buffer := strings.NewReader("abcdefghij")
analyze(buffer)  // strings.Reader реализует ReadSeeker

func handleConnection(conn io.ReadWriteCloser) {
    defer conn.Close()
    
    // Чтение
    buf := make([]byte, 1024)
    conn.Read(buf)
    
    // Ответ
    conn.Write([]byte("OK"))
}

// Использование (псевдокод)
// conn, _ := net.Dial("tcp", "example.com:80")
// handleConnection(conn)  // net.Conn реализует ReadWriteCloser

func updateLog(rws io.ReadWriteSeeker, msg string) {
    // Перемещение в конец
    rws.Seek(0, io.SeekEnd)
    
    // Запись
    rws.Write([]byte(msg))
}

// Использование
file, _ := os.OpenFile("log.txt", os.O_RDWR, 0644)
updateLog(file, "New entry\n")

func process(rw io.ReadWriter) {
    rw.Write([]byte("ping"))
    response, _ := io.ReadAll(rw)
    fmt.Println(string(response))
}

// Использование
var buf bytes.Buffer
buf.WriteString("pong")
process(&buf)  // bytes.Buffer реализует ReadWriter

type ReadSeeker

type ReadSeeker интерфейс {
    Reader
    Seeker
}

ReadSeeker — интерфейс, который группирует основные методы Read и Seek.

type ReadWriteCloser

type ReadWriteCloser интерфейс {
    Reader
    Writer
    Closer
}

ReadWriteCloser — это интерфейс, который группирует основные методы Read, Write и Close.

type ReadWriteSeeker

type ReadWriteSeeker интерфейс {
	Reader
    Writer
    Seeker
}

ReadWriteSeeker — интерфейс, который группирует основные методы Read, Write и Seek.

type ReadWriter

type ReadWriter интерфейс {
    Reader
    Writer
}

ReadWriter — интерфейс, который группирует основные методы Read и Write.

type Reader

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

Reader — это интерфейс, который оборачивает базовый метод Read.

Read считывает до len(p) байт в p. Он возвращает количество прочитанных байтов (0 <= n <= len(p)) и любую возникшую ошибку. Даже если Read возвращает n < len(p), он может использовать все p в качестве временного пространства во время вызова. Если некоторые данные доступны, но не len(p) байтов, Read по умолчанию возвращает то, что доступно, вместо того, чтобы ждать больше.

Когда Read встречает ошибку или условие конца файла после успешного чтения n > 0 байтов, он возвращает количество прочитанных байтов. Он может вернуть ошибку (не nil) из того же вызова или вернуть ошибку (и n == 0) из последующего вызова. Примером этого общего случая является то, что Reader, возвращающий ненулевое количество байтов в конце входного потока, может возвращать либо err == EOF, либо err == nil. Следующий Read должен возвращать 0, EOF.

Вызывающие функции должны всегда обрабатывать возвращенные n > 0 байтов, прежде чем рассматривать ошибку err. Это позволяет правильно обрабатывать ошибки ввода-вывода, возникающие после чтения некоторых байтов, а также оба допустимых поведения EOF.

Если len(p) == 0, Read всегда должен возвращать n == 0. Он может возвращать ошибку, отличную от nil, если известно о каком-либо условии ошибки, таком как EOF.

Реализации Read не рекомендуется возвращать нулевое количество байтов с ошибкой nil, за исключением случаев, когда len(p) == 0. Вызывающие должны рассматривать возвращение 0 и nil как указание на то, что ничего не произошло; в частности, это не указывает на EOF.

Реализации не должны сохранять p.

func LimitReader

func LimitReader(r Reader, n int64) Reader

LimitReader возвращает Reader, который читает из r, но останавливается с EOF после n байтов. Базовой реализацией является *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)
	}

}

Output:

some

func MultiReader

func MultiReader(readers ...Reader) Reader

MultiReader возвращает Reader, который является логическим соединением предоставленных входных считывателей. Они считываются последовательно. Как только все входы вернут EOF, Read вернет EOF. Если какой-либо из считывателей вернет ошибку, отличную от nil и 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)
	}

}

Output:

first reader second reader third reader

func TeeReader

func TeeReader(r Reader, w Writer) Reader

TeeReader возвращает Reader, который записывает в w то, что он читает из r. Все чтения из r, выполняемые через него, сопоставляются с соответствующими записями в w. Внутренней буферизации нет — запись должна быть завершена до завершения чтения. Любая ошибка, возникшая во время записи, сообщается как ошибка чтения.

package main

import (
	"io"
	"log"
	"os"
	"strings"
)

func main() {
	var r io.Reader = strings.NewReader("some io.Reader stream to be read\n")

	r = io.TeeReader(r, os.Stdout)

	// Everything read from r will be copied to stdout.
	if _, err := io.ReadAll(r); err != nil {
		log.Fatal(err)
	}

}

Output:

some io.Reader stream to be read

type ReaderAt

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

ReaderAt — это интерфейс, который оборачивает базовый метод ReadAt.

ReadAt считывает len(p) байт в p, начиная с смещения off в базовом источнике ввода. Он возвращает количество прочитанных байтов (0 <= n <= len(p)) и любую возникшую ошибку.

Когда ReadAt возвращает n < len(p), он возвращает не нулевую ошибку, объясняющую, почему не было возвращено больше байтов. В этом отношении ReadAt более строг, чем Read.

Даже если ReadAt возвращает n < len(p), он может использовать все p в качестве временного пространства во время вызова. Если некоторые данные доступны, но не len(p) байтов, ReadAt блокируется до тех пор, пока не будут доступны все данные или не произойдет ошибка. В этом отношении ReadAt отличается от Read.

Если n = len(p) байтов, возвращаемых ReadAt, находятся в конце источника ввода, ReadAt может вернуть либо err == EOF, либо err == nil.

Если ReadAt читает из источника ввода с смещением поиска, ReadAt не должен влиять на базовое смещение поиска и не должен подвергаться его влиянию.

Клиенты ReadAt могут выполнять параллельные вызовы ReadAt на одном и том же источнике ввода.

Реализации не должны сохранять p.

ReadAt(p []byte, off int64) (n int, err error)

package main

import (
	"fmt"
	"io"
	"os"
)

func main() {
	file, err := os.Open("example.txt")
	if err != nil {
		panic(err)
	}
	defer file.Close()

	// Читаем 10 байт, начиная с 5-го байта
	buf := make([]byte, 10)
	n, err := file.ReadAt(buf, 5)
	if err != nil && err != io.EOF {
		panic(err)
	}

	fmt.Printf("Прочитано %d байт: %q\n", n, buf[:n])
}

Прочитано 10 байт: ", world!"

type MemoryReader struct {
	data []byte
}

func (r *MemoryReader) ReadAt(p []byte, off int64) (n int, err error) {
	if off >= int64(len(r.data)) {
		return 0, io.EOF
	}
	n = copy(p, r.data[off:])
	if n < len(p) {
		err = io.EOF
	}
	return
}

func main() {
	reader := &MemoryReader{data: []byte("RandomAccessData")}
	buf := make([]byte, 5)
	
	// Читаем 5 байт с 7-й позиции
	n, err := reader.ReadAt(buf, 7)
	if err != nil && err != io.EOF {
		panic(err)
	}
	fmt.Printf("Прочитано: %q\n", buf[:n]) // "Access"
}

type ReaderFrom

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

ReaderFrom — это интерфейс, который оборачивает метод ReadFrom.

ReadFrom читает данные из r до EOF или ошибки. Возвращаемое значение n — это количество прочитанных байтов. Любая ошибка, кроме EOF, возникшая во время чтения, также возвращается.

Функция Copy использует ReaderFrom, если он доступен.

type RuneReader

type RuneReader interface {
    ReadRune() (r rune, size int, err error)
}

RuneReader — это интерфейс, который оборачивает метод ReadRune.

ReadRune считывает один закодированный символ Unicode и возвращает руну и ее размер в байтах. Если символ недоступен, будет установлено err.

type RuneScanner

type RuneScanner interface {
    RuneReader
    UnreadRune() error
}

RuneScanner — это интерфейс, который добавляет метод UnreadRune к базовому методу ReadRune.

UnreadRune заставляет следующий вызов ReadRune возвращать последнюю прочитанную руну. Если последняя операция не была успешным вызовом ReadRune, UnreadRune может вернуть ошибку, не прочитать последнюю прочитанную руну (или руну, предшествующую последней непрочитанной руне), или (в реализациях, поддерживающих интерфейс Seeker) перейти к началу руны перед текущим смещением.

type SectionReader

type SectionReader struct {
    // содержит отфильтрованные или неэкспортированные поля
}

SectionReader реализует Read, Seek и ReadAt на секции базового ReaderAt.

package main

import (
	"fmt"
	"io"
	"strings"
)

func main() {
	// Исходные данные
	data := "Hello, World! This is a SectionReader example."
	baseReader := strings.NewReader(data)

	// Создаём SectionReader (база: data, смещение: 7, длина: 12 байтов)
	section := io.NewSectionReader(baseReader, 7, 12)
	
	// 1. Чтение всего раздела (Read)
	buf := make([]byte, 12)
	n, _ := section.Read(buf)
	fmt.Printf("Read: %q (%d bytes)\n", buf[:n], n) // "World! This"

	// 2. Чтение с позиции (ReadAt)
	n, _ = section.ReadAt(buf, 2)
	fmt.Printf("ReadAt(2): %q\n", buf[:n]) // "rld! This "

	// 3. Перемещение (Seek)
	section.Seek(5, io.SeekStart) // Перемещаемся на 5 байт от начала
	n, _ = section.Read(buf)
	fmt.Printf("After Seek(5): %q\n", buf[:n]) // "! This"

	// 4. Получение параметров секции (Outer)
	r, off, n := section.Outer()
	fmt.Printf("Base: %T, Offset: %d, Size: %d\n", r, off, n)

	// 5. Размер секции (Size)
	fmt.Println("Section size:", section.Size()) // 12
}

Read: "World! This" (12 bytes)
ReadAt(2): "rld! This "
After Seek(5): "! This"
Base: *strings.Reader, Offset: 7, Size: 12
Section size: 12

func NewSectionReader

func NewSectionReader(r ReaderAt, off int64, n int64) *SectionReader

NewSectionReader возвращает SectionReader, который читает из r, начиная с смещения off, и останавливается с EOF после n байтов.

func (*SectionReader) Outer

func (s *SectionReader) Outer() (r ReaderAt, off int64, n int64)

Outer возвращает базовый ReaderAt и смещения для секции.

Возвращаемые значения совпадают с теми, которые были переданы в NewSectionReader при создании SectionReader.

func (*SectionReader) Read

func (s *SectionReader) Read(p []byte) (n int, err error)

import (
	"fmt"
	"io"
	"log"
	"strings"
)

func main() {
	r := strings.NewReader("some io.Reader stream to be read\n")
	s := io.NewSectionReader(r, 5, 17)

	buf := make([]byte, 9)
	if _, err := s.Read(buf); err != nil {
		log.Fatal(err)
	}

	fmt.Printf("%s\n", buf)

}

Output:

io.Reader

func (*SectionReader) ReadAt

func (s *SectionReader) ReadAt(p []byte, off int64) (n int, err error)

import (
	"fmt"
	"io"
	"log"
	"strings"
)

func main() {
	r := strings.NewReader("some io.Reader stream to be read\n")
	s := io.NewSectionReader(r, 5, 17)

	buf := make([]byte, 6)
	if _, err := s.ReadAt(buf, 10); err != nil {
		log.Fatal(err)
	}

	fmt.Printf("%s\n", buf)

}

Output:

stream

func (*SectionReader) Seek

func (s *SectionReader) Seek(offset int64, whence int) (int64, error)

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 := s.Seek(10, io.SeekStart); err != nil {
		log.Fatal(err)
	}

	if _, err := io.Copy(os.Stdout, s); err != nil {
		log.Fatal(err)
	}

}

Output:

stream

func (*SectionReader) Size

func (s *SectionReader) Size() int64

Size возвращает размер секции в байтах.

package main

import (
	"fmt"
	"io"
	"strings"
)

func main() {
	r := strings.NewReader("some io.Reader stream to be read\n")
	s := io.NewSectionReader(r, 5, 17)

	fmt.Println(s.Size())

}

Output:

17

type Seeker

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

Seeker — это интерфейс, который оборачивает базовый метод Seek.

Seek устанавливает смещение для следующего Read или Write в offset, интерпретируемое в соответствии с whence: SeekStart означает относительно начала файла, SeekCurrent означает относительно текущего смещения, а SeekEnd означает относительно конца (например, offset = -2 указывает предпоследний байт файла). Seek возвращает новое смещение относительно начала файла или ошибку, если таковая имеется.

Переход к смещению перед началом файла является ошибкой. Переход к любому положительному смещению может быть разрешен, но если новое смещение превышает размер базового объекта, поведение последующих операций ввода-вывода зависит от реализации.

Seek(offset int64, whence int) (int64, error)

file, _ := os.Open("data.txt")
defer file.Close()

// Перемещаемся на 100-й байт от начала
pos, _ := file.Seek(100, io.SeekStart)

// Читаем 50 байт с этой позиции
buf := make([]byte, 50)
file.Read(buf)

// Перемещаемся на 10 байт назад от конца
pos, _ := file.Seek(-10, io.SeekEnd)

// Текущая позиция: 200
// Перемещаемся на +50 байт вперёд
pos, _ := file.Seek(50, io.SeekCurrent) // Новый pos = 250

type ReadSeeker interface {
    Reader
    Seeker
}

type StringWriter

type StringWriter interface {
    WriteString(s string) (n int, err error)
}

StringWriter — это интерфейс, который оборачивает метод WriteString.

type WriteCloser

type WriteCloser interface {
    Writer
    Closer
}

WriteCloser — это интерфейс, который группирует базовые методы Write и Close.

type WriteSeeker

type WriteSeeker interface {
    Writer
    Seeker
}

WriteSeeker — это интерфейс, который группирует базовые методы Write и Seek.

type Writer

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

Writer — это интерфейс, который оборачивает базовый метод Write.

Write записывает len(p) байт из p в базовый поток данных. Он возвращает количество байт, записанных из p (0 <= n <= len(p)), и любую ошибку, которая привела к преждевременному прекращению записи. Write должен возвращать ошибку, отличную от nil, если он возвращает n < len(p). Write не должен изменять данные слайса, даже временно.

Реализации не должны сохранять p.

var Discard Writer = discard{}

Discard — это Writer, на котором все вызовы Write выполняются успешно, не выполняя никаких действий.

io.Discard.Write([]byte("Это исчезнет")) // Никуда не запишется

type ConsoleWriter struct{}

func (cw ConsoleWriter) Write(p []byte) (int, error) {
    n, err := fmt.Print(string(p))
    return n, err
}

func main() {
    var writer Writer = ConsoleWriter{}
    writer.Write([]byte("Привет, Writer!"))
}

Привет, Writer!

func MultiWriter

func MultiWriter(writers ...Writer) Writer

MultiWriter создает писатель, который дублирует свои записи во всех предоставленных писателях, аналогично команде Unix tee(1).

Каждая запись записывается в каждый из перечисленных writer, по одному за раз. Если перечисленный writer возвращает ошибку, вся операция записи останавливается и возвращает ошибку; она не продолжается по списку.

package main

import (
	"fmt"
	"io"
	"log"
	"strings"
)

func main() {
	r := strings.NewReader("some io.Reader stream to be read\n")

	var buf1, buf2 strings.Builder
	w := io.MultiWriter(&buf1, &buf2)

	if _, err := io.Copy(w, r); err != nil {
		log.Fatal(err)
	}

	fmt.Print(buf1.String())
	fmt.Print(buf2.String())

}

Output:

some io.Reader stream to be read
some io.Reader stream to be read

type WriterAt

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

WriterAt — это интерфейс, который оборачивает базовый метод WriteAt.

WriteAt записывает len(p) байт из p в базовый поток данных со смещением off. Он возвращает количество байт, записанных из p (0 <= n <= len(p)), и любую ошибку, которая привела к преждевременному прекращению записи. WriteAt должен возвращать ошибку, отличную от nil, если он возвращает n < len(p).

Если WriteAt записывает в место назначения со смещением поиска, WriteAt не должен влиять на базовое смещение поиска и не должен подвергаться его влиянию.

Клиенты WriteAt могут выполнять параллельные вызовы WriteAt на одном и том же месте назначения, если диапазоны не пересекаются.

Реализации не должны сохранять p.

type WriterTo

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

WriterTo — это интерфейс, который оборачивает метод WriteTo.

WriteTo записывает данные в w до тех пор, пока не закончатся данные для записи или не произойдет ошибка. Возвращаемое значение n — это количество записанных байтов. Любая ошибка, возникшая во время записи, также возвращается.

Функция Copy использует WriterTo, если он доступен.

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

// bytes.Buffer реализует WriterTo
buf := bytes.NewBufferString("Hello!")
buf.WriteTo(os.Stdout) // Выведет "Hello!" в консоль

// strings.Reader тоже реализует WriterTo
reader := strings.NewReader("Text")
reader.WriteTo(file) // Запишет "Text" в файл

type CustomData struct {
    chunks [][]byte
}

func (d *CustomData) WriteTo(w io.Writer) (int64, error) {
    var total int64
    for _, chunk := range d.chunks {
        n, err := w.Write(chunk)
        total += int64(n)
        if err != nil {
            return total, err
        }
    }
    return total, nil
}

// Использование:
data := CustomData{chunks: [][]byte{[]byte("Hello "), []byte("world!")}}
data.WriteTo(os.Stdout) // Выведет "Hello world!"

io.Discard.WriteTo(...) // Ничего не делает

3 - Пакет для работы с файловой системой io/fs

Для поддержки тестирования реализаций файловых систем смотрите пакет testing/fstest.

Переменные

var (
ErrInvalid = errInvalid() // "недопустимый аргумент"
ErrPermission = errPermission() // "разрешение отклонено"
ErrExist = errExist() // "файл уже существует"
ErrNotExist = errNotExist() // "файл не существует"
ErrClosed = errClosed() // "файл уже закрыт"
)

Общие ошибки файловой системы. Ошибки, возвращаемые файловыми системами, можно проверить на соответствие этим ошибкам с помощью errors.Is.

var SkipAll = errors.New("пропустить все и остановить прогулку")

SkipAll используется как возвращаемое значение из WalkDirFunc, чтобы указать, что все оставшиеся файлы и каталоги должны быть пропущены. Ни одна функция не возвращает его в качестве ошибки.

var SkipDir = errors.New("пропустить этот каталог")

SkipDir используется в качестве возвращаемого значения WalkDirFunc, чтобы указать, что каталог, названный в вызове, должен быть пропущен. Ни одна функция не возвращает его в качестве ошибки.

Функции

func FormatDirEntry

func FormatDirEntry(dir DirEntry) string

FormatDirEntry возвращает отформатированную версию dir для удобства чтения. Реализации DirEntry могут вызывать эту функцию из метода String. Результаты для каталога с именем subdir и файла с именем hello.go:

d subdir/
- hello.go

func FormatFileInfo

func FormatFileInfo(info FileInfo) string

FormatFileInfo возвращает отформатированную версию info для удобства чтения. Реализации FileInfo могут вызывать эту функцию из метода String. Результатом для файла с именем «hello.go», размером 100 байт, режимом 0o644, созданного 1 января 1970 года в полдень, будет

-rw-r--r-- 100 1970-01-01 12:00:00 hello.go

func Glob

func Glob(fsys FS, pattern string) (matches []string, err error)

Glob возвращает имена всех файлов, соответствующих pattern, или nil, если нет соответствующих файлов. Синтаксис шаблонов такой же, как в path.Match. Шаблон может описывать иерархические имена, такие как usr/*/bin/ed.

Glob игнорирует ошибки файловой системы, такие как ошибки ввода-вывода при чтении каталогов. Единственная возможная возвращаемая ошибка — path.ErrBadPattern, сообщающая о неверном формате шаблона.

Если fs реализует GlobFS, Glob вызывает fs.Glob. В противном случае Glob использует ReadDir для обхода дерева каталогов и поиска совпадений с шаблоном.

func ReadFile

func ReadFile(fsys FS, name string) ([]byte, error)

ReadFile читает файл с указанным именем из файловой системы fs и возвращает его содержимое. Успешный вызов возвращает ошибку nil, а не io.EOF. (Поскольку ReadFile читает весь файл, ожидаемый EOF от последнего Read не рассматривается как ошибка, о которой следует сообщать).

Если fs реализует ReadFileFS, ReadFile вызывает fs.ReadFile. В противном случае ReadFile вызывает fs.Open и использует Read и Close на возвращенном File.

func ValidPath

func ValidPath(name string) bool

ValidPath сообщает, является ли данное имя пути действительным для использования в вызове Open.

Имена путей, передаваемые в open, представляют собой закодированные в UTF-8, не имеющие корня, разделенные косой чертой последовательности элементов пути, например «x/y/z». Имена путей не должны содержать элемент «.» или «..» или пустую строку, за исключением особого случая, когда имя «.» может использоваться для корневого каталога. Пути не должны начинаться или заканчиваться косой чертой: «/x» и «x/» являются недопустимыми.

Обратите внимание, что пути разделяются косой чертой во всех системах, даже в Windows. Пути, содержащие другие символы, такие как обратная косая черта и двоеточие, принимаются как действительные, но эти символы никогда не должны интерпретироваться реализацией FS как разделители элементов пути.

func WalkDir

func WalkDir(fsys FS, root string, fn WalkDirFunc) error

WalkDir проходит по дереву файлов, корнем которого является root, вызывая fn для каждого файла или каталога в дереве, включая root.

Все ошибки, возникающие при посещении файлов и каталогов, фильтруются fn: подробности см. в документации fs.WalkDirFunc.

Файлы просматриваются в лексическом порядке, что делает вывод детерминированным, но требует, чтобы WalkDir считывал весь каталог в память, прежде чем приступать к просмотру этого каталога.