runeio

Documentation

Overview

Package runeio implements a mechanism to read a stream of Unicode code points (runes) from an io.Reader, with an internal buffer to push code points back to the front of the stream to allow limited peeking and rewind.

Index

• Constants
• func Must(x rune, err error) rune
• func MustFunc(f func() (rune, error)) func() rune
• type Offset
• type Reader
  • func NewReader(rd io.Reader) *Reader
  • func (r *Reader) Buffer(buf []byte, capacity int)
  • func (r *Reader) Clear()
  • func (r *Reader) Last() rune
  • func (r *Reader) Next() (rune, error)
  • func (r *Reader) Offset() Offset
  • func (r *Reader) Peek() (rune, error)
  • func (r *Reader) PeekN(dest []rune, n int) (int, error)
  • func (r *Reader) Push(x rune)
  • func (r *Reader) Skip(n int) error

Constants

const RuneEOF = rune(0xFFFFFF)

Functions

func Must

func Must(x rune, err error) rune

Must accepts a (rune, error) pair and always returns a rune value or raises a panic. If the error is nil, returns the input rune as normal. If the error is io.EOF, returns a special RuneEOF value. Otherwise, if the error is not nil, panics, wrapping the error.

func MustFunc

func MustFunc(f func() (rune, error)) func() rune

MustFunc wraps a function that returns a (rune, error) pair with Must and returns a new function that always returns a rune, RuneEOF, or panics.

Types

type Offset

type Offset struct {
	Byte int64 // current steam offset in bytes (0-indexed)
	Rune int64 // current line offset in runes (0-indexed)
	Line int64 // current line (0-indexed)
}

Offset describes an offset into a stream at the time of a call to Reader.Next.

type Reader

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

Reader has a useful zero value, but doesn't have a pushback buffer by default.

func NewReader

func NewReader(rd io.Reader) *Reader

func (*Reader) Buffer

func (r *Reader) Buffer(buf []byte, capacity int)

Buffer sets the initial buffer to use when pushing runes back onto the stack with [Next]. The capacity is in bytes. If buf is not nil, Cap(buf) must be >= the capacity argument. If the Reader already has an existing buffer that is not empty, the existing buffer is copied to the new buffer (if there is not enough space, this will panic - call Reader.Clear first if necessary). If buf is nil, then a new buffer is allocated with the given capacity. If the capacity is zero, then the reader has no pushback buffer and the provided buf is ignored.

For example, to be able to push back at least n Unicode codepoints (runes), pass a buffer with capacity utf8.UTFMax * n, or 4n.

func (*Reader) Clear

func (r *Reader) Clear()

Clear clears the reader's pushback buffer (if one exists).

func (*Reader) Last

func (r *Reader) Last() rune

Last returns the rune most recently returned by [Next]. If [Next] has not yet been called, it panics.

func (*Reader) Next

func (r *Reader) Next() (rune, error)

Next reads a single rune from the input stream or, if runes have been pushed back, reads and removes the most recently pushed rune from the stack. Error may be io.EOF or a read error.

func (*Reader) Offset

func (r *Reader) Offset() Offset

func (*Reader) Peek

func (r *Reader) Peek() (rune, error)

Peek returns what the next call to Reader.Next would return, without advancing the input stream. This requires room on the pushback buffer.

func (*Reader) PeekN

func (r *Reader) PeekN(dest []rune, n int) (int, error)

PeekN stores in dest what the next n calls to Reader.Next would return, without advancing the input stream. This requires room on the pushback buffer. It returns the number of elements read, ending early in the event of EOF. The first n elements of dest are set to the special value RuneEOF unless updated with a successfully peeked value. The pushback buffer must be able to handle at least n elements, in addition to its existing contents.

func (*Reader) Push

func (r *Reader) Push(x rune)

Push adds a rune to an internal stack that runes will be read from before the input stream is read from.

If a maximum buffer capacity has been set, a panic will be raised if pushing a rune would exceed that capacity.

func (*Reader) Skip

func (r *Reader) Skip(n int) error