Module me.hugmanrique.cartage
Package me.hugmanrique.cartage

Interface Cartridge

All Superinterfaces:
AutoCloseable
All Known Subinterfaces:
GBACartridge, GBCartridge
All Known Implementing Classes:
AbstractCartridge
public interface Cartridge extends AutoCloseable
Represents the contents of a cartridge as a byte buffer.

The cartridge has a certain size, and an offset position for accessing data. The size is non-negative and immutable. The offset is the zero-based index of the next element to be read or written.

Cartridges are closed explicitly (see close()). When a cartridge is closed, the underlying resources associated with said cartridge might be deallocated, and subsequent operation on the cartridge will fail with IllegalStateException.

See Also:
for accessing Game Boy cartridges, for accessing Game Boy Advance cartridges

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Closes the cartridge.
    void
    copyFrom​(MemorySegment source)
    Copies the contents from the given segment to this cartridge.
    void
    copyTo​(OutputStream stream)
    Copies the cartridge contents to the given stream.
    void
    copyTo​(Path path)
    Copies the cartridge contents to the given path.
    void
    copyTo​(MemorySegment dest)
    Copies the cartridge contents to the given segment.
    String
    getAscii​(long offset, int length)
    Decodes length bytes to characters using the StandardCharsets.US_ASCII charset, beginning at the given offset in the cartridge.
    byte
    getByte​(long offset)
    Reads the byte at the given offset.
    void
    getBytes​(long offset, byte[] dest)
    Transfers bytes from the cartridge into the given array, beginning at the given offset in the cartridge.
    void
    getBytes​(long offset, byte[] dest, int destOffset, int length)
    Transfers length bytes from the cartridge into the given array, beginning at the given offset in the cartridge and at the given offset in the array.
    int
    getInt​(long offset)
    Reads the int at the given offset.
    long
    getLong​(long offset)
    Reads the long at the given offset.
    short
    getShort​(long offset)
    Reads the short at the given offset.
    String
    getString​(long offset, int length, Charset charset)
    Decodes length bytes to characters using the given charset, beginning at the given offset in the cartridge.
    int
    getUnsignedByte​(long offset)
    Reads the unsigned byte at the given offset.
    long
    getUnsignedInt​(long offset)
    Reads the unsigned int at the given offset.
    int
    getUnsignedShort​(long offset)
    Reads the unsigned short at the given offset.
    String
    getUtf8​(long offset, int length)
    Decodes length bytes to characters using the StandardCharsets.UTF_8 charset, beginning at the given offset in the cartridge.
    boolean
    hasRemaining()
    Returns whether there exist any bytes between the current offset and the end of the cartridge.
    long
    offset()
    Returns the cartridge's offset.
    ByteOrder
    order()
    Returns the cartridge's byte order.
    void
    order​(ByteOrder order)
    Sets the cartridge's byte order.
    String
    readAscii​(int length)
    Decodes length bytes to characters using the StandardCharsets.US_ASCII charset, beginning at the cartridge's current offset, which is then incremented by length.
    byte
    readByte()
    Reads the byte at the cartridge's current offset, and then increments the offset.
    void
    readBytes​(byte[] dest)
    Transfers bytes from the cartridge into the given array, beginning at the cartridge's current offset, which is then incremented by dest.length.
    void
    readBytes​(byte[] dest, int destOffset, int length)
    Transfers length bytes from the cartridge into the given array, beginning at the cartridge's current offset and at the given offset in the array.
    int
    readInt()
    Reads the int at the cartridge's current offset, and then increments the offset by Integer.BYTES.
    long
    readLong()
    Reads the long at the cartridge's current offset, and then increments the offset by Long.BYTES.
    short
    readShort()
    Reads the short at the cartridge's current offset, and then increments the offset by Short.BYTES.
    String
    readString​(int length, Charset charset)
    Decodes length bytes to characters using the given charset, beginning at the cartridge's current offset, which is then incremented by length.
    int
    readUnsignedByte()
    Reads the unsigned byte at the cartridge's current offset, and then increments the offset.
    long
    readUnsignedInt()
    Reads the unsigned int at the cartridge's current offset, and then increments the offset by Integer.BYTES.
    int
    readUnsignedShort()
    Reads the unsigned short at the cartridge's current offset, and then increments the offset by Short.BYTES.
    String
    readUtf8​(int length)
    Decodes length bytes to characters using the StandardCharsets.UTF_8 charset, beginning at the cartridge's current offset, which is then incremented by length.
    long
    remaining()
    Returns the number of bytes between the current offset and the end of the cartridge.
    int
    setAscii​(long offset, CharSequence sequence)
    Writes the encoded characters using the StandardCharsets.US_ASCII charset, beginning at the given offset in the cartridge.
    void
    setByte​(long offset, byte value)
    Writes the given byte at the given offset.
    void
    setBytes​(long offset, byte[] source)
    Transfers bytes from the given array into the cartridge, beginning at the given offset in the cartridge.
    void
    setBytes​(long offset, byte[] source, int sourceOffset, int length)
    Transfers length bytes from the given array into the cartridge, beginning at the given offset in the cartridge and at the given offset in the array.
    void
    setInt​(long offset, int value)
    Writes the given int at the given offset.
    void
    setLong​(long offset, long value)
    Writes the given long at the given offset.
    void
    setOffset​(long offset)
    Sets the cartridge's offset.
    void
    setShort​(long offset, short value)
    Writes the given short at the given offset.
    int
    setString​(long offset, CharSequence sequence, Charset charset)
    Writes the encoded characters using the given charset, beginning at the given offset in the cartridge.
    void
    setUnsignedByte​(long offset, int value)
    Writes the given unsigned byte at the given offset.
    void
    setUnsignedInt​(long offset, long value)
    Writes the given unsigned int at the given offset.
    void
    setUnsignedShort​(long offset, int value)
    Writes the given unsigned short at the given offset.
    int
    setUtf8​(long offset, CharSequence sequence)
    Writes the encoded characters using the StandardCharsets.UTF_8 charset, beginning at the given offset in the cartridge.
    long
    size()
    Returns the size of the cartridge.
    void
    skip​(long count)
    Increases the cartridge's offset.
    int
    writeAscii​(CharSequence sequence)
    Writes the encoded characters using the StandardCharsets.US_ASCII charset, beginning at the cartridge's current offset, which is then incremented by the number of written bytes.
    void
    writeByte​(byte value)
    Writes the given byte at the cartridge's current offset, and then increments the offset.
    void
    writeBytes​(byte[] source)
    Transfers the entire content of the given array into the cartridge, beginning at the cartridge's current offset, which is then incremented by source.length.
    void
    writeBytes​(byte[] source, int sourceOffset, int length)
    Transfers length bytes from the given array into the cartridge, beginning at the cartridge's current offset and at the given offset in the array.
    void
    writeInt​(int value)
    Writes the given int at the cartridge's current offset, and then increments the offset by Integer.BYTES.
    void
    writeLong​(long value)
    Writes the given long at the cartridge's current offset, and then increments the offset by Long.BYTES.
    void
    writeShort​(short value)
    Writes the given short at the cartridge's current offset, and then increments the offset by Short.BYTES.
    int
    writeString​(CharSequence sequence, Charset charset)
    Writes the encoded characters using the given charset, beginning at the cartridge's current offset, which is then incremented by the number of written bytes.
    void
    writeUnsignedByte​(int value)
    Writes the given unsigned byte at the cartridge's current offset, and then increments the offset.
    void
    writeUnsignedInt​(long value)
    Writes the given unsigned int at the cartridge's current offset, and then increments the offset by Integer.BYTES.
    void
    writeUnsignedShort​(int value)
    Writes the given unsigned short at the cartridge's current offset, and then increments the offset by Short.BYTES.
    int
    writeUtf8​(CharSequence sequence)
    Writes the encoded characters using the StandardCharsets.UTF_8 charset, beginning at the cartridge's current offset, which is then incremented by the number of written bytes.

  • Method Details

    • order

      ByteOrder order()
      Returns the cartridge's byte order.
      Returns:
      the current byte order
      Throws:
      IllegalStateException - if the cartridge is closed

    • order

      void order​(ByteOrder order)
      Sets the cartridge's byte order.
      Parameters:
      order - the new byte order
      Throws:
      IllegalStateException - if the cartridge is closed

    • offset

      long offset()
      Returns the cartridge's offset.
      Returns:
      the current offset, in bytes
      Throws:
      IllegalStateException - if the cartridge is closed

    • setOffset

      void setOffset​(long offset)
      Sets the cartridge's offset.
      Parameters:
      offset - the new offset, in bytes
      Throws:
      IndexOutOfBoundsException - if the given offset is out of bounds, i.e. less than 0 or greater than size()
      IllegalStateException - if the cartridge is closed

    • size

      long size()
      Returns the size of the cartridge.
      Returns:
      the cartridge size, in bytes
      Throws:
      IllegalStateException - if the cartridge is closed

    • remaining

      long remaining()
      Returns the number of bytes between the current offset and the end of the cartridge.
      Returns:
      the number of remaining bytes
      Throws:
      IllegalStateException - if the cartridge is closed

    • hasRemaining

      boolean hasRemaining()
      Returns whether there exist any bytes between the current offset and the end of the cartridge.
      Returns:
      true if and only if remaining() equals 0
      Throws:
      IllegalStateException - if the cartridge is closed

    • skip

      void skip​(long count)
      Increases the cartridge's offset.
      Parameters:
      count - the number of bytes to skip
      Throws:
      IndexOutOfBoundsException - if the given count is less than 0 or greater than remaining()
      IllegalStateException - if the cartridge is closed

    • close

      void close()
      Closes the cartridge. Once closed, any subsequent operation on the cartridge will fail with IllegalStateException.
      Specified by:
      close in interface AutoCloseable
      Throws:
      IllegalStateException - if the cartridge is closed

    • copyFrom

      void copyFrom​(MemorySegment source)
      Copies the contents from the given segment to this cartridge. More specifically, the bytes at offset 0 through cartridge.size() - 1 in the source segment are copied into this cartridge at offset 0 through cartridge.size() - 1.
      Parameters:
      source - the source segment
      Throws:
      IndexOutOfBoundsException - if source.byteSize() > this.size()
      IllegalStateException - if either the source segment or the cartridge are closed

    • copyTo

      void copyTo​(MemorySegment dest)
      Copies the cartridge contents to the given segment. More specifically, the bytes at offset 0 through dest.byteSize() - 1 in the cartridge are copied into the given segment at offset 0 through dest.byteSize() - 1.
      Parameters:
      dest - the destination segment
      Throws:
      IndexOutOfBoundsException - if this.size() > dest.byteSize()
      IllegalStateException - if either the destination segment or the cartridge are closed

    • copyTo

      void copyTo​(Path path) throws IOException
      Copies the cartridge contents to the given path.
      Parameters:
      path - the destination path
      Throws:
      IOException - if an I/O error occurs
      IllegalStateException - if the cartridge is closed

    • copyTo

      void copyTo​(OutputStream stream) throws IOException
      Copies the cartridge contents to the given stream. The stream is not closed.
      Parameters:
      stream - the output stream
      Throws:
      UnsupportedOperationException - if this cartridge's contents cannot be copied into a byte[] instance, e.g. its size is greater than Integer.MAX_VALUE
      IOException - if an I/O error occurs
      IllegalStateException - if the cartridge is closed

    • readByte

      byte readByte()
      Reads the byte at the cartridge's current offset, and then increments the offset.
      Returns:
      the byte value at the current offset
      Throws:
      IndexOutOfBoundsException - if remaining() is 0

    • getByte

      byte getByte​(long offset)
      Reads the byte at the given offset.
      Parameters:
      offset - the offset to read from
      Returns:
      the byte value at the given offset
      Throws:
      IndexOutOfBoundsException - if the given offset is out of bounds, i.e. less than 0 or greater than or equal to size()

    • readUnsignedByte

      int readUnsignedByte()
      Reads the unsigned byte at the cartridge's current offset, and then increments the offset.
      Returns:
      the unsigned byte value at the current offset
      Throws:
      IndexOutOfBoundsException - if remaining() is 0

    • getUnsignedByte

      int getUnsignedByte​(long offset)
      Reads the unsigned byte at the given offset.
      Parameters:
      offset - the offset to read from
      Returns:
      the unsigned byte value at the given offset
      Throws:
      IndexOutOfBoundsException - if the given offset is out of bounds, i.e. less than 0 or greater than or equal to size()

    • writeByte

      void writeByte​(byte value)
      Writes the given byte at the cartridge's current offset, and then increments the offset.
      Parameters:
      value - the byte value to write
      Throws:
      IndexOutOfBoundsException - if remaining() is 0

    • setByte

      void setByte​(long offset, byte value)
      Writes the given byte at the given offset.
      Parameters:
      offset - the offset to write to
      value - the byte value to write
      Throws:
      IndexOutOfBoundsException - if the given offset is out of bounds, i.e. less than 0 or greater than or equal to size()

    • writeUnsignedByte

      void writeUnsignedByte​(int value)
      Writes the given unsigned byte at the cartridge's current offset, and then increments the offset.
      Parameters:
      value - the unsigned byte value to write
      Throws:
      IndexOutOfBoundsException - if remaining() is 0

    • setUnsignedByte

      void setUnsignedByte​(long offset, int value)
      Writes the given unsigned byte at the given offset.
      Parameters:
      offset - the offset to write to
      value - the byte value to write
      Throws:
      IndexOutOfBoundsException - if the given offset is out of bounds, i.e. less than 0 or greater than or equal to size()

    • readShort

      short readShort()
      Reads the short at the cartridge's current offset, and then increments the offset by Short.BYTES.
      Returns:
      the short value at the current offset
      Throws:
      IndexOutOfBoundsException - if remaining() is less than Short.BYTES.

    • getShort

      short getShort​(long offset)
      Reads the short at the given offset.
      Parameters:
      offset - the offset to read from
      Returns:
      the short value at the given offset
      Throws:
      IndexOutOfBoundsException - if the given offset is out of bounds, i.e. less than 0 or greater than ({@link Cartridge#size()} - {@link Short#BYTES})

    • readUnsignedShort

      int readUnsignedShort()
      Reads the unsigned short at the cartridge's current offset, and then increments the offset by Short.BYTES.
      Returns:
      the unsigned short value at the current offset
      Throws:
      IndexOutOfBoundsException - if remaining() is less than Short.BYTES.

    • getUnsignedShort

      int getUnsignedShort​(long offset)
      Reads the unsigned short at the given offset.
      Parameters:
      offset - the offset to read from
      Returns:
      the unsigned short value at the given offset
      Throws:
      IndexOutOfBoundsException - if the given offset is out of bounds, i.e. less than 0 or greater than {@link Cartridge#size()} - {@link Short#BYTES}

    • writeShort

      void writeShort​(short value)
      Writes the given short at the cartridge's current offset, and then increments the offset by Short.BYTES.
      Parameters:
      value - the short value to write
      Throws:
      IndexOutOfBoundsException - if remaining() is less than Short.BYTES

    • setShort

      void setShort​(long offset, short value)
      Writes the given short at the given offset.
      Parameters:
      offset - the offset to write to
      value - the short value to write
      Throws:
      IndexOutOfBoundsException - if the given offset is out of bounds, i.e. less than 0 or greater than ({@link Cartridge#size()} - {@link Short#BYTES})

    • writeUnsignedShort

      void writeUnsignedShort​(int value)
      Writes the given unsigned short at the cartridge's current offset, and then increments the offset by Short.BYTES.
      Parameters:
      value - the unsigned short value to write
      Throws:
      IndexOutOfBoundsException - if remaining() is less than Short.BYTES

    • setUnsignedShort

      void setUnsignedShort​(long offset, int value)
      Writes the given unsigned short at the given offset.
      Parameters:
      offset - the offset to write to
      value - the unsigned short value to write
      Throws:
      IndexOutOfBoundsException - if the given offset is out of bounds, i.e. less than 0 or greater than ({@link Cartridge#size()} - {@link Short#BYTES})

    • readInt

      int readInt()
      Reads the int at the cartridge's current offset, and then increments the offset by Integer.BYTES.
      Returns:
      the int value at the current offset
      Throws:
      IndexOutOfBoundsException - if remaining() is less than Integer.BYTES.

    • getInt

      int getInt​(long offset)
      Reads the int at the given offset.
      Parameters:
      offset - the offset to read from
      Returns:
      the int value at the given offset
      Throws:
      IndexOutOfBoundsException - if the given offset is out of bounds, i.e. less than 0 or greater than ({@link Cartridge#size()} - {@link Integer#BYTES})

    • readUnsignedInt

      long readUnsignedInt()
      Reads the unsigned int at the cartridge's current offset, and then increments the offset by Integer.BYTES.
      Returns:
      the unsigned int value at the current offset
      Throws:
      IndexOutOfBoundsException - if remaining() is less than Integer.BYTES.

    • getUnsignedInt

      long getUnsignedInt​(long offset)
      Reads the unsigned int at the given offset.
      Parameters:
      offset - the offset to read from
      Returns:
      the unsigned int value at the given offset
      Throws:
      IndexOutOfBoundsException - if the given offset is out of bounds, i.e. less than 0 or greater than ({@link Cartridge#size()} - {@link Integer#BYTES})

    • writeInt

      void writeInt​(int value)
      Writes the given int at the cartridge's current offset, and then increments the offset by Integer.BYTES.
      Parameters:
      value - the int value to write
      Throws:
      IndexOutOfBoundsException - if remaining() is less than Integer.BYTES

    • setInt

      void setInt​(long offset, int value)
      Writes the given int at the given offset.
      Parameters:
      offset - the offset to write to
      value - the int value to write
      Throws:
      IndexOutOfBoundsException - if the given offset is out of bounds, i.e. less than 0 or greater than ({@link Cartridge#size()} - {@link Integer#BYTES})

    • writeUnsignedInt

      void writeUnsignedInt​(long value)
      Writes the given unsigned int at the cartridge's current offset, and then increments the offset by Integer.BYTES.
      Parameters:
      value - the unsigned int value to write
      Throws:
      IndexOutOfBoundsException - if remaining() is less than Integer.BYTES

    • setUnsignedInt

      void setUnsignedInt​(long offset, long value)
      Writes the given unsigned int at the given offset.
      Parameters:
      offset - the offset to write to
      value - the unsigned int value to write
      Throws:
      IndexOutOfBoundsException - if the given offset is out of bounds, i.e. less than 0 or greater than ({@link Cartridge#size()} - {@link Integer#BYTES})

    • readLong

      long readLong()
      Reads the long at the cartridge's current offset, and then increments the offset by Long.BYTES.
      Returns:
      the long value at the current offset
      Throws:
      IndexOutOfBoundsException - if remaining() is less than Long.BYTES.

    • getLong

      long getLong​(long offset)
      Reads the long at the given offset.
      Parameters:
      offset - the offset to read from
      Returns:
      the long value at the given offset
      Throws:
      IndexOutOfBoundsException - if the given offset is out of bounds, i.e. less than 0 or greater than ({@link Cartridge#size()} - {@link Long#BYTES})

    • writeLong

      void writeLong​(long value)
      Writes the given long at the cartridge's current offset, and then increments the offset by Long.BYTES.
      Parameters:
      value - the long value to write
      Throws:
      IndexOutOfBoundsException - if remaining() is less than Long.BYTES

    • setLong

      void setLong​(long offset, long value)
      Writes the given long at the given offset.
      Parameters:
      offset - the offset to write to
      value - the long value to write
      Throws:
      IndexOutOfBoundsException - if the given offset is out of bounds, i.e. less than 0 or greater than ({@link Cartridge#size()} - {@link Long#BYTES})

    • readBytes

      void readBytes​(byte[] dest)
      Transfers bytes from the cartridge into the given array, beginning at the cartridge's current offset, which is then incremented by dest.length.
      Parameters:
      dest - the destination array
      Throws:
      IndexOutOfBoundsException - if remaining() is less than dest.length

    • readBytes

      void readBytes​(byte[] dest, int destOffset, int length)
      Transfers length bytes from the cartridge into the given array, beginning at the cartridge's current offset and at the given offset in the array. The cartridge's offset is then incremented by length.
      Parameters:
      dest - the destination array
      destOffset - the offset within the array of the first byte to be written
      length - the number of bytes to be written
      Throws:
      IndexOutOfBoundsException - if destOffset is out of bounds, i.e. less than 0 or greater than dest.length - destOffset; or remaining() is less than length

    • getBytes

      void getBytes​(long offset, byte[] dest)
      Transfers bytes from the cartridge into the given array, beginning at the given offset in the cartridge.
      Parameters:
      offset - the offset in the cartridge from which the first byte will be read
      dest - the destination array
      Throws:
      IndexOutOfBoundsException - if the given offset is out of bounds, i.e. less than 0 or greater than ({@link Cartridge#size()} - dest.length)

    • getBytes

      void getBytes​(long offset, byte[] dest, int destOffset, int length)
      Transfers length bytes from the cartridge into the given array, beginning at the given offset in the cartridge and at the given offset in the array.
      Parameters:
      offset - the offset in the cartridge from which the first byte will be read
      dest - the destination array
      destOffset - the offset within the array of the first byte to be written
      length - the number of bytes to be written
      Throws:
      IndexOutOfBoundsException - if offset is out of bounds, i.e. less than 0 or greater than ({@link Cartridge#size()} - length); or destOffset is out of bounds, i.e. less than 0 or greater than dest.length - length; or remaining() is less than length

    • writeBytes

      void writeBytes​(byte[] source)
      Transfers the entire content of the given array into the cartridge, beginning at the cartridge's current offset, which is then incremented by source.length.
      Parameters:
      source - the source array
      Throws:
      IndexOutOfBoundsException - if remaining() is less than source.length

    • writeBytes

      void writeBytes​(byte[] source, int sourceOffset, int length)
      Transfers length bytes from the given array into the cartridge, beginning at the cartridge's current offset and at the given offset in the array. The cartridge's offset is then incremented by length.
      Parameters:
      source - the source array
      sourceOffset - the offset within the array of the first byte to be read
      length - the number of bytes to be written
      Throws:
      IndexOutOfBoundsException - if sourceOffset is out of bounds, i.e. less than 0 or greater than (source.length - sourceOffset); or remaining() is less than length

    • setBytes

      void setBytes​(long offset, byte[] source)
      Transfers bytes from the given array into the cartridge, beginning at the given offset in the cartridge.
      Parameters:
      offset - the offset in the cartridge at which the first byte will be written
      source - the source array
      Throws:
      IndexOutOfBoundsException - if the given offset is out of bounds, i.e. less than 0 or greater than {@link Cartridge#remaining()} - source.length

    • setBytes

      void setBytes​(long offset, byte[] source, int sourceOffset, int length)
      Transfers length bytes from the given array into the cartridge, beginning at the given offset in the cartridge and at the given offset in the array.
      Parameters:
      offset - the offset in the cartridge at which the first byte will be written
      source - the source array
      sourceOffset - the offset within the array of the first byte to be read
      length - the number of bytes to be written
      Throws:
      IndexOutOfBoundsException - if offset is out of bounds, i.e. less than 0 or greater than ({@link Cartridge#size()} - length); or sourceOffset is out of bounds, i.e. less than 0 or greater than (source.length - length); or remaining() is less than length

    • readString

      String readString​(int length, Charset charset)
      Decodes length bytes to characters using the given charset, beginning at the cartridge's current offset, which is then incremented by length.
      Parameters:
      length - the number of bytes to be read
      charset - the charset to be used
      Returns:
      a string containing the decoded characters
      Throws:
      IndexOutOfBoundsException - if remaining() is less than length

    • getString

      String getString​(long offset, int length, Charset charset)
      Decodes length bytes to characters using the given charset, beginning at the given offset in the cartridge.
      Parameters:
      offset - the offset in the cartridge from which the first byte will be read
      length - the number of bytes to be read
      charset - the charset to be used
      Returns:
      a string containing the decoded characters
      Throws:
      IndexOutOfBoundsException - if offset is out of bounds, i.e. less than 0 or greater than ({@link Cartridge#size()} - length)

    • readAscii

      String readAscii​(int length)
      Decodes length bytes to characters using the StandardCharsets.US_ASCII charset, beginning at the cartridge's current offset, which is then incremented by length.
      Parameters:
      length - the number of bytes to be read
      Returns:
      a string containing the decoded characters
      Throws:
      IndexOutOfBoundsException - if remaining() is less than length

    • getAscii

      String getAscii​(long offset, int length)
      Decodes length bytes to characters using the StandardCharsets.US_ASCII charset, beginning at the given offset in the cartridge.
      Parameters:
      offset - the offset in the cartridge from which the first byte will be read
      length - the number of bytes to be read
      Returns:
      a string containing the decoded characters
      Throws:
      IndexOutOfBoundsException - if offset is out of bounds, i.e. less than 0 or greater than ({@link Cartridge#size()} - length)

    • readUtf8

      String readUtf8​(int length)
      Decodes length bytes to characters using the StandardCharsets.UTF_8 charset, beginning at the cartridge's current offset, which is then incremented by length.
      Parameters:
      length - the number of bytes to be read
      Returns:
      a string containing the decoded characters
      Throws:
      IndexOutOfBoundsException - if remaining() is less than length

    • getUtf8

      String getUtf8​(long offset, int length)
      Decodes length bytes to characters using the StandardCharsets.UTF_8 charset, beginning at the given offset in the cartridge.
      Parameters:
      offset - the offset in the cartridge from which the first byte will be read
      length - the number of bytes to be read
      Returns:
      a string containing the decoded characters
      Throws:
      IndexOutOfBoundsException - if offset is out of bounds, i.e. less than 0 or greater than ({@link Cartridge#size()} - length)

    • writeString

      int writeString​(CharSequence sequence, Charset charset)
      Writes the encoded characters using the given charset, beginning at the cartridge's current offset, which is then incremented by the number of written bytes.
      Parameters:
      sequence - the sequence of characters to be encoded
      charset - the charset to be used
      Returns:
      the number of bytes written to the cartridge
      Throws:
      IndexOutOfBoundsException - if remaining()} is less than the number of bytes to be written

    • setString

      int setString​(long offset, CharSequence sequence, Charset charset)
      Writes the encoded characters using the given charset, beginning at the given offset in the cartridge.
      Parameters:
      offset - the offset in the cartridge at which the first byte will be written
      sequence - the sequence of characters to be encoded
      charset - the charset to be used
      Returns:
      the number of bytes written to the cartridge
      Throws:
      IndexOutOfBoundsException - if the given offset is out of bounds, i.e. less than 0 or greater than size() minus the number of bytes to be written

    • writeAscii

      int writeAscii​(CharSequence sequence)
      Writes the encoded characters using the StandardCharsets.US_ASCII charset, beginning at the cartridge's current offset, which is then incremented by the number of written bytes.
      Parameters:
      sequence - the sequence of characters to be encoded
      Returns:
      the number of bytes written to the cartridge
      Throws:
      IndexOutOfBoundsException - if remaining() is less than the number of bytes to be written

    • setAscii

      int setAscii​(long offset, CharSequence sequence)
      Writes the encoded characters using the StandardCharsets.US_ASCII charset, beginning at the given offset in the cartridge.
      Parameters:
      offset - the offset in the cartridge at which the first byte will be written
      sequence - the sequence of characters to be encoded
      Returns:
      the number of bytes written to the cartridge
      Throws:
      IndexOutOfBoundsException - if the given offset is out of bounds, i.e. less than 0 or greater than size() minus the number of bytes to be written

    • writeUtf8

      int writeUtf8​(CharSequence sequence)
      Writes the encoded characters using the StandardCharsets.UTF_8 charset, beginning at the cartridge's current offset, which is then incremented by the number of written bytes.
      Parameters:
      sequence - the sequence of characters to be encoded
      Returns:
      the number of bytes written to the cartridge
      Throws:
      IndexOutOfBoundsException - if remaining() is less than the number of bytes to be written

    • setUtf8

      int setUtf8​(long offset, CharSequence sequence)
      Writes the encoded characters using the StandardCharsets.UTF_8 charset, beginning at the given offset in the cartridge.
      Parameters:
      offset - the offset in the cartridge at which the first byte will be written
      sequence - the sequence of characters to be encoded
      Returns:
      the number of bytes written to the cartridge
      Throws:
      IndexOutOfBoundsException - if the given offset is out of bounds, i.e. less than 0 or greater than size() minus the number of bytes to be written