io

Documentation

Overview

Package io slightly redefines and extends the standard io package.

The Reader and Writer base interfaces are redefined to also be Closers by default, as stream users should always have the clear option of closing the stream. It should generally be less awkward to implement NoOp Close methods when not needed, rather than always having to check for Closers to ensure clean termination.

Unlike the standard specification, Readers should always strive to fill the given byte slice, and always return an error on shorter reads. It is the caller's responsibility to decide on appropriate fragmented streaming, which they can control through slice length; Readers should not make assumptions in their place. In order to accomodate for time sensitive operations, or guard against infinite blocking, Reader implementations should provide explicit timeout mechanisms. Conversely, Read calls should not return an error if the read is complete.

Index

• Variables
• type BytesReader
  • func (x *BytesReader) Close() error
  • func (x *BytesReader) Read(b []byte) (int, error)
• type Closer
• type MultiWriter
  • func (x MultiWriter) Close() error
  • func (x MultiWriter) Write(b []byte) (int, error)
• type ReadBuffer
  • func ReadBufferMake(src Reader, buf []byte) *ReadBuffer
  • func (x *ReadBuffer) Close() error
  • func (x *ReadBuffer) Read(b []byte) (int, error)
  • func (x *ReadBuffer) Reset(src Reader)
• type ReadWriter
  • func ReadWriterOf(rw io.ReadWriter) ReadWriter
• type Reader
  • func ReaderOf(r io.Reader) Reader
• type WriteBuffer
  • func WriteBufferMake(dst Writer, buf []byte) *WriteBuffer
  • func (x *WriteBuffer) Bytes() []byte
  • func (x *WriteBuffer) Close() error
  • func (x *WriteBuffer) Flush() error
  • func (x *WriteBuffer) Write(b []byte) (int, error)
• type Writer
  • func WriterOf(w io.Writer) Writer

Variables

var EOF = io.EOF

Types

type BytesReader

type BytesReader []byte

A BytesReader attaches a simple Reader interface to a byte slice.

func (*BytesReader) Close

func (x *BytesReader) Close() error

func (*BytesReader) Read

func (x *BytesReader) Read(b []byte) (int, error)

type Closer

type Closer = io.Closer

type MultiWriter

type MultiWriter []Writer

A MultiWriter bundles multiple Writers together.

func (MultiWriter) Close

func (x MultiWriter) Close() error

func (MultiWriter) Write

func (x MultiWriter) Write(b []byte) (int, error)

Write will write b to all bundled Writers sequentially. Will always return len(b). If there is an error, it will be a [MultiError]. Errors do not stop the Write sequence.

type ReadBuffer

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

A ReadBuffer pulls data in buffered chunks, minimizing the number of read calls to the underlying source Reader.

func ReadBufferMake

func ReadBufferMake(src Reader, buf []byte) *ReadBuffer

ReadBufferMake returns a ReadBuffer from [src]. [buf] may be nil, in which case a default sized buffer will be allocated.

func (*ReadBuffer) Close

func (x *ReadBuffer) Close() error

func (*ReadBuffer) Read

func (x *ReadBuffer) Read(b []byte) (int, error)

func (*ReadBuffer) Reset

func (x *ReadBuffer) Reset(src Reader)

Reset discards any pending data and sets the ReadBuffer to start reading from [src].

type ReadWriter

type ReadWriter = io.ReadWriteCloser

func ReadWriterOf

func ReadWriterOf(rw io.ReadWriter) ReadWriter

ReadWriterOf is the ReadWrite equivalent of ReaderOf.

type Reader

type Reader = io.ReadCloser

func ReaderOf

func ReaderOf(r io.Reader) Reader

ReaderOf adapts an io.Reader to this package's conventions: full reads and no error on full read. If it is not a Closer, it will also get a NoOp Close method.

type WriteBuffer

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

A WriteBuffer accumulates Write calls before forwarding them, minimizing calls to the destination.

func WriteBufferMake

func WriteBufferMake(dst Writer, buf []byte) *WriteBuffer

WriteBufferMake returns a WriteBuffer to [dst]. If [buf] is nil, a default will be allocated.

func (*WriteBuffer) Bytes

func (x *WriteBuffer) Bytes() []byte

Bytes returns the currently buffered data.

func (*WriteBuffer) Close

func (x *WriteBuffer) Close() error

Close flushes any remaining data before closing the destination Writer.

func (*WriteBuffer) Flush

func (x *WriteBuffer) Flush() error

Flush writes out any pending data.

func (*WriteBuffer) Write

func (x *WriteBuffer) Write(b []byte) (int, error)

type Writer

type Writer = io.WriteCloser

func WriterOf

func WriterOf(w io.Writer) Writer

WriterOf attaches a NoOp Close method to an io.Writer, if it doesn't already have one.