Documentation
¶
Index ¶
- Constants
- Variables
- func ScanLines[T comparable](data []T, delim T, excluded *T, atEOF bool) (advance int, token []T, err error)
- func WithDelim[T comparable](delim T) cfg.Option[Config[T]]
- func WithExcluded[T comparable](excluded *T) cfg.Option[Config[T]]
- func WithSize[T any](size int) cfg.Option[Config[T]]
- type ComparableReader
- type Config
- type ReadWriter
- type Reader
- func (b *Reader[T]) Buffered() int
- func (b *Reader[T]) Discard(n int) (discarded int, err error)
- func (b *Reader[T]) Peek(n int) ([]T, error)
- func (b *Reader[T]) Read(p []T) (n int, err error)
- func (b *Reader[T]) ReadItem() (T, error)
- func (b *Reader[T]) Reset(r gio.Reader[T])
- func (b *Reader[T]) Size() int
- func (b *Reader[T]) UnreadItem() error
- func (b *Reader[T]) WriteTo(w gio.Writer[T]) (n int64, err error)
- type Scanner
- type SplitFunc
- type Writer
- func (b *Writer[T]) Available() int
- func (b *Writer[T]) AvailableBuffer() []T
- func (b *Writer[T]) Buffered() int
- func (b *Writer[T]) Flush() error
- func (b *Writer[T]) ReadFrom(r gio.Reader[T]) (n int64, err error)
- func (b *Writer[T]) Reset(w gio.Writer[T])
- func (b *Writer[T]) Size() int
- func (b *Writer[T]) Write(p []T) (nn int, err error)
- func (b *Writer[T]) WriteItem(c T) error
Constants ¶
const ( // MaxScanTokenSize is the maximum size used to buffer a token // unless the user provides an explicit buffer with Scanner.Buffer. // The actual maximum token size may be smaller as the buffer // may need to include, for instance, a newline. MaxScanTokenSize = 64 * 1024 )
Variables ¶
var ( ErrInvalidUnreadItem = errors.New("gbufio: invalid use of UnreadItem") ErrBufferFull = errors.New("gbufio: buffer full") ErrNegativeCount = errors.New("gbufio: negative count") )
var ( ErrTooLong = errors.New("gbufio.Scanner: token too long") ErrNegativeAdvance = errors.New("gbufio.Scanner: SplitFunc returns negative advance count") ErrAdvanceTooFar = errors.New("gbufio.Scanner: SplitFunc returns advance count beyond input") ErrBadReadCount = errors.New("gbufio.Scanner: Read returned impossible count") )
Errors returned by Scanner.
var ErrFinalToken = errors.New("final token")
ErrFinalToken is a special sentinel error value. It is intended to be returned by a Split function to indicate that the token being delivered with the error is the last token and scanning should stop after this one. After ErrFinalToken is received by Scan, scanning stops with no error. The value is useful to stop processing early or when it is necessary to deliver a final empty token. One could achieve the same behavior with a custom error value but providing one here is tidier. See the emptyFinalToken example for a use of this value.
Functions ¶
func ScanLines ¶
func ScanLines[T comparable](data []T, delim T, excluded *T, atEOF bool) (advance int, token []T, err error)
ScanLines is a split function for a Scanner that returns each line of text, stripped of any trailing end-of-line marker. The returned line may be empty. The end-of-line marker is one optional carriage return followed by one mandatory newline. In regular expression notation, it is `\r?\n`. The last non-empty line of input will be returned even if it has no newline.
func WithExcluded ¶
func WithExcluded[T comparable](excluded *T) cfg.Option[Config[T]]
Types ¶
type ComparableReader ¶
type ComparableReader[T comparable] struct { *Reader[T] // contains filtered or unexported fields }
func NewComparableReader ¶
func NewComparableReader[T comparable](rd gio.Reader[T], opts ...cfg.Option[Config[T]]) *ComparableReader[T]
NewComparableReader returns a new Reader for types that allow comparisons, unlocking added features to work with this data.
The ComparableReader type can be configured with a set size (via WithSize) and delimiter (via WithDelim).
func (*ComparableReader[T]) ReadItems ¶
func (b *ComparableReader[T]) ReadItems(delim T) ([]T, error)
ReadItems reads until the first occurrence of delim in the input, returning a slice containing the data up to and including the delimiter. If ReadBytes encounters an error before finding a delimiter, it returns the data read before the error and the error itself (often io.EOF). ReadBytes returns err != nil if and only if the returned data does not end in delim. For simple uses, a Scanner may be more convenient.
func (*ComparableReader[T]) ReadLine ¶
func (b *ComparableReader[T]) ReadLine() (line []T, isPrefix bool, err error)
ReadLine is a low-level line-reading primitive. Most callers should use ReadBytes('\n') or ReadString('\n') instead or use a Scanner.
ReadLine tries to return a single line, not including the end-of-line bytes. If the line was too long for the buffer then isPrefix is set and the beginning of the line is returned. The rest of the line will be returned from future calls. isPrefix will be false when returning the last fragment of the line. The returned buffer is only valid until the next call to ReadLine. ReadLine either returns a non-nil line or it returns an error, never both.
The text returned from ReadLine does not include the line end ("\r\n" or "\n"). No indication or error is given if the input ends without a final line end. Calling UnreadByte after ReadLine will always unread the last byte read (possibly a character belonging to the line end) even if that byte is not part of the line returned by ReadLine.
func (*ComparableReader[T]) ReadSlice ¶
func (b *ComparableReader[T]) ReadSlice(delim T) (line []T, err error)
ReadSlice reads until the first occurrence of delim in the input, returning a slice pointing at the items in the buffer. The items stop being valid at the next read. If ReadSlice encounters an error before finding a delimiter, it returns all the data in the buffer and the error itself (often io.EOF). ReadSlice fails with error ErrBufferFull if the buffer fills without a delim. Because the data returned from ReadSlice will be overwritten by the next I/O operation, most clients should use Read or ReadItem instead. ReadSlice returns err != nil if and only if line does not end in delim.
type ReadWriter ¶
ReadWriter stores pointers to a Reader and a Writer. It implements gio.ReadWriter.
func NewReadWriter ¶
func NewReadWriter[T any](r *Reader[T], w *Writer[T]) *ReadWriter[T]
NewReadWriter allocates a new ReadWriter that dispatches to r and w.
type Reader ¶
type Reader[T any] struct { // contains filtered or unexported fields }
Reader implements buffering for a gio.Reader[T] object.
func (*Reader[T]) Buffered ¶
Buffered returns the number of items that can be read from the current buffer.
func (*Reader[T]) Discard ¶
Discard skips the next n items, returning the number of items discarded.
If Discard skips fewer than n items, it also returns an error. If 0 <= n <= b.Buffered(), Discard is guaranteed to succeed without reading from the underlying gio.Reader[T].
func (*Reader[T]) Peek ¶
Peek returns the next n items without advancing the reader. The items stop being valid at the next read call. If Peek returns fewer than n items, it also returns an error explaining why the read is short. The error is ErrBufferFull if n is larger than b's buffer size.
Calling Peek prevents a UnreadItem call from succeeding until the next read operation.
func (*Reader[T]) Read ¶
Read reads data into p. It returns the number of items read into p. The items are taken from at most one Read on the underlying Reader, hence n may be less than len(p). To read exactly len(p) items, use gio.ReadFull(b, p). If the underlying Reader can return a non-zero count with io.EOF, then this Read method can do so as well; see the gio.Reader docs.
func (*Reader[T]) ReadItem ¶
ReadItem reads and returns a single item. If no item is available, returns an error.
func (*Reader[T]) Reset ¶
Reset discards any buffered data, resets all state, and switches the buffered reader to read from r. Calling Reset on the zero value of Reader initializes the internal buffer to the default size. Calling b.Reset(b) (that is, resetting a Reader to itself) does nothing.
func (*Reader[T]) UnreadItem ¶
UnreadItem unreads the last item. Only the most recently read item can be unread.
UnreadItem returns an error if the most recent method called on the Reader was not a read operation. Notably, Peek, Discard, and WriteTo are not considered read operations.
type Scanner ¶
type Scanner[T comparable] struct { // contains filtered or unexported fields }
Scanner provides a convenient interface for reading data such as a file of newline-delimited lines of text. Successive calls to the Scan method will step through the 'tokens' of a file, skipping the bytes between the tokens. The specification of a token is defined by a split function of type SplitFunc; the default split function breaks the input into lines with line termination stripped. Split functions are defined in this package for scanning a file into lines, bytes, UTF-8-encoded runes, and space-delimited words. The client may instead provide a custom split function.
Scanning stops unrecoverably at EOF, the first I/O error, or a token too large to fit in the buffer. When a scan stops, the reader may have advanced arbitrarily far past the last token. Programs that need more control over error handling or large tokens, or must run sequential scans on a reader, should use bufio.Reader instead.
func NewScanner ¶
NewScanner returns a new Scanner to read from r. The split function defaults to ScanLines.
func (*Scanner[T]) Buffer ¶
Buffer sets the initial buffer to use when scanning and the maximum size of buffer that may be allocated during scanning. The maximum token size is the larger of max and cap(buf). If max <= cap(buf), Scan will use this buffer only and do no allocation.
By default, Scan uses an internal buffer and sets the maximum token size to MaxScanTokenSize.
Buffer panics if it is called after scanning has started.
func (*Scanner[T]) Scan ¶
Scan advances the Scanner to the next token, which will then be available through the Bytes or Text method. It returns false when the scan stops, either by reaching the end of the input or an error. After Scan returns false, the Err method will return any error that occurred during scanning, except that if it was io.EOF, Err will return nil. Scan panics if the split function returns too many empty tokens without advancing the input. This is a common error mode for scanners.
type SplitFunc ¶
type SplitFunc[T comparable] func(data []T, delim T, excluded *T, atEOF bool) (advance int, token []T, err error)
SplitFunc is the signature of the split function used to tokenize the input. The arguments are an initial substring of the remaining unprocessed data and a flag, atEOF, that reports whether the Reader has no more data to give. The return values are the number of bytes to advance the input and the next token to return to the user, if any, plus an error, if any.
Scanning stops if the function returns an error, in which case some of the input may be discarded. If that error is ErrFinalToken, scanning stops with no error.
Otherwise, the Scanner advances the input. If the token is not nil, the Scanner returns it to the user. If the token is nil, the Scanner reads more data and continues scanning; if there is no more data--if atEOF was true--the Scanner returns. If the data does not yet hold a complete token, for instance if it has no newline while scanning lines, a SplitFunc can return (0, nil, nil) to signal the Scanner to read more data into the slice and try again with a longer slice starting at the same point in the input.
The function is never called with an empty data slice unless atEOF is true. If atEOF is true, however, data may be non-empty and, as always, holds unprocessed text.
type Writer ¶
type Writer[T any] struct { // contains filtered or unexported fields }
Writer implements buffering for an io.Writer object. If an error occurs writing to a Writer, no more data will be accepted and all subsequent writes, and Flush, will return the error. After all data has been written, the client should call the Flush method to guarantee all data has been forwarded to the underlying io.Writer.
func NewWriter ¶
NewWriter returns a new Writer whose buffer has the default size. If the argument gio.Writer is already a Writer with large enough buffer size, it returns the underlying Writer.
func (*Writer[T]) AvailableBuffer ¶
func (b *Writer[T]) AvailableBuffer() []T
AvailableBuffer returns an empty buffer with b.Available() capacity. This buffer is intended to be appended to and passed to an immediately succeeding Write call. The buffer is only valid until the next write operation on b.
func (*Writer[T]) Buffered ¶
Buffered returns the number of item that have been written into the current buffer.
func (*Writer[T]) ReadFrom ¶
ReadFrom implements io.ReaderFrom. If the underlying writer supports the ReadFrom method, this calls the underlying ReadFrom. If there is buffered data and an underlying ReadFrom, this fills the buffer and writes it before calling ReadFrom.
func (*Writer[T]) Reset ¶
Reset discards any unflushed buffered data, clears any error, and resets b to write its output to w. Calling Reset on the zero value of Writer initializes the internal buffer to the default size. Calling w.Reset(w) (that is, resetting a Writer to itself) does nothing.
Source Files