inout

package
v0.12.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 16, 2024 License: AGPL-3.0 Imports: 5 Imported by: 1

Documentation

Overview

Package inout provides interfaces and functions for I/O.

For better performance, all functions in this package are unsafe for concurrency unless otherwise specified.

Index

Constants

This section is empty.

Variables

View Source 
var ErrClosed = errors.AutoWrapCustom(
	&ClosedError{device: "closer"},
	errors.PrependFullPkgName,
	0,
	nil,
)

ErrClosed is an error indicating that the closer is already closed.

The client should use errors.Is to test whether an error is ErrClosed.

View Source 
var ErrReaderClosed = errors.AutoWrapCustom(
	NewClosedError("reader", nil),
	errors.PrependFullPkgName,
	0,
	nil,
)

ErrReaderClosed is an error indicating that the reader is already closed.

The client should use errors.Is to test whether an error is ErrReaderClosed.

View Source 
var ErrWriterClosed = errors.AutoWrapCustom(
	NewClosedError("writer", nil),
	errors.PrependFullPkgName,
	0,
	nil,
)

ErrWriterClosed is an error indicating that the writer is already closed.

The client should use errors.Is to test whether an error is ErrWriterClosed.

Functions

func MustFprint added in v0.5.0 

func MustFprint(w io.Writer, args ...any) (n int)

MustFprint is like fmt.Fprint but panics when encountering an error.

If it panics, the error value passed to the call of panic must be exactly of type *WritePanic.

func MustFprintf added in v0.5.0 

func MustFprintf(w io.Writer, format string, args ...any) (n int)

MustFprintf is like fmt.Fprintf but panics when encountering an error.

If it panics, the error value passed to the call of panic must be exactly of type *WritePanic.

func MustFprintln added in v0.5.0 

func MustFprintln(w io.Writer, args ...any) (n int)

MustFprintln is like fmt.Fprintln but panics when encountering an error.

If it panics, the error value passed to the call of panic must be exactly of type *WritePanic.

Types

type BufferedReader 

type BufferedReader interface {
	io.Reader
	io.ByteScanner
	ByteConsumer
	io.RuneScanner
	RuneConsumer
	io.WriterTo
	LineReader
	EntireLineReader
	LineWriterTo

	// Size returns the size of the underlying buffer in bytes.
	Size() int

	// Buffered returns the number of bytes
	// that can be read from the current buffer.
	Buffered() int

	// Peek returns the next n bytes without advancing the reader.
	//
	// The bytes stop being valid at the next read call.
	// If it returns fewer than n bytes,
	// it also returns an error explaining why the read is short.
	// The error is bufio.ErrBufferFull if n is larger than its buffer size.
	// (To test whether err is bufio.ErrBufferFull, use function errors.Is.)
	//
	// Calling Peek prevents an UnreadByte or UnreadRune call from succeeding
	// until the next read operation.
	Peek(n int) (data []byte, err error)

	// Discard skips the next n bytes and returns the number of bytes discarded.
	//
	// If it skips fewer than n bytes, it also returns an error explaining why.
	//
	// If 0 <= n <= Buffered(),
	// it is guaranteed to succeed without reading from the underlying reader.
	Discard(n int) (discarded int, err error)
}

BufferedReader is an interface for a reader with a buffer.

To get a BufferedReader, use function NewBufferedReader or NewBufferedReaderSize.

type BufferedWriter 

type BufferedWriter interface {
	Writer
	ByteWriter
	RuneWriter
	StringWriter
	io.ReaderFrom
	Printer
	Flusher

	// Size returns the size of the underlying buffer in bytes.
	Size() int

	// Buffered returns the number of bytes that
	// have been written into the current buffer.
	Buffered() int

	// Available returns the number of bytes unused in the current buffer.
	Available() int
}

BufferedWriter is an interface for a writer with a buffer.

Note that after all data has been written, the client should call the method Flush to guarantee that all data has been forwarded to the underlying writer.

To get a BufferedWriter, use function NewBufferedWriter or NewBufferedWriterSize.

type ByteConsumer added in v0.8.0 

type ByteConsumer interface {
	// ConsumeByte repeats detecting the next byte in the underlying reader
	// and consuming it until the byte is not the specified byte
	// or ConsumeByte has consumed n bytes (if n is positive).
	//
	// If n is zero, it does nothing and returns (0, nil).
	// If n is negative, it consumes the bytes with no limit.
	//
	// It returns the number of bytes consumed and
	// any error encountered (including io.EOF).
	ConsumeByte(target byte, n int64) (consumed int64, err error)

	// ConsumeByteFunc repeats detecting the next byte in the underlying reader
	// and consuming it until the byte does not satisfy the specified function f
	// or ConsumeByteFunc has consumed n bytes (if n is positive).
	//
	// If n is zero, it does nothing and returns (0, nil).
	// If n is negative, it consumes the bytes with no limit.
	//
	// It returns the number of bytes consumed and
	// any error encountered (including io.EOF).
	ConsumeByteFunc(f func(c byte) bool, n int64) (consumed int64, err error)
}

ByteConsumer contains methods to consume (read and discard) bytes from an io.Reader.

type ByteWriter added in v0.5.0 

type ByteWriter interface {
	io.ByteWriter

	// MustWriteByte is like WriteByte of io.ByteWriter
	// but panics when encountering an error.
	//
	// If it panics, the error value passed to the call of panic
	// must be exactly of type *WritePanic.
	MustWriteByte(c byte)
}

ByteWriter extends io.ByteWriter by adding a MustWriteByte method.

type ClosedError 

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

ClosedError is an error indicating that a closable device is already closed.

It records the device name and possible parent error. The parent error here is used to classify ClosedError instances, not the error that caused the current ClosedError.

The client should use function NewClosedError to create a ClosedError.

ErrClosed is a (direct or indirect) parent error of all ClosedError instances except itself. Therefore, the client can use errors.Is(err, ErrClosed) to test whether err is a ClosedError.

func NewClosedError 

func NewClosedError(deviceName string, parentErr error) *ClosedError

NewClosedError creates a new ClosedError with specified device name and parent error.

parentErr must either be nil or satisfy that errors.Is(parentErr, ErrClosed) is true. If not, NewClosedError panics.

If deviceName is empty, it uses "closer" instead. If parentErr is nil, it uses ErrClosed instead.

func (*ClosedError) DeviceName added in v0.5.0 

func (ce *ClosedError) DeviceName() string

DeviceName returns the device name passed to NewClosedError.

If ce is nil, it returns "<nil>".

func (*ClosedError) Error 

func (ce *ClosedError) Error() string

Error reports the error message.

If ce is nil, it returns "<nil>".

func (*ClosedError) Unwrap 

func (ce *ClosedError) Unwrap() error

Unwrap returns its parent error (if any).

If ce has no parent error, it returns nil.

type Closer 

type Closer interface {
	io.Closer

	// Closed reports whether this closer is closed successfully.
	Closed() bool
}

Closer is an interface combining the basic Close method and a Closed method.

Method Closed reports whether this closer is closed.

func NewNoOpCloser 

func NewNoOpCloser() Closer

NewNoOpCloser creates a new closer with a no-op method Close.

func WrapErrorCloser 

func WrapErrorCloser(
	closer io.Closer,
	deviceName string,
	parentErr error,
) Closer

WrapErrorCloser wraps the specified closer into a Closer, whose method Close does nothing and returns a *ClosedError after the first successful call.

It panics if closer is nil.

deviceName is the name of the specified closer. If deviceName is empty, it uses "closer" instead.

parentErr is the parent error of the ClosedError returned by method Close. The parent error here is used to classify ClosedError instances, not the error that caused the current ClosedError. parentErr must either be nil or satisfy that errors.Is(parentErr, ErrClosed) is true. If not, WrapErrorCloser panics. If parentErr is nil, it uses ErrClosed instead.

func WrapNoErrorCloser 

func WrapNoErrorCloser(closer io.Closer) Closer

WrapNoErrorCloser wraps the specified closer into a Closer, whose method Close does nothing and returns nil after the first successful call.

It panics if closer is nil.

type EntireLineReader added in v0.5.0 

type EntireLineReader interface {
	// ReadEntireLine reads an entire line excluding the end-of-line bytes.
	//
	// It either returns a non-nil line or it returns an error, never both.
	// If an error (including io.EOF) occurs after reading some content,
	// it returns the content as a line and a nil error.
	// The error encountered will be reported on future read calls.
	//
	// No indication or error is given if the input ends
	// without a final line end.
	// Even if the input ends without end-of-line bytes,
	// the content before EOF is treated as a line.
	//
	// Unlike the method ReadLine of interface LineReader,
	// the returned line is always valid.
	// Caller can keep the returned line safely.
	//
	// If the line is too long to be stored in a []byte
	// (hardly happens in text files), it may panic or report an error.
	ReadEntireLine() (line []byte, err error)
}

EntireLineReader is an interface that wraps method ReadEntireLine.

type Flusher 

type Flusher interface {
	// Flush writes any buffered data to the underlying writer.
	//
	// It returns any write error encountered.
	Flush() error
}

Flusher is an interface that wraps the method Flush, which writes any buffered data to the underlying writer.

type LineReader 

type LineReader interface {
	// ReadLine reads a line excluding the end-of-line bytes.
	//
	// If the line is too long for the buffer,
	// then more is set and the beginning of the line is returned.
	// The rest of the line will be returned from future calls.
	// more is false when returning the last fragment of the line.
	//
	// It either returns a non-nil line or it returns an error, never both.
	// If an error (including io.EOF) occurs after reading some content,
	// it returns the content as a line and a nil error.
	// The error encountered will be reported on future read calls.
	//
	// No indication or error is given if the input ends
	// without a final line end.
	// Even if the input ends without end-of-line bytes,
	// the content before EOF is treated as a line.
	//
	// Caller should not keep the return value line,
	// and line is only valid until the next call to the reader,
	// including the method ReadLine and any other possible methods.
	ReadLine() (line []byte, more bool, err error)
}

LineReader is an interface that wraps method ReadLine.

It may be useful to read long lines that are hard to be loaded in a buffer once.

type LineWriterTo 

type LineWriterTo interface {
	// WriteLineTo reads a line excluding the end-of-line bytes
	// from its underlying reader and writes it to w.
	//
	// It stops writing data if an error occurs.
	//
	// It returns the number of bytes written to w and any error encountered.
	//
	// If an error (including io.EOF) occurs while reading from
	// the underlying reader, but some content has already been read,
	// it writes the content as a line and returns a nil error.
	// The error encountered will be reported on future read calls.
	//
	// No indication or error is given if the input ends
	// without a final line end.
	// Even if the input ends without end-of-line bytes,
	// the content before EOF is treated as a line.
	WriteLineTo(w io.Writer) (n int64, err error)
}

LineWriterTo is an interface that wraps method WriteLineTo.

type MultiCloser 

type MultiCloser interface {
	Closer

	// CloserClosed reports whether the specified closer is closed successfully.
	//
	// It returns two boolean indicators:
	// closed reports whether the specified closer
	// has been successfully closed by this MultiCloser.
	// ok reports whether the specified closer is in this MultiCloser.
	CloserClosed(closer io.Closer) (closed, ok bool)
}

MultiCloser is a device to close multiple closers sequentially.

It closes its closers sequentially from the last one to the first one.

Its method Closed returns true if and only if all its closers are already successfully closed.

If its option tryAll is enabled, its method Close tries to close all its closers, regardless of whether any error occurs, and returns all errors encountered. (It returns an ErrorList if there are multiple errors.)

If its option tryAll is disabled, when an error occurs, its method Close stops closing other closers and returns this error.

If its option noError is enabled, its method Close does nothing and returns nil after the first successful call.

If its option noError is disabled, its method Close does nothing and returns a *ClosedError after the first successful call.

func NewMultiCloser 

func NewMultiCloser(tryAll, noError bool, closer ...io.Closer) MultiCloser

NewMultiCloser creates a new MultiCloser.

If the option tryAll is enabled, its method Close tries to close all its closers, regardless of whether any error occurs, and returns all errors encountered. (It returns an ErrorList if there are multiple errors.)

If the option tryAll is disabled, when an error occurs, its method Close stops closing other closers and returns this error.

If the option noError is enabled, its method Close does nothing and returns nil after the first successful call.

If the option noError is disabled, its method Close does nothing and returns a *ClosedError after the first successful call.

closer is the closers provided to the MultiCloser. All nil closers are ignored. If there is no non-nil closer, the MultiCloser performs as an already closed closer.

type Printer added in v0.5.0 

type Printer interface {
	// Printf formats arguments and writes to its underlying data stream.
	// Arguments are handled in the manner of fmt.Printf.
	Printf(format string, args ...any) (n int, err error)

	// MustPrintf is like Printf but panics when encountering an error.
	//
	// If it panics, the error value passed to the call of panic
	// must be exactly of type *WritePanic.
	MustPrintf(format string, args ...any) (n int)

	// Print formats arguments and writes to its underlying data stream.
	// Arguments are handled in the manner of fmt.Print.
	Print(args ...any) (n int, err error)

	// MustPrint is like Print but panics when encountering an error.
	//
	// If it panics, the error value passed to the call of panic
	// must be exactly of type *WritePanic.
	MustPrint(args ...any) (n int)

	// Println formats arguments and writes to its underlying data stream.
	// Arguments are handled in the manner of fmt.Println.
	Println(args ...any) (n int, err error)

	// MustPrintln is like Println but panics when encountering an error.
	//
	// If it panics, the error value passed to the call of panic
	// must be exactly of type *WritePanic.
	MustPrintln(args ...any) (n int)
}

Printer contains methods Printf, Print, Println, and their "Must" versions.

type ReaderResetter 

type ReaderResetter interface {
	// Reset resets all states and switches to read from r.
	Reset(r io.Reader)
}

ReaderResetter is an interface that wraps method Reset, which resets all states of its instance and switches to read from the reader r.

type ResettableBufferedReader 

type ResettableBufferedReader interface {
	BufferedReader
	ReaderResetter
}

ResettableBufferedReader is an interface combining BufferedReader and ReaderResetter.

To get a ResettableBufferedReader, use function NewBufferedReader or NewBufferedReaderSize.

func NewBufferedReader 

func NewBufferedReader(r io.Reader) ResettableBufferedReader

NewBufferedReader creates a ResettableBufferedReader on r, whose buffer has at least the default size (4096 bytes).

func NewBufferedReaderSize 

func NewBufferedReaderSize(r io.Reader, size int) ResettableBufferedReader

NewBufferedReaderSize creates a ResettableBufferedReader on r, whose buffer has at least the specified size.

If size is less than 16, it uses 16 instead.

If r is a ResettableBufferedReader with a large enough buffer, it returns r directly.

type ResettableBufferedWriter 

type ResettableBufferedWriter interface {
	BufferedWriter
	WriterResetter
}

ResettableBufferedWriter is an interface combining BufferedWriter and WriterResetter.

To get a ResettableBufferedWriter, use function NewBufferedWriter or NewBufferedWriterSize.

func NewBufferedWriter 

func NewBufferedWriter(w io.Writer) ResettableBufferedWriter

NewBufferedWriter creates a ResettableBufferedWriter on w, whose buffer has at least the default size (4096 bytes).

func NewBufferedWriterSize 

func NewBufferedWriterSize(w io.Writer, size int) ResettableBufferedWriter

NewBufferedWriterSize creates a ResettableBufferedWriter on w, whose buffer has at least the specified size.

If size is non-positive, it uses the default size (4096) instead.

If w is a ResettableBufferedWriter with a large enough buffer, it returns w directly.

type Resetter 

type Resetter interface {
	// Reset resets all states.
	Reset()
}

Resetter is an interface that wraps method Reset, which resets all states of its instance.

type RuneConsumer added in v0.8.0 

type RuneConsumer interface {
	// ConsumeRune repeats detecting the next rune in the underlying reader
	// and consuming it until the rune is not the specified rune
	// or ConsumeRune has consumed n runes (if n is positive).
	// In particular, if the rune is not a valid Unicode code point in UTF-8,
	// the rune is considered unicode.ReplacementChar (U+FFFD) with a size of 1.
	//
	// If n is zero, ConsumeRune does nothing and returns (0, nil).
	// If n is negative, it consumes the runes with no limit.
	//
	// It returns the number of runes consumed and
	// any error encountered (including io.EOF).
	ConsumeRune(target rune, n int64) (consumed int64, err error)

	// ConsumeRuneFunc repeats detecting the next rune in the underlying reader
	// and consuming it until the rune does not satisfy the specified function f
	// or ConsumeRuneFunc has consumed n runes (if n is positive).
	//
	// If n is zero, it does nothing and returns (0, nil).
	// If n is negative, it consumes the runes with no limit.
	//
	// The parameters of f are the rune and the size of the rune in bytes.
	// In particular, if the rune is not a valid Unicode code point in UTF-8,
	// f gets unicode.ReplacementChar (U+FFFD) with a size of 1.
	//
	// ConsumeRuneFunc returns the number of runes consumed and
	// any error encountered (including io.EOF).
	ConsumeRuneFunc(f func(r rune, size int) bool, n int64) (
		consumed int64, err error)
}

RuneConsumer contains methods to consume (read and discard) runes (Unicode code points) from an io.Reader.

type RuneWriter added in v0.5.0 

type RuneWriter interface {
	// WriteRune writes a single Unicode code point.
	//
	// It returns the number of bytes written and any write error encountered.
	WriteRune(r rune) (size int, err error)

	// MustWriteRune is like WriteRune but panics when encountering an error.
	//
	// If it panics, the error value passed to the call of panic
	// must be exactly of type *WritePanic.
	MustWriteRune(r rune) (size int)
}

RuneWriter contains a WriteRune method and a MustWriteRune method.

type StringWriter added in v0.5.0 

type StringWriter interface {
	io.StringWriter

	// MustWriteString is like WriteString of io.StringWriter
	// but panics when encountering an error.
	//
	// If it panics, the error value passed to the call of panic
	// must be exactly of type *WritePanic.
	MustWriteString(s string) (n int)
}

StringWriter extends io.StringWriter by adding a MustWriteString method.

type WritePanic added in v0.5.0 

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

WritePanic is the error passed to the call of panic in MustWrite methods and MustPrint methods.

It records the error that caused the panic.

func NewWritePanic added in v0.5.0 

func NewWritePanic(causeErr error) *WritePanic

NewWritePanic creates a new WritePanic with specified error that caused the panic.

func (*WritePanic) Error added in v0.5.0 

func (wp *WritePanic) Error() string

Error reports the error message.

If wp is nil, it returns "<nil>".

func (*WritePanic) Unwrap added in v0.5.0 

func (wp *WritePanic) Unwrap() error

Unwrap returns the error that caused this panic.

If wp is nil, it returns nil.

type Writer added in v0.5.0 

type Writer interface {
	io.Writer

	// MustWrite is like Write of io.Writer
	// but panics when encountering an error.
	//
	// If it panics, the error value passed to the call of panic
	// must be exactly of type *WritePanic.
	MustWrite(p []byte) (n int)
}

Writer extends io.Writer by adding a MustWrite method.

type WriterResetter 

type WriterResetter interface {
	// Reset discards any unflushed data, resets all states,
	// and switches to write to w.
	Reset(w io.Writer)
}

WriterResetter is an interface that wraps method Reset, which discards any unflushed data, resets all states of its instance, and switches to write to the writer w.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.