Package ghidra.app.util.bin

# Class BinaryReader

java.lang.Object
ghidra.app.util.bin.BinaryReader

public class BinaryReader extends Object
A class for reading data from a generic byte provider in either big-endian or little-endian.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `BinaryReader.InputStreamReaderFunction<T>`
  Reads and returns an object from the current position in the specified input stream.
  `static interface`
  `BinaryReader.ReaderFunction<T>`
  Reads and returns an object from the current position in the specified BinaryReader.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected DataConverter`
  `converter`
  `protected long`
  `currentIndex`
  `protected final ByteProvider`
  `provider`
  `static final int`
  `SIZEOF_BYTE`
  The size of a BYTE in Java.
  `static final int`
  `SIZEOF_INT`
  The size of an INTEGER in Java.
  `static final int`
  `SIZEOF_LONG`
  The size of a LONG in Java.
  `static final int`
  `SIZEOF_SHORT`
  The size of a SHORT in Java.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `BinaryReader(ByteProvider provider, boolean isLittleEndian)`
  Constructs a reader using the given ByteProvider and endian-order.
  `BinaryReader(ByteProvider provider, DataConverter converter, long initialIndex)`
  Creates a BinaryReader instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `align(int alignValue)`
  Advances the current index so that it aligns to the specified value (if not already aligned).
  `BinaryReader`
  `asBigEndian()`
  Returns a BinaryReader that is in BigEndian mode.
  `BinaryReader`
  `asLittleEndian()`
  Returns a BinaryReader that is in LittleEndian mode.
  `BinaryReader`
  `clone()`
  Returns an independent clone of this reader positioned at the same index.
  `BinaryReader`
  `clone(long newIndex)`
  Returns a clone of this reader, with its own independent current position, positioned at the new index.
  `ByteProvider`
  `getByteProvider()`
  Returns the underlying byte provider.
  `InputStream`
  `getInputStream()`
  Returns an InputStream that is a live view of the BinaryReader's position.
  `long`
  `getPointerIndex()`
  Returns the current index value.
  `boolean`
  `hasNext()`
  Returns true if this stream has data that could be read at the current position.
  `boolean`
  `hasNext(int count)`
  Returns true if this stream has data that could be read at the current position.
  `boolean`
  `isBigEndian()`
  Returns true if this reader will extract values in big endian.
  `boolean`
  `isLittleEndian()`
  Returns true if this reader will extract values in little endian, otherwise in big endian.
  `boolean`
  `isValidIndex(int index)`
  Returns true if the specified unsigned int32 index into the underlying byte provider is valid.
  `boolean`
  `isValidIndex(long index)`
  Returns true if the specified index into the underlying byte provider is valid.
  `boolean`
  `isValidRange(long startIndex, int count)`
  Returns true if the specified range is valid and does not wrap around the end of the index space.
  `long`
  `length()`
  Returns the length of the underlying file.
  `byte`
  `peekNextByte()`
  Peeks at the next byte without incrementing the current index.
  `int`
  `peekNextInt()`
  Peeks at the next integer without incrementing the current index.
  `long`
  `peekNextLong()`
  Peeks at the next long without incrementing the current index.
  `short`
  `peekNextShort()`
  Peeks at the next short without incrementing the current index.
  `String`
  `readAsciiString(long index)`
  Reads a null terminated US-ASCII string, starting at specified index, stopping at the first null character.
  `String`
  `readAsciiString(long index, int length)`
  Reads an fixed length US-ASCII string starting at `index`.
  `byte`
  `readByte(long index)`
  Returns the signed BYTE at `index`.
  `byte[]`
  `readByteArray(long index, int nElements)`
  Returns the BYTE array of `nElements` starting at `index`.
  `int`
  `readInt(long index)`
  Returns the signed INTEGER at `index`.
  `int`
  `readInt(DataConverter dc, long index)`
  Returns the signed INTEGER at `index`.
  `int[]`
  `readIntArray(long index, int nElements)`
  Returns the INTEGER array of `nElements` starting at `index`.
  `long`
  `readLong(long index)`
  Returns the signed LONG at `index`.
  `long`
  `readLong(DataConverter dc, long index)`
  Returns the signed LONG at `index`.
  `long[]`
  `readLongArray(long index, int nElements)`
  Returns the LONG array of `nElements` starting at `index`.
  `<T> T`
  `readNext(BinaryReader.InputStreamReaderFunction<T> func)`
  Reads an object from the current position, using the supplied reader function.
  `<T> T`
  `readNext(BinaryReader.ReaderFunction<T> func)`
  Reads an object from the current position, using the supplied reader function.
  `String`
  `readNextAsciiString()`
  Reads a null terminated US-ASCII string starting at the current index, advancing the current index by the length of the string that was found.
  `String`
  `readNextAsciiString(int length)`
  Reads a fixed length US-ASCII string starting at the current index, advancing the current index by the specified fixed length.
  `byte`
  `readNextByte()`
  Reads the byte at the current index and then increments the current index by `SIZEOF_BYTE`.
  `byte[]`
  `readNextByteArray(int nElements)`
  Reads a byte array of `nElements` starting at the current index and then increments the current index by `SIZEOF_BYTE * nElements`.
  `int`
  `readNextInt()`
  Reads the integer at the current index and then increments the current index by `SIZEOF_INT`.
  `int`
  `readNextInt(DataConverter dc)`
  Reads the integer at the current index and then increments the current index by `SIZEOF_INT`.
  `int[]`
  `readNextIntArray(int nElements)`
  Reads an integer array of `nElements` starting at the current index and then increments the current index by `SIZEOF_INT * nElements`.
  `long`
  `readNextLong()`
  Reads the long at the current index and then increments the current index by `SIZEOF_LONG`.
  `long`
  `readNextLong(DataConverter dc)`
  Reads the long at the current index and then increments the current index by `SIZEOF_LONG`.
  `long[]`
  `readNextLongArray(int nElements)`
  Reads a long array of `nElements` starting at the current index and then increments the current index by `SIZEOF_LONG * nElements`.
  `short`
  `readNextShort()`
  Reads the short at the current index and then increments the current index by `SIZEOF_SHORT`.
  `short`
  `readNextShort(DataConverter dc)`
  Reads the short at the current index and then increments the current index by `SIZEOF_SHORT`.
  `short[]`
  `readNextShortArray(int nElements)`
  Reads a short array of `nElements` starting at the current index and then increments the current index by `SIZEOF_SHORT * nElements`.
  `String`
  `readNextString(int charCount, Charset charset, int charLen)`
  Reads a fixed length string of `charCount` characters starting at the current index, using a specific `Charset`, advancing the current index by the length of the string that was found.
  `String`
  `readNextString(Charset charset, int charLen)`
  Reads a null terminated string starting at the current index, using a specific `Charset`, advancing the current index by the length of the string that was found.
  `String`
  `readNextUnicodeString()`
  Reads a null-terminated UTF-16 Unicode string at the current index, advancing the current index by the length of the string that was found.
  `String`
  `readNextUnicodeString(int charCount)`
  Reads a fixed length UTF-16 Unicode string at the current index, advancing the current index by the length of the string that was found.
  `int`
  `readNextUnsignedByte()`
  Reads the unsigned byte at the current index and then increments the current index by `SIZEOF_BYTE`.
  `long`
  `readNextUnsignedInt()`
  Reads the unsigned integer at the current index and then increments the current index by `SIZEOF_INT`.
  `long`
  `readNextUnsignedInt(DataConverter dc)`
  Reads the unsigned integer at the current index and then increments the current index by `SIZEOF_INT`.
  `int`
  `readNextUnsignedIntExact()`
  Reads an unsigned int32 value, and returns it as a java int (instead of a java long).
  `int`
  `readNextUnsignedIntExact(DataConverter dc)`
  Reads an unsigned int32 value, and returns it as a java int (instead of a java long).
  `int`
  `readNextUnsignedShort()`
  Reads the unsigned short at the current index and then increments the current index by `SIZEOF_SHORT`.
  `int`
  `readNextUnsignedShort(DataConverter dc)`
  Reads the unsigned short at the current index and then increments the current index by `SIZEOF_SHORT`.
  `long`
  `readNextUnsignedValue(int len)`
  Returns the unsigned value of the integer (of the specified length) at the current index.
  `long`
  `readNextUnsignedValue(DataConverter dc, int len)`
  Returns the unsigned value of the integer (of the specified length) at the current index.
  `int`
  `readNextUnsignedVarIntExact(BinaryReader.InputStreamReaderFunction<Long> func)`
  Reads a variable length / unknown format unsigned integer from the current position, using the supplied reader function, returning it (if it fits) as a 32 bit java integer.
  `int`
  `readNextUnsignedVarIntExact(BinaryReader.ReaderFunction<Long> func)`
  Reads a variable length / unknown format unsigned integer from the current position, using the supplied reader function, returning it (if it fits) as a 32 bit java integer.
  `String`
  `readNextUtf8String()`
  Reads a null-terminated UTF-8 string at the current index, advancing the current index by the length of the string that was found.
  `String`
  `readNextUtf8String(int length)`
  Reads a fixed length UTF-8 string the current index, advancing the current index by the length of the string that was found.
  `long`
  `readNextValue(int len)`
  Returns the signed value of the integer (of the specified length) at the current index.
  `long`
  `readNextValue(DataConverter dc, int len)`
  Returns the signed value of the integer (of the specified length) at the current index.
  `int`
  `readNextVarInt(BinaryReader.InputStreamReaderFunction<Long> func)`
  Reads a variable length / unknown format integer from the current position, using the supplied reader function, returning it (if it fits) as a 32 bit java integer.
  `int`
  `readNextVarInt(BinaryReader.ReaderFunction<Long> func)`
  Reads a variable length / unknown format integer from the current position, using the supplied reader function, returning it (if it fits) as a 32 bit java integer.
  `short`
  `readShort(long index)`
  Returns the signed SHORT at `index`.
  `short`
  `readShort(DataConverter dc, long index)`
  Returns the signed SHORT at `index`.
  `short[]`
  `readShortArray(long index, int nElements)`
  Returns the SHORT array of `nElements` starting at `index`.
  `String`
  `readString(long index, int charCount, Charset charset, int charLen)`
  Reads a fixed length string of `charCount` characters starting at `index`, using a specific `Charset`.
  `String`
  `readString(long index, Charset charset, int charLen)`
  Reads a null-terminated string starting at `index`, using a specific `Charset`.
  `String`
  `readUnicodeString(long index)`
  Reads a null-terminated UTF-16 Unicode string starting at `index` and using the pre-specified `endianness`.
  `String`
  `readUnicodeString(long index, int charCount)`
  Reads a fixed length UTF-16 Unicode string of `length` characters starting at `index`, using the pre-specified `endianness`.
  `int`
  `readUnsignedByte(long index)`
  Returns the unsigned BYTE at `index`.
  `long`
  `readUnsignedInt(long index)`
  Returns the unsigned INTEGER at `index`.
  `long`
  `readUnsignedInt(DataConverter dc, long index)`
  Returns the unsigned INTEGER at `index`.
  `int`
  `readUnsignedShort(long index)`
  Returns the unsigned SHORT at `index`.
  `int`
  `readUnsignedShort(DataConverter dc, long index)`
  Returns the unsigned SHORT at `index`.
  `long`
  `readUnsignedValue(long index, int len)`
  Returns the unsigned value of the integer (of the specified length) at the specified offset.
  `long`
  `readUnsignedValue(DataConverter dc, long index, int len)`
  Returns the unsigned value of the integer (of the specified length) at the specified offset.
  `String`
  `readUtf8String(long index)`
  Reads a null-terminated UTF-8 string starting at `index`.
  `String`
  `readUtf8String(long index, int length)`
  Reads a fixed length UTF-8 string of `length` bytes starting at `index`.
  `long`
  `readValue(long index, int len)`
  Returns the signed value of the integer (of the specified length) at the specified offset.
  `long`
  `readValue(DataConverter dc, long index, int len)`
  Returns the signed value of the integer (of the specified length) at the specified offset.
  `void`
  `setLittleEndian(boolean isLittleEndian)`
  Sets the endian of this binary reader.
  `long`
  `setPointerIndex(int index)`
  A convenience method for setting the index using a 32 bit integer.
  `long`
  `setPointerIndex(long index)`
  Sets the current index to the specified value.

  ### Methods inherited from class java.lang.Object

  `equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### SIZEOF_BYTE

    public static final int SIZEOF_BYTE
    The size of a BYTE in Java.
    See Also:
      - Constant Field Values

  - ### SIZEOF_SHORT

    public static final int SIZEOF_SHORT
    The size of a SHORT in Java.
    See Also:
      - Constant Field Values

  - ### SIZEOF_INT

    public static final int SIZEOF_INT
    The size of an INTEGER in Java.
    See Also:
      - Constant Field Values

  - ### SIZEOF_LONG

    public static final int SIZEOF_LONG
    The size of a LONG in Java.
    See Also:
      - Constant Field Values

  - ### provider

    protected final ByteProvider provider

  - ### converter

    protected DataConverter converter

  - ### currentIndex

    protected long currentIndex

- ## Constructor Details

  - ### BinaryReader

    public BinaryReader(ByteProvider provider, boolean isLittleEndian)
    Constructs a reader using the given ByteProvider and endian-order. If isLittleEndian is true, then all values read from the file will be done so assuming little-endian order. Otherwise, if isLittleEndian is false, then all values will be read assuming big-endian order.
    Parameters:
      `provider` - the byte provider
      `isLittleEndian` - the endian-order

  - ### BinaryReader

    public BinaryReader(ByteProvider provider, DataConverter converter, long initialIndex)
    Creates a BinaryReader instance.
    Parameters:
      `provider` - the ByteProvider to use
      `converter` - the `DataConverter` to use
      `initialIndex` - the initial offset

- ## Method Details

  - ### clone

    public BinaryReader clone(long newIndex)
    Returns a clone of this reader, with its own independent current position, positioned at the new index.
    Parameters:
      `newIndex` - the new index
    Returns:
      an independent clone of this reader positioned at the new index

  - ### clone

    public BinaryReader clone()
    Returns an independent clone of this reader positioned at the same index.
    Overrides:
      `clone` in class `Object`
    Returns:
      a independent clone of this reader positioned at the same index

  - ### asBigEndian

    public BinaryReader asBigEndian()
    Returns a BinaryReader that is in BigEndian mode.
    Returns:
      a new independent BinaryReader, at the same position, in BigEndian mode

  - ### asLittleEndian

    public BinaryReader asLittleEndian()
    Returns a BinaryReader that is in LittleEndian mode.
    Returns:
      a new independent instance, at the same position, in LittleEndian mode

  - ### isLittleEndian

    public boolean isLittleEndian()
    Returns true if this reader will extract values in little endian, otherwise in big endian.
    Returns:
      true is little endian, false is big endian

  - ### isBigEndian

    public boolean isBigEndian()
    Returns true if this reader will extract values in big endian.
    Returns:
      true is big endian, false is little endian

  - ### setLittleEndian

    public void setLittleEndian(boolean isLittleEndian)
    Sets the endian of this binary reader.
    Parameters:
      `isLittleEndian` - true for little-endian and false for big-endian

  - ### length

    public long length() throws IOException
    Returns the length of the underlying file.
    Returns:
      returns the length of the underlying file
    Throws:
      `IOException` - if an I/O error occurs

  - ### isValidIndex

    public boolean isValidIndex(int index)
    Returns true if the specified unsigned int32 index into the underlying byte provider is valid.
    Parameters:
      `index` - an integer that is treated as an unsigned int32 index into the byte provider
    Returns:
      returns true if the specified index is valid

  - ### isValidIndex

    public boolean isValidIndex(long index)
    Returns true if the specified index into the underlying byte provider is valid.
    Parameters:
      `index` - the index in the byte provider
    Returns:
      returns true if the specified index is valid

  - ### isValidRange

    public boolean isValidRange(long startIndex, int count)
    Returns true if the specified range is valid and does not wrap around the end of the index space.
    Parameters:
      `startIndex` - the starting index to check, treated as an unsigned int64
      `count` - the number of bytes to check
    Returns:
      boolean true if all bytes between startIndex to startIndex+count (exclusive) are valid (according to the underlying byte provider)

  - ### hasNext

    public boolean hasNext()
    Returns true if this stream has data that could be read at the current position.
    Returns:
      true if there are more bytes that could be read at the `current index`.

  - ### hasNext

    public boolean hasNext(int count)
    Returns true if this stream has data that could be read at the current position.
    Parameters:
      `count` - number of bytes to verify
    Returns:
      true if there are at least count more bytes that could be read at the `current index`.

  - ### align

    public int align(int alignValue)
    Advances the current index so that it aligns to the specified value (if not already aligned).

    For example, if current index was 123 and align value was 16, then current index would be advanced to 128.

    Parameters:
      `alignValue` - position index alignment
    Returns:
      the number of bytes required to align (0..alignValue-1)

  - ### setPointerIndex

    public long setPointerIndex(int index)
    A convenience method for setting the index using a 32 bit integer.
    Parameters:
      `index` - new index, treated as a 32 bit unsigned integer
    Returns:
      previous reader offset for use with `setPointerIndex(long)` to restore previous position.

  - ### setPointerIndex

    public long setPointerIndex(long index)
    Sets the current index to the specified value. The pointer index will allow the reader to operate as a pseudo-iterator.
    Parameters:
      `index` - the byte provider index value
    Returns:
      previous reader offset for use with this method to restore previous position.

  - ### getPointerIndex

    public long getPointerIndex()
    Returns the current index value.
    Returns:
      the current index value

  - ### getInputStream

    public InputStream getInputStream()
    Returns an InputStream that is a live view of the BinaryReader's position.

    Any bytes read with the stream will affect the current position of the BinaryReader, and any change to the BinaryReader's position will affect the next value the inputstream returns.

    Returns:
      `InputStream`

  - ### peekNextByte

    public byte peekNextByte() throws IOException
    Peeks at the next byte without incrementing the current index.
    Returns:
      the next byte
    Throws:
      `IOException` - if an I/O error occurs

  - ### peekNextShort

    public short peekNextShort() throws IOException
    Peeks at the next short without incrementing the current index.
    Returns:
      the next short
    Throws:
      `IOException` - if an I/O error occurs

  - ### peekNextInt

    public int peekNextInt() throws IOException
    Peeks at the next integer without incrementing the current index.
    Returns:
      the next int
    Throws:
      `IOException` - if an I/O error occurs

  - ### peekNextLong

    public long peekNextLong() throws IOException
    Peeks at the next long without incrementing the current index.
    Returns:
      the next long
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextByte

    public byte readNextByte() throws IOException
    Reads the byte at the current index and then increments the current index by `SIZEOF_BYTE`.
    Returns:
      the byte at the current index
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextUnsignedByte

    public int readNextUnsignedByte() throws IOException
    Reads the unsigned byte at the current index and then increments the current index by `SIZEOF_BYTE`.
    Returns:
      the unsigned byte at the current index, as an int
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextShort

    public short readNextShort() throws IOException
    Reads the short at the current index and then increments the current index by `SIZEOF_SHORT`.
    Returns:
      the short at the current index
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextShort

    public short readNextShort(DataConverter dc) throws IOException
    Reads the short at the current index and then increments the current index by `SIZEOF_SHORT`.
    Parameters:
      `dc` - `BE` or `LE`
    Returns:
      the short at the current index
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextUnsignedShort

    public int readNextUnsignedShort() throws IOException
    Reads the unsigned short at the current index and then increments the current index by `SIZEOF_SHORT`.
    Returns:
      the unsigned short at the current index, as an int
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextUnsignedShort

    public int readNextUnsignedShort(DataConverter dc) throws IOException
    Reads the unsigned short at the current index and then increments the current index by `SIZEOF_SHORT`.
    Parameters:
      `dc` - `BE` or `LE`
    Returns:
      the unsigned short at the current index, as an int
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextInt

    public int readNextInt() throws IOException
    Reads the integer at the current index and then increments the current index by `SIZEOF_INT`.
    Returns:
      the integer at the current index
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextInt

    public int readNextInt(DataConverter dc) throws IOException
    Reads the integer at the current index and then increments the current index by `SIZEOF_INT`.
    Parameters:
      `dc` - `BE` or `LE`
    Returns:
      the integer at the current index
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextUnsignedInt

    public long readNextUnsignedInt() throws IOException
    Reads the unsigned integer at the current index and then increments the current index by `SIZEOF_INT`.
    Returns:
      the unsigned integer at the current index, as a long
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextUnsignedInt

    public long readNextUnsignedInt(DataConverter dc) throws IOException
    Reads the unsigned integer at the current index and then increments the current index by `SIZEOF_INT`.
    Parameters:
      `dc` - `BE` or `LE`
    Returns:
      the unsigned integer at the current index, as a long
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextLong

    public long readNextLong() throws IOException
    Reads the long at the current index and then increments the current index by `SIZEOF_LONG`.
    Returns:
      the long at the current index
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextLong

    public long readNextLong(DataConverter dc) throws IOException
    Reads the long at the current index and then increments the current index by `SIZEOF_LONG`.
    Parameters:
      `dc` - `BE` or `LE`
    Returns:
      the long at the current index
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextValue

    public long readNextValue(int len) throws IOException
    Returns the signed value of the integer (of the specified length) at the current index.
    Parameters:
      `len` - the number of bytes that the integer occupies, 1 to 8
    Returns:
      value of requested length, with sign bit extended, in a long
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextValue

    public long readNextValue(DataConverter dc, int len) throws IOException
    Returns the signed value of the integer (of the specified length) at the current index.
    Parameters:
      `dc` - `BE` or `LE`
      `len` - the number of bytes that the integer occupies, 1 to 8
    Returns:
      value of requested length, with sign bit extended, in a long
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextUnsignedValue

    public long readNextUnsignedValue(int len) throws IOException
    Returns the unsigned value of the integer (of the specified length) at the current index.
    Parameters:
      `len` - the number of bytes that the integer occupies, 1 to 8
    Returns:
      unsigned value of requested length, in a long
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextUnsignedValue

    public long readNextUnsignedValue(DataConverter dc, int len) throws IOException
    Returns the unsigned value of the integer (of the specified length) at the current index.
    Parameters:
      `dc` - `BE` or `LE`
      `len` - the number of bytes that the integer occupies, 1 to 8
    Returns:
      unsigned value of requested length, in a long
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextAsciiString

    public String readNextAsciiString() throws IOException
    Reads a null terminated US-ASCII string starting at the current index, advancing the current index by the length of the string that was found.

    Note: this method no longer trims() the returned String.

    Returns:
      the US-ASCII string at the current index
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextAsciiString

    public String readNextAsciiString(int length) throws IOException
    Reads a fixed length US-ASCII string starting at the current index, advancing the current index by the specified fixed length.

    Trailing null terminator characters will be removed. (suitable for reading a string from a fixed length field that is padded with trailing null chars)

    Note: this method no longer trims() the returned String.

    Parameters:
      `length` - number of bytes to read
    Returns:
      the US-ASCII string at the current index
    Throws:
      `IOException` - if an IO-related error occurred

  - ### readNextUnicodeString

    public String readNextUnicodeString() throws IOException
    Reads a null-terminated UTF-16 Unicode string at the current index, advancing the current index by the length of the string that was found.
    Returns:
      UTF-16 string at the current index
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextUnicodeString

    public String readNextUnicodeString(int charCount) throws IOException
    Reads a fixed length UTF-16 Unicode string at the current index, advancing the current index by the length of the string that was found.
    Parameters:
      `charCount` - number of UTF-16 characters to read (not bytes)
    Returns:
      the UTF-16 Unicode string at the current index
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextUtf8String

    public String readNextUtf8String() throws IOException
    Reads a null-terminated UTF-8 string at the current index, advancing the current index by the length of the string that was found.
    Returns:
      UTF-8 string at the current index
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextUtf8String

    public String readNextUtf8String(int length) throws IOException
    Reads a fixed length UTF-8 string the current index, advancing the current index by the length of the string that was found.
    Parameters:
      `length` - number of bytes to read
    Returns:
      the UTF-8 string at the current index
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextString

    public String readNextString(Charset charset, int charLen) throws IOException
    Reads a null terminated string starting at the current index, using a specific `Charset`, advancing the current index by the length of the string that was found.
    Parameters:
      `charset` - `Charset`, see `StandardCharsets`
      `charLen` - number of bytes in each character
    Returns:
      the string
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextString

    public String readNextString(int charCount, Charset charset, int charLen) throws IOException
    Reads a fixed length string of `charCount` characters starting at the current index, using a specific `Charset`, advancing the current index by the length of the string that was found.

    Trailing null terminator characters will be removed. (suitable for reading a string from a fixed length field that is padded with trailing null chars)

    Parameters:
      `charCount` - the number of charLen character elements to read
      `charset` - `Charset`, see `StandardCharsets`
      `charLen` - number of bytes in each character
    Returns:
      the string
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextByteArray

    public byte[] readNextByteArray(int nElements) throws IOException
    Reads a byte array of `nElements` starting at the current index and then increments the current index by `SIZEOF_BYTE * nElements`.
    Parameters:
      `nElements` - number of elements to read
    Returns:
      the byte array starting at the current index
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextShortArray

    public short[] readNextShortArray(int nElements) throws IOException
    Reads a short array of `nElements` starting at the current index and then increments the current index by `SIZEOF_SHORT * nElements`.
    Parameters:
      `nElements` - number of elements to read
    Returns:
      the short array starting at the current index
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextIntArray

    public int[] readNextIntArray(int nElements) throws IOException
    Reads an integer array of `nElements` starting at the current index and then increments the current index by `SIZEOF_INT * nElements`.
    Parameters:
      `nElements` - number of elements to read
    Returns:
      the integer array starting at the current index
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextLongArray

    public long[] readNextLongArray(int nElements) throws IOException
    Reads a long array of `nElements` starting at the current index and then increments the current index by `SIZEOF_LONG * nElements`.
    Parameters:
      `nElements` - number of elements to read
    Returns:
      the long array starting at the current index
    Throws:
      `IOException` - if an I/O error occurs

  - ### readNextUnsignedIntExact

    public int readNextUnsignedIntExact() throws IOException, InvalidDataException
    Reads an unsigned int32 value, and returns it as a java int (instead of a java long).

    If the value is outside the range of 0..Integer.MAX_VALUE, an InvalidDataException is thrown.

    Useful for reading uint32 values that are going to be used in java to allocate arrays or other similar cases where the value must be a java integer.

    Returns:
      the uint32 value read from the stream, if it fits into the range [0..MAX_VALUE] of a java integer
    Throws:
      `IOException` - if there was an error reading
      `InvalidDataException` - if value can not be held in a java integer

  - ### readNextUnsignedIntExact

    public int readNextUnsignedIntExact(DataConverter dc) throws IOException, InvalidDataException
    Reads an unsigned int32 value, and returns it as a java int (instead of a java long).

    If the value is outside the range of 0..Integer.MAX_VALUE, an InvalidDataException is thrown.

    Useful for reading uint32 values that are going to be used in java to allocate arrays or other similar cases where the value must be a java integer.

    Parameters:
      `dc` - `BE` or `LE`
    Returns:
      the uint32 value read from the stream, if it fits into the range [0..MAX_VALUE] of a java integer
    Throws:
      `IOException` - if there was an error reading
      `InvalidDataException` - if value can not be held in a java integer

  - ### readAsciiString

    public String readAsciiString(long index) throws IOException
    Reads a null terminated US-ASCII string, starting at specified index, stopping at the first null character.

    Note: this method no longer trims() the returned String.

    Parameters:
      `index` - starting position of the string
    Returns:
      US-ASCII string, excluding the trailing null terminator character
    Throws:
      `IOException` - if error reading bytes

  - ### readAsciiString

    public String readAsciiString(long index, int length) throws IOException
    Reads an fixed length US-ASCII string starting at `index`.

    Trailing null terminator characters will be removed. (suitable for reading a string from a fixed length field that is padded with trailing null chars)

    Note: this method no longer trims() the returned String.

    Parameters:
      `index` - where the string begins
      `length` - number of bytes to read
    Returns:
      the US-ASCII string
    Throws:
      `IOException` - if an I/O error occurs

  - ### readUnicodeString

    public String readUnicodeString(long index) throws IOException
    Reads a null-terminated UTF-16 Unicode string starting at `index` and using the pre-specified `endianness`.

    The end of the string is denoted by a two-byte (ie. short) `null` character.

    Parameters:
      `index` - where the UTF-16 Unicode string begins
    Returns:
      the UTF-16 Unicode string
    Throws:
      `IOException` - if an I/O error occurs

  - ### readUnicodeString

    public String readUnicodeString(long index, int charCount) throws IOException
    Reads a fixed length UTF-16 Unicode string of `length` characters starting at `index`, using the pre-specified `endianness`.

    Trailing null terminator characters will be removed. (suitable for reading a string from a fixed length field that is padded with trailing null chars)

    Parameters:
      `index` - the index where the UTF-16 Unicode string begins
      `charCount` - the number of UTF-16 character elements to read.
    Returns:
      the UTF-16 Unicode string
    Throws:
      `IOException` - if an I/O error occurs

  - ### readUtf8String

    public String readUtf8String(long index) throws IOException
    Reads a null-terminated UTF-8 string starting at `index`.
    Parameters:
      `index` - where the UTF-8 string begins
    Returns:
      the string
    Throws:
      `IOException` - if an I/O error occurs

  - ### readUtf8String

    public String readUtf8String(long index, int length) throws IOException
    Reads a fixed length UTF-8 string of `length` bytes starting at `index`.

    Trailing null terminator characters will be removed. (suitable for reading a string from a fixed length field that is padded with trailing null chars)

    Parameters:
      `index` - the index where the UTF-8 string begins
      `length` - the number of bytes to read
    Returns:
      the string
    Throws:
      `IOException` - if an I/O error occurs

  - ### readString

    public String readString(long index, int charCount, Charset charset, int charLen) throws IOException
    Reads a fixed length string of `charCount` characters starting at `index`, using a specific `Charset`.

    Trailing null terminator characters will be removed. (suitable for reading a string from a fixed length field that is padded with trailing null chars)

    Parameters:
      `index` - the index where the string begins
      `charCount` - the number of charLen character elements to read
      `charset` - `Charset`, see `StandardCharsets`
      `charLen` - number of bytes in each character
    Returns:
      the string
    Throws:
      `IOException` - if an I/O error occurs

  - ### readString

    public String readString(long index, Charset charset, int charLen) throws IOException
    Reads a null-terminated string starting at `index`, using a specific `Charset`.
    Parameters:
      `index` - where the string begins
      `charset` - `Charset`, see `StandardCharsets`
      `charLen` - number of bytes in each character
    Returns:
      the string
    Throws:
      `IOException` - if an I/O error occurs

  - ### readByte

    public byte readByte(long index) throws IOException
    Returns the signed BYTE at `index`.
    Parameters:
      `index` - the index where the BYTE begins
    Returns:
      the signed BYTE
    Throws:
      `IOException` - if an I/O error occurs

  - ### readUnsignedByte

    public int readUnsignedByte(long index) throws IOException
    Returns the unsigned BYTE at `index`.
    Parameters:
      `index` - the index where the BYTE begins
    Returns:
      the unsigned BYTE as an int
    Throws:
      `IOException` - if an I/O error occurs

  - ### readShort

    public short readShort(long index) throws IOException
    Returns the signed SHORT at `index`.
    Parameters:
      `index` - the index where the SHORT begins
    Returns:
      the signed SHORT
    Throws:
      `IOException` - if an I/O error occurs

  - ### readShort

    public short readShort(DataConverter dc, long index) throws IOException
    Returns the signed SHORT at `index`.
    Parameters:
      `dc` - `BE` or `LE`
      `index` - the index where the SHORT begins
    Returns:
      the signed SHORT
    Throws:
      `IOException` - if an I/O error occurs

  - ### readUnsignedShort

    public int readUnsignedShort(long index) throws IOException
    Returns the unsigned SHORT at `index`.
    Parameters:
      `index` - the index where the SHORT begins
    Returns:
      the unsigned SHORT as an int
    Throws:
      `IOException` - if an I/O error occurs

  - ### readUnsignedShort

    public int readUnsignedShort(DataConverter dc, long index) throws IOException
    Returns the unsigned SHORT at `index`.
    Parameters:
      `dc` - `BE` or `LE`
      `index` - the index where the SHORT begins
    Returns:
      the unsigned SHORT as an int
    Throws:
      `IOException` - if an I/O error occurs

  - ### readInt

    public int readInt(long index) throws IOException
    Returns the signed INTEGER at `index`.
    Parameters:
      `index` - the index where the INTEGER begins
    Returns:
      the signed INTEGER
    Throws:
      `IOException` - if an I/O error occurs

  - ### readInt

    public int readInt(DataConverter dc, long index) throws IOException
    Returns the signed INTEGER at `index`.
    Parameters:
      `dc` - `BE` or `LE`
      `index` - the index where the INTEGER begins
    Returns:
      the signed INTEGER
    Throws:
      `IOException` - if an I/O error occurs

  - ### readUnsignedInt

    public long readUnsignedInt(long index) throws IOException
    Returns the unsigned INTEGER at `index`.
    Parameters:
      `index` - the index where the INTEGER begins
    Returns:
      the unsigned INTEGER as a long
    Throws:
      `IOException` - if an I/O error occurs

  - ### readUnsignedInt

    public long readUnsignedInt(DataConverter dc, long index) throws IOException
    Returns the unsigned INTEGER at `index`.
    Parameters:
      `dc` - `BE` or `LE`
      `index` - the index where the INTEGER begins
    Returns:
      the unsigned INTEGER as a long
    Throws:
      `IOException` - if an I/O error occurs

  - ### readLong

    public long readLong(long index) throws IOException
    Returns the signed LONG at `index`.
    Parameters:
      `index` - the index where the LONG begins
    Returns:
      the LONG
    Throws:
      `IOException` - if an I/O error occurs

  - ### readLong

    public long readLong(DataConverter dc, long index) throws IOException
    Returns the signed LONG at `index`.
    Parameters:
      `dc` - `BE` or `LE`
      `index` - the index where the LONG begins
    Returns:
      the LONG
    Throws:
      `IOException` - if an I/O error occurs

  - ### readValue

    public long readValue(long index, int len) throws IOException
    Returns the signed value of the integer (of the specified length) at the specified offset.
    Parameters:
      `index` - where the value begins
      `len` - the number of bytes that the integer occupies, 1 to 8
    Returns:
      value of requested length, with sign bit extended, in a long
    Throws:
      `IOException` - if an I/O error occurs

  - ### readValue

    public long readValue(DataConverter dc, long index, int len) throws IOException
    Returns the signed value of the integer (of the specified length) at the specified offset.
    Parameters:
      `dc` - `BE` or `LE`
      `index` - where the value begins
      `len` - the number of bytes that the integer occupies, 1 to 8
    Returns:
      value of requested length, with sign bit extended, in a long
    Throws:
      `IOException` - if an I/O error occurs

  - ### readUnsignedValue

    public long readUnsignedValue(long index, int len) throws IOException
    Returns the unsigned value of the integer (of the specified length) at the specified offset.
    Parameters:
      `index` - where the value begins
      `len` - the number of bytes that the integer occupies, 1 to 8
    Returns:
      unsigned value of requested length, in a long
    Throws:
      `IOException` - if an I/O error occurs

  - ### readUnsignedValue

    public long readUnsignedValue(DataConverter dc, long index, int len) throws IOException
    Returns the unsigned value of the integer (of the specified length) at the specified offset.
    Parameters:
      `dc` - `BE` or `LE`
      `index` - where the value begins
      `len` - the number of bytes that the integer occupies, 1 to 8
    Returns:
      unsigned value of requested length, in a long
    Throws:
      `IOException` - if an I/O error occurs

  - ### readByteArray

    public byte[] readByteArray(long index, int nElements) throws IOException
    Returns the BYTE array of `nElements` starting at `index`.
    Parameters:
      `index` - the index where the BYTE begins
      `nElements` - the number of array elements
    Returns:
      the BYTE array
    Throws:
      `IOException` - if an I/O error occurs

  - ### readShortArray

    public short[] readShortArray(long index, int nElements) throws IOException
    Returns the SHORT array of `nElements` starting at `index`.
    Parameters:
      `index` - the index where the SHORT begins
      `nElements` - the number of array elements
    Returns:
      the SHORT array
    Throws:
      `IOException` - if an I/O error occurs

  - ### readIntArray

    public int[] readIntArray(long index, int nElements) throws IOException
    Returns the INTEGER array of `nElements` starting at `index`.
    Parameters:
      `index` - the index where the INTEGER begins
      `nElements` - the number of array elements
    Returns:
      the INTEGER array
    Throws:
      `IOException` - if an I/O error occurs

  - ### readLongArray

    public long[] readLongArray(long index, int nElements) throws IOException
    Returns the LONG array of `nElements` starting at `index`.
    Parameters:
      `index` - the index where the LONG begins
      `nElements` - the number of array elements
    Returns:
      the LONG array
    Throws:
      `IOException` - if an I/O error occurs

  - ### getByteProvider

    public ByteProvider getByteProvider()
    Returns the underlying byte provider.
    Returns:
      the underlying byte provider

  - ### readNextVarInt

    public int readNextVarInt(BinaryReader.ReaderFunction<Long> func) throws IOException, InvalidDataException
    Reads a variable length / unknown format integer from the current position, using the supplied reader function, returning it (if it fits) as a 32 bit java integer.
    Parameters:
      `func` - `BinaryReader.ReaderFunction`
    Returns:
      signed int32
    Throws:
      `IOException` - if error reading or if the value does not fit into a 32 bit java int
      `InvalidDataException` - if value can not be held in a java integer

  - ### readNextVarInt

    public int readNextVarInt(BinaryReader.InputStreamReaderFunction<Long> func) throws IOException, InvalidDataException
    Reads a variable length / unknown format integer from the current position, using the supplied reader function, returning it (if it fits) as a 32 bit java integer.
    Parameters:
      `func` - `BinaryReader.InputStreamReaderFunction`
    Returns:
      signed int32
    Throws:
      `IOException` - if error reading or if the value does not fit into a 32 bit java int
      `InvalidDataException` - if value can not be held in a java integer

  - ### readNextUnsignedVarIntExact

    public int readNextUnsignedVarIntExact(BinaryReader.ReaderFunction<Long> func) throws IOException, InvalidDataException
    Reads a variable length / unknown format unsigned integer from the current position, using the supplied reader function, returning it (if it fits) as a 32 bit java integer.
    Parameters:
      `func` - `BinaryReader.ReaderFunction`
    Returns:
      unsigned int32
    Throws:
      `IOException` - if error reading data
      `InvalidDataException` - if value can not be held in a java integer

  - ### readNextUnsignedVarIntExact

    public int readNextUnsignedVarIntExact(BinaryReader.InputStreamReaderFunction<Long> func) throws IOException, InvalidDataException
    Reads a variable length / unknown format unsigned integer from the current position, using the supplied reader function, returning it (if it fits) as a 32 bit java integer.
    Parameters:
      `func` - `BinaryReader.InputStreamReaderFunction`
    Returns:
      unsigned int32
    Throws:
      `IOException` - if error reading data
      `InvalidDataException` - if value can not be held in a java integer

  - ### readNext

    public <T> T readNext(BinaryReader.ReaderFunction<T> func) throws IOException
    Reads an object from the current position, using the supplied reader function.
    Type Parameters:
      `T` - type of the object that will be returned
    Parameters:
      `func` - `BinaryReader.ReaderFunction` that will read and return an object
    Returns:
      new object of type T
    Throws:
      `IOException` - if error reading

  - ### readNext

    public <T> T readNext(BinaryReader.InputStreamReaderFunction<T> func) throws IOException
    Reads an object from the current position, using the supplied reader function.
    Type Parameters:
      `T` - type of the object that will be returned
    Parameters:
      `func` - `BinaryReader.InputStreamReaderFunction` that will read and return an object
    Returns:
      new object of type T
    Throws:
      `IOException` - if error reading