shared

Documentation

Overview

The `shared` package defines helper types and functions used internally by all the other refmt packages; it is not user-facing.

Index

• type SlickReader
  • func NewBytesReader(buf *bytes.Buffer) SlickReader
  • func NewReader(r io.Reader) SlickReader
  • func NewSliceReader(b []byte) SlickReader
• type SlickReaderSlice
  • func (z *SlickReaderSlice) NumRead() int
  • func (z *SlickReaderSlice) Readb(bs []byte) error
  • func (z *SlickReaderSlice) Readn(n int) (bs []byte, err error)
  • func (z *SlickReaderSlice) Readn1() (v uint8, err error)
  • func (z *SlickReaderSlice) Readnzc(n int) (bs []byte, err error)
  • func (z *SlickReaderSlice) StopTrack() (bs []byte)
  • func (z *SlickReaderSlice) Track()
  • func (z *SlickReaderSlice) Unreadn1()
• type SlickReaderStream
  • func (z *SlickReaderStream) NumRead() int
  • func (z *SlickReaderStream) Readb(bs []byte) error
  • func (z *SlickReaderStream) Readn(n int) (bs []byte, err error)
  • func (z *SlickReaderStream) Readn1() (b uint8, err error)
  • func (z *SlickReaderStream) Readnzc(n int) (bs []byte, err error)
  • func (z *SlickReaderStream) StopTrack() (bs []byte)
  • func (z *SlickReaderStream) Track()
  • func (z *SlickReaderStream) Unreadn1()
• type TokenPump
  • func (p TokenPump) Run() error
• type TokenSink
• type TokenSource

Types

type SlickReader

type SlickReader interface {

	// Read n bytes into a byte slice which may be shared and must not be reused
	// After any additional calls to this reader.
	// Readnzc will use the implementation scratch buffer if possible,
	// i.e. n < len(scratchbuf), or may return a view of the []byte being decoded from.
	// Requesting a zero length read will return `zeroByteSlice`, a len-zero cap-zero slice.
	Readnzc(n int) ([]byte, error)

	// Read n bytes into a new byte slice.
	// If zero-copy views into existing buffers are acceptable (e.g. you know you
	// won't later mutate, reference or expose this memory again), prefer `Readnzc`.
	// If you already have an existing slice of sufficient size to reuse, prefer `Readb`.
	// Requesting a zero length read will return `zeroByteSlice`, a len-zero cap-zero slice.
	Readn(n int) ([]byte, error)

	// Read `len(b)` bytes into the given slice, starting at its beginning,
	// overwriting all values, and disregarding any extra capacity.
	Readb(b []byte) error

	Readn1() (uint8, error)
	Unreadn1()
	NumRead() int // number of bytes read
	Track()
	StopTrack() []byte
}

SlickReader is a hybrid of reader and buffer interfaces with methods giving specific attention to the performance needs found in a decoder. Implementations cover io.Reader as well as []byte directly.

In particular, it allows:

• returning byte-slices with zero-copying (you were warned!) when possible
• returning byte-slices for short reads which will be reused (you were warned!)
• putting a 'track' point in the buffer, and later yielding all those bytes at once
• counting the number of bytes read (for use in parser error messages, mainly)

All of these shortcuts mean correct usage is essential to avoid unexpected behaviors, but in return allow avoiding many, many common sources of memory allocations in a parser.

func NewBytesReader

func NewBytesReader(buf *bytes.Buffer) SlickReader

func NewReader

func NewReader(r io.Reader) SlickReader

func NewSliceReader

func NewSliceReader(b []byte) SlickReader

type SlickReaderSlice

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

SlickReaderSlice implements SlickReader by reading a byte slice directly. Often this means the zero-copy methods can simply return subslices.

func (*SlickReaderSlice) NumRead

func (z *SlickReaderSlice) NumRead() int

func (*SlickReaderSlice) Readb

func (z *SlickReaderSlice) Readb(bs []byte) error

func (*SlickReaderSlice) Readn

func (z *SlickReaderSlice) Readn(n int) (bs []byte, err error)

func (*SlickReaderSlice) Readn1

func (z *SlickReaderSlice) Readn1() (v uint8, err error)

func (*SlickReaderSlice) Readnzc

func (z *SlickReaderSlice) Readnzc(n int) (bs []byte, err error)

func (*SlickReaderSlice) StopTrack

func (z *SlickReaderSlice) StopTrack() (bs []byte)

func (*SlickReaderSlice) Track

func (z *SlickReaderSlice) Track()

func (*SlickReaderSlice) Unreadn1

func (z *SlickReaderSlice) Unreadn1()

type SlickReaderStream

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

SlickReaderStream is a SlickReader that reads off an io.Reader. Initialize it by wrapping an ioDecByteScanner around your io.Reader and dumping it in. While this implementation does use some internal buffers, it's still advisable to use a buffered reader to avoid small reads for any external IO like disk or network.

func (*SlickReaderStream) NumRead

func (z *SlickReaderStream) NumRead() int

func (*SlickReaderStream) Readb

func (z *SlickReaderStream) Readb(bs []byte) error

func (*SlickReaderStream) Readn

func (z *SlickReaderStream) Readn(n int) (bs []byte, err error)

func (*SlickReaderStream) Readn1

func (z *SlickReaderStream) Readn1() (b uint8, err error)

func (*SlickReaderStream) Readnzc

func (z *SlickReaderStream) Readnzc(n int) (bs []byte, err error)

func (*SlickReaderStream) StopTrack

func (z *SlickReaderStream) StopTrack() (bs []byte)

func (*SlickReaderStream) Track

func (z *SlickReaderStream) Track()

func (*SlickReaderStream) Unreadn1

func (z *SlickReaderStream) Unreadn1()

type TokenPump

type TokenPump struct {
	TokenSource
	TokenSink
}

func (TokenPump) Run

func (p TokenPump) Run() error

type TokenSink

type TokenSink interface {
	Step(consume *Token) (done bool, err error)
}

type TokenSource

type TokenSource interface {
	Step(fillme *Token) (done bool, err error)
}