Package com.google.android.exoplayer2.util

## Class ParsableByteArray

- java.lang.Object
- - com.google.android.exoplayer2.util.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.

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

    All Methods Instance Methods Concrete Methods
    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.
    `void` | `ensureCapacity​(int requiredCapacity)` | Ensures the backing array is at least `requiredCapacity` long.
    `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`.
    `String` | `readDelimiterTerminatedString​(char delimiter)` | Reads up to the next delimiter byte (or the limit) as UTF-8 characters.
    `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 in UTF-8.
    `String` | `readLine​(Charset charset)` | Reads a line of text in `charset`.
    `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
    `Charset` | `readUtfCharsetFromBom()` | Reads a UTF byte order mark (BOM) and returns the UTF `Charset` it represents.
    `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`

- - ### Constructor Detail

    - #### 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 Detail

    - #### reset

          public void reset​(int limit)

      Resets the position to zero and the limit to the specified value. This might replace or wipe the `underlying array`, potentially invalidating any local references.
      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.

    - #### ensureCapacity

          public void ensureCapacity​(int requiredCapacity)

      Ensures the backing array is at least `requiredCapacity` long.

      `position`, `limit`, and all data in the underlying array (including that beyond `limit()`) are preserved.

      This might replace or wipe the `underlying array`, potentially invalidating any local references.

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

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

    - #### 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(int)` or `ensureCapacity(int)` are called (because the array might get reallocated).

    - #### capacity

          public int capacity()

      Returns the capacity of the array, which may be larger than the limit.

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

    - #### readDelimiterTerminatedString

          @Nullable
          public String readDelimiterTerminatedString​(char delimiter)

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

    - #### readLine

          @Nullable
          public String readLine()

      Reads a line of text in UTF-8.

      Equivalent to passing `Charsets.UTF_8` to `readLine(Charset)`.

    - #### readLine

          @Nullable
          public String readLine​(Charset charset)

      Reads a line of text in `charset`.

      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'). This method discards leading UTF byte order marks (BOM), if present.

      The position is advanced to start of the next line (i.e. any line terminators are skipped).

      Parameters:
        `charset` - The charset used to interpret the bytes as a `String`.
      Returns:
        The line not including any line-termination characters, or null if the end of the data has already been reached.
      Throws:
        `IllegalArgumentException` - if charset is not supported. Only US_ASCII, UTF-8, UTF-16, UTF-16BE, and UTF-16LE are supported.

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

    - #### readUtfCharsetFromBom

          @Nullable
          public Charset readUtfCharsetFromBom()

      Reads a UTF byte order mark (BOM) and returns the UTF `Charset` it represents. Returns `null` without advancing `position` if no BOM is found.