Go io Package

// Reader — anything you can read bytes from
type Reader interface {
    Read(p []byte) (n int, err error)
}

// Writer — anything you can write bytes to
type Writer interface {
    Write(p []byte) (n int, err error)
}

// Closer — anything that can be closed
type Closer interface {
    Close() error
}

// Seeker — random access within a stream
type Seeker interface {
    Seek(offset int64, whence int) (int64, error)
    // whence: io.SeekStart=0, io.SeekCurrent=1, io.SeekEnd=2
}

// Composed interfaces used throughout the stdlib
// io.ReadCloser   = Reader + Closer  (e.g. http.Response.Body)
// io.WriteCloser  = Writer + Closer
// io.ReadWriter   = Reader + Writer
// io.ReadWriteCloser = Reader + Writer + Closer
// io.ReadSeeker   = Reader + Seeker  (e.g. *os.File, *bytes.Reader)

// io.Reader implementations
var _ io.Reader = (*os.File)(nil)            // files
var _ io.Reader = (*bytes.Buffer)(nil)        // in-memory buffer
var _ io.Reader = (*bytes.Reader)(nil)        // read-only byte slice
var _ io.Reader = (*strings.Reader)(nil)      // read-only string
var _ io.Reader = (net.Conn)(nil)             // network connections
var _ io.Reader = (http.Response{}).Body       // HTTP response body

// io.Writer implementations
var _ io.Writer = (*os.File)(nil)            // files, os.Stdout, os.Stderr
var _ io.Writer = (*bytes.Buffer)(nil)        // in-memory buffer
var _ io.Writer = (http.ResponseWriter)(nil)  // HTTP response
var _ io.Writer = (*bufio.Writer)(nil)        // buffered writer

// Copy(dst Writer, src Reader) → written int64, err error
// Copies until EOF or error; uses a 32 KB internal buffer

// Copy a file
src, _ := os.Open("input.txt")
dst, _ := os.Create("output.txt")
defer src.Close(); defer dst.Close()
n, err := io.Copy(dst, src)
// n = bytes written

// Serve a file over HTTP
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
    f, _ := os.Open("index.html")
    defer f.Close()
    io.Copy(w, f)
})

// CopyN — copy exactly n bytes
io.CopyN(dst, src, 1024)

// CopyBuffer — use your own buffer (avoids alloc in tight loops)
buf := make([]byte, 64*1024)
io.CopyBuffer(dst, src, buf)

// LimitReader — read at most n bytes from r
limited := io.LimitReader(resp.Body, 10*1024*1024) // cap at 10 MB
data, _ := io.ReadAll(limited)

// MultiReader — concatenate multiple readers into one
header := strings.NewReader("HEADER\n")
body   := strings.NewReader("BODY\n")
footer := strings.NewReader("FOOTER\n")
combined := io.MultiReader(header, body, footer)
io.Copy(os.Stdout, combined)
// HEADER
// BODY
// FOOTER

// TeeReader — read and simultaneously write to w
var buf bytes.Buffer
tee := io.TeeReader(resp.Body, &buf) // taps the stream
json.NewDecoder(tee).Decode(&result) // decode AND keep raw bytes in buf

// Pipe creates a connected (PipeReader, PipeWriter) pair
// Write blocks until Read consumes the data (no internal buffer)
pr, pw := io.Pipe()

go func() {
    json.NewEncoder(pw).Encode(myStruct)
    pw.Close()  // signal EOF to reader
}()

var result MyStruct
json.NewDecoder(pr).Decode(&result)

// Common pattern: stream large data through an encoder
// without buffering the whole thing in memory
pr2, pw2 := io.Pipe()
go func() {
    gzip.NewWriter(pw2)  // compress as you go
    pw2.Close()
}()
http.Post(url, "application/gzip", pr2)

// The idiomatic way to read lines from any Reader
scanner := bufio.NewScanner(os.Stdin)
for scanner.Scan() {
    line := scanner.Text()  // string, no trailing \n
    fmt.Println(line)
}
if err := scanner.Err(); err != nil {
    log.Fatal(err)
}

// Read lines from a file
f, _ := os.Open("data.txt")
defer f.Close()
scanner = bufio.NewScanner(f)
for scanner.Scan() {
    fmt.Println(scanner.Text())
}

// Bytes() instead of Text() avoids a string alloc
for scanner.Scan() {
    b := scanner.Bytes()  // valid only until next Scan()
    _ = b
}

// Default split: ScanLines (split on \n)
scanner := bufio.NewScanner(r)

// Split on whitespace-delimited words
scanner.Split(bufio.ScanWords)
for scanner.Scan() {
    fmt.Println(scanner.Text())
}

// Split on individual runes
scanner.Split(bufio.ScanRunes)

// Split on individual bytes
scanner.Split(bufio.ScanBytes)

// Increase buffer for long lines (default 64 KB)
scanner.Buffer(make([]byte, 1*1024*1024), 1*1024*1024)

// A simple counter reader that wraps another reader
type CountReader struct {
    r     io.Reader
    total int64
}

func (c *CountReader) Read(p []byte) (int, error) {
    n, err := c.r.Read(p)
    c.total += int64(n)
    return n, err
}

cr := &CountReader{r: resp.Body}
io.Copy(io.Discard, cr)
fmt.Println("bytes read:", cr.total)

// io.EOF is the expected signal for "no more data"
// Return it (or wrap it) when your reader is exhausted
func (c *CountReader) Read(p []byte) (int, error) {
    if c.total >= c.limit {
        return 0, io.EOF
    }
    // ...
}

// Functions that accept io.Reader are trivially testable
func CountWords(r io.Reader) int {
    scanner := bufio.NewScanner(r)
    scanner.Split(bufio.ScanWords)
    count := 0
    for scanner.Scan() { count++ }
    return count
}

// In tests — no need for real files
func TestCountWords(t *testing.T) {
    r := strings.NewReader("hello world foo")
    got := CountWords(r)
    if got != 3 {
        t.Errorf("got %d, want 3", got)
    }
}

// Functions that accept io.Writer use bytes.Buffer in tests
func TestWrite(t *testing.T) {
    var buf bytes.Buffer
    WriteReport(&buf, data)
    if !strings.Contains(buf.String(), "Total:") {
        t.Error("missing Total: in output")
    }
}