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
    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
    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:

    • SIZEOF_SHORT

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

    • SIZEOF_INT

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

    • SIZEOF_LONG

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

    • 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

    • 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

    • 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.
      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.
      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

    • 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