plumbing

README

plumbing

Assorted I/O U-bends, T-pieces, etc.

Documentation

Overview

Package plumbing is a collection of assorted I/O helpers.

Index

• func LimitReadCloser(r io.ReadCloser, n int64) io.ReadCloser
• func MultiWriteCloser(writeClosers ...io.WriteCloser) io.WriteCloser
• func NopWriteCloser(w io.Writer) io.WriteCloser
• func PaddedReader(r io.Reader, n int64, fill byte) io.Reader
• func TeeReadCloser(r io.ReadCloser, w io.Writer) io.ReadCloser
• func TeeReaderAt(r io.ReaderAt, w io.Writer) io.ReaderAt
• type LimitedReadCloser
  • func (l *LimitedReadCloser) Close() error
  • func (l *LimitedReadCloser) Read(p []byte) (n int, err error)
• type WriteCounter
  • func (wc *WriteCounter) Count() uint64
  • func (wc *WriteCounter) Write(p []byte) (int, error)

Examples

• LimitReadCloser
• MultiWriteCloser
• NopWriteCloser
• PaddedReader
• TeeReadCloser
• TeeReaderAt
• WriteCounter

Functions

func LimitReadCloser

func LimitReadCloser(r io.ReadCloser, n int64) io.ReadCloser

LimitReadCloser returns an io.ReadCloser that reads from r but stops with EOF after n bytes. The underlying implementation is a *LimitedReadCloser.

Example

in := []byte{0, 1, 2, 3, 4, 5, 6, 7, 8, 9}
reader := LimitReadCloser(ioutil.NopCloser(bytes.NewReader(in)), 5)
writer := new(bytes.Buffer)
if _, err := io.Copy(writer, reader); err != nil {
	panic(err)
}
if err := reader.Close(); err != nil {
	panic(err)
}

fmt.Println(writer.Bytes())

Output:

[0 1 2 3 4]

func MultiWriteCloser

func MultiWriteCloser(writeClosers ...io.WriteCloser) io.WriteCloser

MultiWriteCloser creates a writer that duplicates its writes to all the provided writers, similar to the Unix tee(1) command.

Each write is written to each listed writer, one at a time. If a listed writer returns an error, that overall write operation stops and returns the error; it does not continue down the list.

Example

in := []byte{0, 1, 2, 3}
b1, b2 := new(bytes.Buffer), new(bytes.Buffer)
writer := MultiWriteCloser(NopWriteCloser(b1), NopWriteCloser(b2))
if _, err := writer.Write(in); err != nil {
	panic(err)
}
if err := writer.Close(); err != nil {
	panic(err)
}

fmt.Println(b1.Bytes(), b2.Bytes())

Output:

[0 1 2 3] [0 1 2 3]

func NopWriteCloser

func NopWriteCloser(w io.Writer) io.WriteCloser

NopWriteCloser returns an io.WriteCloser with a no-op Close method wrapping the provided io.Writer w.

Example

writer := NopWriteCloser(new(bytes.Buffer))

fmt.Println(writer.Close())

Output:

<nil>

func PaddedReader

func PaddedReader(r io.Reader, n int64, fill byte) io.Reader

PaddedReader returns an io.Reader that reads at most n bytes from r. If fewer than n bytes are available from r then any remaining bytes return fill instead.

Example

in := []byte{1, 2, 3, 4}
reader := PaddedReader(bytes.NewReader(in), 8, 0)
writer := new(bytes.Buffer)
if _, err := io.Copy(writer, reader); err != nil {
	panic(err)
}

fmt.Println(writer.Bytes())

Output:

[1 2 3 4 0 0 0 0]

func TeeReadCloser

func TeeReadCloser(r io.ReadCloser, w io.Writer) io.ReadCloser

TeeReadCloser returns an io.ReadCloser that writes to w what it reads from r. All reads from r performed through it are matched with corresponding writes to w. There is no internal buffering - the write must complete before the read completes. Any error encountered while writing is reported as a read error.

Example

in := []byte{0, 1, 2, 3, 4, 5, 6, 7, 8, 9}
writer := WriteCounter{}
reader := TeeReadCloser(ioutil.NopCloser(bytes.NewReader(in)), &writer)
defer reader.Close()
if _, err := io.Copy(ioutil.Discard, reader); err != nil {
	panic(err)
}

fmt.Println(writer.Count())

Output:

10

func TeeReaderAt

func TeeReaderAt(r io.ReaderAt, w io.Writer) io.ReaderAt

TeeReaderAt returns an io.ReaderAt that writes to w what it reads from r. All reads from r performed through it are matched with corresponding writes to w. There is no internal buffering - the write must complete before the read completes. Any error encountered while writing is reported as a read error.

Example

// Smallest valid zip archive
in := []byte{80, 75, 5, 6, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0}
writer := WriteCounter{}
if _, err := zip.NewReader(TeeReaderAt(bytes.NewReader(in), &writer), int64(len(in))); err != nil {
	panic(err)
}

fmt.Println(writer.Count())

Output:

44

Types

type LimitedReadCloser

type LimitedReadCloser struct {
	R io.ReadCloser
	N int64
}

A LimitedReadCloser reads from R but limits the amount of data returned to just N bytes. Each call to Read updates N to reflect the new amount remaining. Read returns EOF when N <= 0 or when the underlying R returns EOF.

func (*LimitedReadCloser) Close

func (l *LimitedReadCloser) Close() error

Close closes the LimitedReadCloser, rendering it unusable for I/O.

func (*LimitedReadCloser) Read

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

type WriteCounter

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

WriteCounter is an io.Writer that simply counts the number of bytes written to it.

Example

in := []byte{0, 1, 2, 3, 4, 5, 6, 7, 8, 9}
writer := WriteCounter{}
reader := io.TeeReader(bytes.NewReader(in), &writer)
if _, err := io.CopyN(ioutil.Discard, reader, 4); err != nil {
	panic(err)
}
if _, err := io.Copy(ioutil.Discard, reader); err != nil {
	panic(err)
}

fmt.Println(writer.Count())

Output:

10

func (*WriteCounter) Count

func (wc *WriteCounter) Count() uint64

Count returns the number of bytes written.

func (*WriteCounter) Write

func (wc *WriteCounter) Write(p []byte) (int, error)