import java.io.IOException;
import org.jspecify.annotations.Nullable;

/**
 * An extension of {@code DataInput} for reading from in-memory byte arrays; its methods offer
 * identical functionality but do not throw {@link IOException}.
 *
 * <p><b>Warning:</b> The caller is responsible for not attempting to read past the end of the
 * array. If any method encounters the end of the array prematurely, it throws {@link

const (
	opRead      readOp = -1 // Any other read operation.
	opInvalid   readOp = 0  // Non-read operation.
	opReadRune1 readOp = 1  // Read rune of size 1.
	opReadRune2 readOp = 2  // Read rune of size 2.
	opReadRune3 readOp = 3  // Read rune of size 3.
	opReadRune4 readOp = 4  // Read rune of size 4.
)

// ErrTooLarge is passed to panic if memory cannot be allocated to store data in a buffer.

   * than would be returned by reading all of the bytes (for example, some special files may return
   * a size of 0 despite actually having content when read).
   *
   * <p>In either case, for mutable sources such as files, a subsequent read may return a different
   * number of bytes if the contents are changed.
   *
   * @throws IOException if an I/O error occurs while reading the size of this source
   */

	// follow line position to add context to errors
	lineNo    int
	lineStart int64
}

// NewDecoder creates new Decoder to read JSON values at the provided
// emitDepth from the provider io.Reader.
// If emitDepth is < 0, values at every depth will be emitted.
func NewDecoder(r io.Reader, emitDepth int) *Decoder {
	d := &Decoder{
		scanner:   newScanner(r),
		emitDepth: emitDepth,
		scratch:   &scratch{data: make([]byte, 1024)},

    private final int bufferSize;

    /** Callback function to process each line as it's read */
    private final Consumer<String> outputCallback;

    /**
     * Creates a new input stream thread.
     *
     * @param is the input stream to read from
     * @param charset the character encoding to use for reading
     * @param bufferSize the maximum number of lines to keep in the buffer (0 to disable buffering)

        boolean hasProperty = false;
        while (reader.nextProperty()) {
            hasProperty = true;
            storage.put(reader.getPropertyName(), reader.getPropertyValue());
            int idx = checkHeaderComment(reader.getCommentLines());
            layout.put(
                    reader.getPropertyName(),
                    new Layout(
                            idx < reader.getCommentLines().size()

        boolean hasProperty = false;
        while (reader.nextProperty()) {
            hasProperty = true;
            storage.put(reader.getPropertyName(), reader.getPropertyValue());
            int idx = checkHeaderComment(reader.getCommentLines());
            layout.put(
                    reader.getPropertyName(),
                    new Layout(
                            idx < reader.getCommentLines().size()

	filePath   string
	verifier   *BitrotVerifier // Holds the bit-rot info
	tillOffset int64           // Affects the length of data requested in disk.ReadFile depending on Read()'s offset
	buf        []byte          // Holds bit-rot verified data
}

func (b *wholeBitrotReader) ReadAt(buf []byte, offset int64) (n int, err error) {
	if b.buf == nil {
		b.buf = make([]byte, b.tillOffset-offset)

              // 1NNNNNNN
              val index = readInt(b, PREFIX_7_BITS)
              readIndexedHeader(index - 1)
            }

            b == 0x40 -> {
              // 01000000
              readLiteralHeaderWithIncrementalIndexingNewName()
            }

            b and 0x40 == 0x40 -> {
              // 01NNNNNN
              val index = readInt(b, PREFIX_6_BITS)

	Error         string
}

func newRandomReader(size int) io.Reader {
	return io.LimitReader(randreader.New(), int64(size))
}

type firstByteRecorder struct {
	t *time.Time
	r io.Reader
}

func (f *firstByteRecorder) Read(p []byte) (n int, err error) {
	if f.t != nil || len(p) == 0 {
		return f.r.Read(p)
	}
	// Read a single byte.
	n, err = f.r.Read(p[:1])
	if n > 0 {
		t := time.Now()
		f.t = &t
	}