io

type ByteReader interface {
	// ReadByte reads a single byte and returns it. If no byte is
	// available, err will be set.
	//
	// Returns:
	//   - byte: The byte read.
	//   - error: An error if reading from the reader fails.
	//
	// Errors:
	//   - any error: Depends on the implementation.
	ReadByte() (byte, error)
}

type ByteScanner interface {
	// UnreadByte causes the next call to [ReadByte] to return the last
	// byte read.
	//
	// If the last operation was not a successful call to ReadByte,
	// UnreadByte may return an error, unread the last byte read (or the
	// byte prior to the last-unread byte), or (in implementations that
	// support the [Seeker] interface) seek to the start of the byte
	// before the current offset.
	//
	// Errors:
	//   - any error: Depends on the implementation.
	UnreadByte() error

	ByteReader
}

type Reader interface {
	// Read reads up to len(p) bytes. Even if [Read] returns less than
	// len(p), it may use all of p as scratch space during the call.
	//
	// If some data is available but not len(p) bytes, [Read]
	// conventionally returns what is available instead of waiting for
	// more. When [Read] encounters an error or EOF condition after
	// successfully reading n > 0 bytes, it returns the number of bytes
	// read (0 <= n <= len(p)).
	//
	// Callers should always process the n > 0 bytes returned before
	// considering the error err. Doing so correctly handles I/O errors
	// that happen after reading some bytes and also both of the allowed
	// EOF behaviors.
	//
	// If len(p) == 0, [Read] should return n == 0. However, it may
	// return a non-nil error if some error condition is known, such as
	// EOF.
	//
	// Implementations of [Read] are discouraged from returning a zero
	// byte count with a nil error, except when len(p) == 0. Callers
	// should treat a return of 0 and nil as indicating that nothing
	// happened; in particular it does not indicate EOF.
	//
	// Implementations must not retain p.
	//
	// Parameters:
	//   - p: The buffer to read into.
	//
	// Returns:
	//   - int: The number of bytes read. Always non-negative.
	//   - error: An error if reading from the reader fails.
	//
	// Errors:
	//   - any error: Depends on the implementation.
	Read(p []byte) (int, error)
}

type RuneReader interface {
	// ReadRune reads a single encoded Unicode character and returns the
	// rune and its size in bytes. If no character is available, err will
	// be set.
	//
	// Returns:
	//   - rune: The rune read.
	//   - int: The number of bytes read.
	//   - error: An error if reading from the reader fails.
	//
	// Errors:
	//   - any error: Depends on the implementation.
	ReadRune() (rune, int, error)
}

type RuneScanner interface {
	// UnreadRune causes the next call to [ReadRune] to return the last
	// rune read.
	//
	// If the last operation was not a successful call to ReadRune,
	// UnreadRune may return an error, unread the last rune read (or the
	// rune prior to the last-unread rune), or (in implementations that
	// support the [Seeker] interface) seek to the start of the rune
	// before the current offset.
	//
	// Errors:
	//   - any error: Depends on the implementation.
	UnreadRune() error

	RuneReader
}

type StringWriter interface {
	// WriteString is like [Write] but it writes a string. All the
	// properties of [Write] must be met.
	//
	// Parameters:
	//   - str: The string to write.
	//
	// Returns:
	//   - int: The number of bytes written.
	//   - error: An error if writing to the writer fails.
	//
	// Errors:
	//   - any error: Depends on the implementation.
	WriteString(str string) (int, error)
}

type Writer interface {
	// Write writes len(p) bytes from p to the underlying data stream.
	// It returns the number of bytes written from p (0 <= n <= len(p))
	// and any error encountered that caused the write to stop early.
	// [Write] must return a non-nil error if it returns n < len(p).
	// [Write] must not modify the slice data, even temporarily.
	//
	// Implementations must not retain p.
	//
	// Parameters:
	//   - p: The bytes to write.
	//
	// Returns:
	//   - int: The number of bytes written.
	//   - error: An error if writing to the writer fails.
	//
	// Errors:
	//   - any error: Depends on the implementation.
	Write(p []byte) (int, error)
}