Package com.castlabs.sdk.base.subtitles.utilities

# Class ParsableByteArray

java.lang.Object
com.castlabs.sdk.base.subtitles.utilities.ParsableByteArray

public final class ParsableByteArray extends Object
Wraps a byte array, providing a set of methods for parsing data from it. Numerical values are parsed with the assumption that their constituent bytes are in big endian order.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `byte[]`
  `data`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ParsableByteArray()`
  Creates a new instance that initially has no backing data.
  `ParsableByteArray(byte[] data)`
  Creates a new instance wrapping `data`, and sets the limit to `data.length`.
  `ParsableByteArray(byte[] data, int limit)`
  Creates a new instance that wraps an existing array.
  `ParsableByteArray(int limit)`
  Creates a new instance with `limit` bytes and sets the limit.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `bytesLeft()`
  Returns the number of bytes yet to be read.
  `int`
  `capacity()`
  Returns the capacity of the array, which may be larger than the limit.
  `byte[]`
  `getData()`
  Returns the underlying array.
  `int`
  `getPosition()`
  Returns the current offset in the array, in bytes.
  `int`
  `limit()`
  Returns the limit.
  `char`
  `peekChar()`
  Peeks at the next char.
  `int`
  `peekUnsignedByte()`
  Peeks at the next byte as an unsigned value.
  `void`
  `readBytes(byte[] buffer, int offset, int length)`
  Reads the next `length` bytes into `buffer` at `offset`.
  `void`
  `readBytes(ParsableBitArray bitArray, int length)`
  Reads the next `length` bytes into `bitArray`, and resets the position of `bitArray` to zero.
  `void`
  `readBytes(ByteBuffer buffer, int length)`
  Reads the next `length` bytes into `buffer`.
  `double`
  `readDouble()`
  Reads the next eight bytes as a 64-bit floating point value.
  `float`
  `readFloat()`
  Reads the next four bytes as a 32-bit floating point value.
  `int`
  `readInt()`
  Reads the next four bytes as a signed value
  `int`
  `readInt24()`
  Reads the next three bytes as a signed value.
  `String`
  `readLine()`
  Reads a line of text.
  `int`
  `readLittleEndianInt()`
  Reads the next four bytes as a signed value in little endian order.
  `int`
  `readLittleEndianInt24()`
  Reads the next three bytes as a signed value in little endian order.
  `long`
  `readLittleEndianLong()`
  Reads the next eight bytes as a signed value in little endian order.
  `short`
  `readLittleEndianShort()`
  Reads the next two bytes as a signed value.
  `long`
  `readLittleEndianUnsignedInt()`
  Reads the next four bytes as an unsigned value in little endian order.
  `int`
  `readLittleEndianUnsignedInt24()`
  Reads the next three bytes as an unsigned value in little endian order.
  `int`
  `readLittleEndianUnsignedIntToInt()`
  Reads the next four bytes as a little endian unsigned integer into an integer, if the top bit is a zero.
  `int`
  `readLittleEndianUnsignedShort()`
  Reads the next two bytes as an unsigned value.
  `long`
  `readLong()`
  Reads the next eight bytes as a signed value.
  `String`
  `readNullTerminatedString()`
  Reads up to the next NUL byte (or the limit) as UTF-8 characters.
  `String`
  `readNullTerminatedString(int length)`
  Reads the next `length` bytes as UTF-8 characters.
  `short`
  `readShort()`
  Reads the next two bytes as a signed value.
  `String`
  `readString(int length)`
  Reads the next `length` bytes as UTF-8 characters.
  `String`
  `readString(int length, Charset charset)`
  Reads the next `length` bytes as characters in the specified `Charset`.
  `int`
  `readSynchSafeInt()`
  Reads a Synchsafe integer.
  `int`
  `readUnsignedByte()`
  Reads the next byte as an unsigned value.
  `int`
  `readUnsignedFixedPoint1616()`
  Reads the next four bytes, returning the integer portion of the fixed point 16.16 integer.
  `long`
  `readUnsignedInt()`
  Reads the next four bytes as an unsigned value.
  `int`
  `readUnsignedInt24()`
  Reads the next three bytes as an unsigned value.
  `int`
  `readUnsignedIntToInt()`
  Reads the next four bytes as an unsigned integer into an integer, if the top bit is a zero.
  `long`
  `readUnsignedLongToLong()`
  Reads the next eight bytes as an unsigned long into a long, if the top bit is a zero.
  `int`
  `readUnsignedShort()`
  Reads the next two bytes as an unsigned value.
  `long`
  `readUtf8EncodedLong()`
  Reads a long value encoded by UTF-8 encoding
  `void`
  `reset()`
  Sets the position and limit to zero.
  `void`
  `reset(byte[] data)`
  Updates the instance to wrap `data`, and resets the position to zero and the limit to `data.length`.
  `void`
  `reset(byte[] data, int limit)`
  Updates the instance to wrap `data`, and resets the position to zero.
  `void`
  `reset(int limit)`
  Resets the position to zero and the limit to the specified value.
  `void`
  `setLimit(int limit)`
  Sets the limit.
  `void`
  `setPosition(int position)`
  Sets the reading offset in the array.
  `void`
  `skipBytes(int bytes)`
  Moves the reading offset by `bytes`.

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

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

- ## Field Details

  - ### data

    public byte[] data

- ## Constructor Details

  - ### ParsableByteArray

    public ParsableByteArray()
    Creates a new instance that initially has no backing data.

  - ### ParsableByteArray

    public ParsableByteArray(int limit)
    Creates a new instance with `limit` bytes and sets the limit.
    Parameters:
      `limit` - The limit to set.

  - ### ParsableByteArray

    public ParsableByteArray(byte[] data)
    Creates a new instance wrapping `data`, and sets the limit to `data.length`.
    Parameters:
      `data` - The array to wrap.

  - ### ParsableByteArray

    public ParsableByteArray(byte[] data, int limit)
    Creates a new instance that wraps an existing array.
    Parameters:
      `data` - The data to wrap.
      `limit` - The limit to set.

- ## Method Details

  - ### reset

    public void reset()
    Sets the position and limit to zero.

  - ### reset

    public void reset(int limit)
    Resets the position to zero and the limit to the specified value. If the limit exceeds the capacity, `data` is replaced with a new array of sufficient size.
    Parameters:
      `limit` - The limit to set.

  - ### reset

    public void reset(byte[] data)
    Updates the instance to wrap `data`, and resets the position to zero and the limit to `data.length`.
    Parameters:
      `data` - The array to wrap.

  - ### reset

    public void reset(byte[] data, int limit)
    Updates the instance to wrap `data`, and resets the position to zero.
    Parameters:
      `data` - The array to wrap.
      `limit` - The limit to set.

  - ### getData

    public byte[] getData()
    Returns the underlying array.

    Changes to this array are reflected in the results of the `read...()` methods.

    This reference must be assumed to become invalid when `reset()` or invalid input: '{@link /*missing*/}' are called (because the array might get reallocated).

  - ### bytesLeft

    public int bytesLeft()
    Returns the number of bytes yet to be read.

  - ### limit

    public int limit()
    Returns the limit.

  - ### setLimit

    public void setLimit(int limit)
    Sets the limit.
    Parameters:
      `limit` - The limit to set.

  - ### getPosition

    public int getPosition()
    Returns the current offset in the array, in bytes.

  - ### capacity

    public int capacity()
    Returns the capacity of the array, which may be larger than the limit.

  - ### setPosition

    public void setPosition(int position)
    Sets the reading offset in the array.
    Parameters:
      `position` - Byte offset in the array from which to read.
    Throws:
      `IllegalArgumentException` - Thrown if the new position is neither in nor at the end of the array.

  - ### skipBytes

    public void skipBytes(int bytes)
    Moves the reading offset by `bytes`.
    Parameters:
      `bytes` - The number of bytes to skip.
    Throws:
      `IllegalArgumentException` - Thrown if the new position is neither in nor at the end of the array.

  - ### readBytes

    public void readBytes(ParsableBitArray bitArray, int length)
    Reads the next `length` bytes into `bitArray`, and resets the position of `bitArray` to zero.
    Parameters:
      `bitArray` - The `ParsableBitArray` into which the bytes should be read.
      `length` - The number of bytes to write.

  - ### readBytes

    public void readBytes(byte[] buffer, int offset, int length)
    Reads the next `length` bytes into `buffer` at `offset`.
    Parameters:
      `buffer` - The array into which the read data should be written.
      `offset` - The offset in `buffer` at which the read data should be written.
      `length` - The number of bytes to read.
    See Also:
      - `System.arraycopy(Object, int, Object, int, int)`

  - ### readBytes

    public void readBytes(ByteBuffer buffer, int length)
    Reads the next `length` bytes into `buffer`.
    Parameters:
      `buffer` - The `ByteBuffer` into which the read data should be written.
      `length` - The number of bytes to read.
    See Also:
      - `ByteBuffer.put(byte[], int, int)`

  - ### peekUnsignedByte

    public int peekUnsignedByte()
    Peeks at the next byte as an unsigned value.

  - ### peekChar

    public char peekChar()
    Peeks at the next char.

  - ### readUnsignedByte

    public int readUnsignedByte()
    Reads the next byte as an unsigned value.

  - ### readUnsignedShort

    public int readUnsignedShort()
    Reads the next two bytes as an unsigned value.

  - ### readLittleEndianUnsignedShort

    public int readLittleEndianUnsignedShort()
    Reads the next two bytes as an unsigned value.

  - ### readShort

    public short readShort()
    Reads the next two bytes as a signed value.

  - ### readLittleEndianShort

    public short readLittleEndianShort()
    Reads the next two bytes as a signed value.

  - ### readUnsignedInt24

    public int readUnsignedInt24()
    Reads the next three bytes as an unsigned value.

  - ### readInt24

    public int readInt24()
    Reads the next three bytes as a signed value.

  - ### readLittleEndianInt24

    public int readLittleEndianInt24()
    Reads the next three bytes as a signed value in little endian order.

  - ### readLittleEndianUnsignedInt24

    public int readLittleEndianUnsignedInt24()
    Reads the next three bytes as an unsigned value in little endian order.

  - ### readUnsignedInt

    public long readUnsignedInt()
    Reads the next four bytes as an unsigned value.

  - ### readLittleEndianUnsignedInt

    public long readLittleEndianUnsignedInt()
    Reads the next four bytes as an unsigned value in little endian order.

  - ### readInt

    public int readInt()
    Reads the next four bytes as a signed value

  - ### readLittleEndianInt

    public int readLittleEndianInt()
    Reads the next four bytes as a signed value in little endian order.

  - ### readLong

    public long readLong()
    Reads the next eight bytes as a signed value.

  - ### readLittleEndianLong

    public long readLittleEndianLong()
    Reads the next eight bytes as a signed value in little endian order.

  - ### readUnsignedFixedPoint1616

    public int readUnsignedFixedPoint1616()
    Reads the next four bytes, returning the integer portion of the fixed point 16.16 integer.

  - ### readSynchSafeInt

    public int readSynchSafeInt()
    Reads a Synchsafe integer.

    Synchsafe integers keep the highest bit of every byte zeroed. A 32 bit synchsafe integer can store 28 bits of information.

    Returns:
      The parsed value.

  - ### readUnsignedIntToInt

    public int readUnsignedIntToInt()
    Reads the next four bytes as an unsigned integer into an integer, if the top bit is a zero.
    Throws:
      `IllegalStateException` - Thrown if the top bit of the input data is set.

  - ### readLittleEndianUnsignedIntToInt

    public int readLittleEndianUnsignedIntToInt()
    Reads the next four bytes as a little endian unsigned integer into an integer, if the top bit is a zero.
    Throws:
      `IllegalStateException` - Thrown if the top bit of the input data is set.

  - ### readUnsignedLongToLong

    public long readUnsignedLongToLong()
    Reads the next eight bytes as an unsigned long into a long, if the top bit is a zero.
    Throws:
      `IllegalStateException` - Thrown if the top bit of the input data is set.

  - ### readFloat

    public float readFloat()
    Reads the next four bytes as a 32-bit floating point value.

  - ### readDouble

    public double readDouble()
    Reads the next eight bytes as a 64-bit floating point value.

  - ### readString

    public String readString(int length)
    Reads the next `length` bytes as UTF-8 characters.
    Parameters:
      `length` - The number of bytes to read.
    Returns:
      The string encoded by the bytes.

  - ### readString

    public String readString(int length, Charset charset)
    Reads the next `length` bytes as characters in the specified `Charset`.
    Parameters:
      `length` - The number of bytes to read.
      `charset` - The character set of the encoded characters.
    Returns:
      The string encoded by the bytes in the specified character set.

  - ### readNullTerminatedString

    public String readNullTerminatedString(int length)
    Reads the next `length` bytes as UTF-8 characters. A terminating NUL byte is discarded, if present.
    Parameters:
      `length` - The number of bytes to read.
    Returns:
      The string, not including any terminating NUL byte.

  - ### readNullTerminatedString

    @Nullable public String readNullTerminatedString()
    Reads up to the next NUL byte (or the limit) as UTF-8 characters.
    Returns:
      The string not including any terminating NUL byte, or null if the end of the data has already been reached.

  - ### readLine

    @Nullable public String readLine()
    Reads a line of text.

    A line is considered to be terminated by any one of a carriage return ('\r'), a line feed ('\n'), or a carriage return followed immediately by a line feed ('\r\n'). The system's default charset (UTF-8) is used. This method discards leading UTF-8 byte order marks, if present.

    Returns:
      The line not including any line-termination characters, or null if the end of the data has already been reached.

  - ### readUtf8EncodedLong

    public long readUtf8EncodedLong()
    Reads a long value encoded by UTF-8 encoding
    Returns:
      Decoded long value
    Throws:
      `NumberFormatException` - if there is a problem with decoding