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 ¶
- Variables
- func MustFprint(w io.Writer, args ...any) (n int)
- func MustFprintf(w io.Writer, format string, args ...any) (n int)
- func MustFprintln(w io.Writer, args ...any) (n int)
- type BufferedReader
- type BufferedWriter
- type ByteConsumer
- type ByteWriter
- type ClosedError
- type Closer
- type EntireLineReader
- type Flusher
- type LineReader
- type LineWriterTo
- type MultiCloser
- type Printer
- type ReaderResetter
- type ResettableBufferedReader
- type ResettableBufferedWriter
- type Resetter
- type RuneConsumer
- type RuneWriter
- type StringWriter
- type WritePanic
- type Writer
- type WriterResetter
Constants ¶
This section is empty.
Variables ¶
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.
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.
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
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
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.
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 ¶
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 ¶
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. // // In particular, // Reset may do nothing if the ReaderResetter is reset to itself. // The reader r can be nil to reset all states and disable further reading. 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.
In particular, The method Reset may do nothing if the ReaderResetter is reset to itself. The reader r can be nil to reset all states and disable further reading.
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).
The reader r can be nil, in which case NewBufferedReader only allocates the buffer, and the reader can be set later via the method Reset. Note that reading before setting up a valid reader may cause panic.
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.
The reader r can be nil, in which case NewBufferedReaderSize only allocates the buffer, and the reader can be set later via the method Reset. Note that reading before setting up a valid reader may cause panic.
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).
The writer w can be nil, in which case NewBufferedWriter only allocates the buffer, and the writer can be set later via the method Reset. Note that writing before setting up a valid writer may cause panic.
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 nonpositive, it uses the default size (4096) instead.
The writer w can be nil, in which case NewBufferedWriterSize only allocates the buffer, and the writer can be set later via the method Reset. Note that writing before setting up a valid writer may cause panic.
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. // // In particular, // Reset may do nothing if the WriterResetter is reset to itself. // The writer w can be nil to discard unflushed data, reset all states, // and disable further writing. 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.
In particular, The method Reset may do nothing if the WriterResetter is reset to itself. The writer w can be nil to discard unflushed data, reset all states, and disable further writing.