public final class

ParsableBitArray

extends java.lang.Object

 java.lang.Object

↳androidx.media3.common.util.ParsableBitArray

Gradle dependencies

compile group: 'androidx.media3', name: 'media3-common', version: '1.0.0-alpha03'

  • groupId: androidx.media3
  • artifactId: media3-common
  • version: 1.0.0-alpha03

Artifact androidx.media3:media3-common:1.0.0-alpha03 it located at Google repository (https://maven.google.com/)

Overview

Wraps a byte array, providing methods that allow it to be read as a bitstream.

Summary

Fields
public byte[]data

Constructors
publicParsableBitArray()

Creates a new instance that initially has no backing data.

publicParsableBitArray(byte[] data[])

Creates a new instance that wraps an existing array.

publicParsableBitArray(byte[] data[], int limit)

Creates a new instance that wraps an existing array.

Methods
public intbitsLeft()

Returns the number of bits yet to be read.

public voidbyteAlign()

Aligns the position to the next byte boundary.

public intgetBytePosition()

Returns the current byte offset.

public intgetPosition()

Returns the current bit offset.

public voidputInt(int value, int numBits)

Overwrites numBits from this array using the numBits least significant bits from value.

public booleanreadBit()

Reads a single bit.

public voidreadBits(byte[] buffer[], int offset, int numBits)

Reads numBits bits into buffer.

public intreadBits(int numBits)

Reads up to 32 bits.

public longreadBitsToLong(int numBits)

Reads up to 64 bits.

public voidreadBytes(byte[] buffer[], int offset, int length)

Reads the next length bytes into buffer.

public java.lang.StringreadBytesAsString(int length)

Reads the next length bytes as a UTF-8 string.

public java.lang.StringreadBytesAsString(int length, java.nio.charset.Charset charset)

Reads the next length bytes as a string encoded in java.nio.charset.Charset.

public voidreset(byte[] data[])

Updates the instance to wrap data, and resets the position to zero.

public voidreset(byte[] data[], int limit)

Updates the instance to wrap data, and resets the position to zero.

public voidreset(ParsableByteArray parsableByteArray)

Sets this instance's data, position and limit to match the provided parsableByteArray.

public voidsetPosition(int position)

Sets the current bit offset.

public voidskipBit()

Skips a single bit.

public voidskipBits(int numBits)

Skips bits and moves current reading position forward.

public voidskipBytes(int length)

Skips the next length bytes.

from java.lang.Objectclone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Fields

public byte[] data

Constructors

public ParsableBitArray()

Creates a new instance that initially has no backing data.

public ParsableBitArray(byte[] data[])

Creates a new instance that wraps an existing array.

Parameters:

data: The data to wrap.

public ParsableBitArray(byte[] data[], int limit)

Creates a new instance that wraps an existing array.

Parameters:

data: The data to wrap.
limit: The limit in bytes.

Methods

public void reset(byte[] data[])

Updates the instance to wrap data, and resets the position to zero.

Parameters:

data: The array to wrap.

public void reset(ParsableByteArray parsableByteArray)

Sets this instance's data, position and limit to match the provided parsableByteArray. Any modifications to the underlying data array will be visible in both instances

Parameters:

parsableByteArray: The ParsableByteArray.

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 in bytes.

public int bitsLeft()

Returns the number of bits yet to be read.

public int getPosition()

Returns the current bit offset.

public int getBytePosition()

Returns the current byte offset. Must only be called when the position is byte aligned.

public void setPosition(int position)

Sets the current bit offset.

Parameters:

position: The position to set.

public void skipBit()

Skips a single bit.

public void skipBits(int numBits)

Skips bits and moves current reading position forward.

Parameters:

numBits: The number of bits to skip.

public boolean readBit()

Reads a single bit.

Returns:

Whether the bit is set.

public int readBits(int numBits)

Reads up to 32 bits.

Parameters:

numBits: The number of bits to read.

Returns:

An integer whose bottom numBits bits hold the read data.

public long readBitsToLong(int numBits)

Reads up to 64 bits.

Parameters:

numBits: The number of bits to read.

Returns:

A long whose bottom numBits bits hold the read data.

public void readBits(byte[] buffer[], int offset, int numBits)

Reads numBits bits into buffer.

Parameters:

buffer: The array into which the read data should be written. The trailing numBits % 8 bits are written into the most significant bits of the last modified buffer byte. The remaining ones are unmodified.
offset: The offset in buffer at which the read data should be written.
numBits: The number of bits to read.

public void byteAlign()

Aligns the position to the next byte boundary. Does nothing if the position is already aligned.

public void readBytes(byte[] buffer[], int offset, int length)

Reads the next length bytes into buffer. Must only be called when the position is byte aligned.

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

public void skipBytes(int length)

Skips the next length bytes. Must only be called when the position is byte aligned.

Parameters:

length: The number of bytes to read.

public java.lang.String readBytesAsString(int length)

Reads the next length bytes as a UTF-8 string. Must only be called when the position is byte aligned.

Parameters:

length: The number of bytes to read.

Returns:

The string encoded by the bytes in UTF-8.

public java.lang.String readBytesAsString(int length, java.nio.charset.Charset charset)

Reads the next length bytes as a string encoded in java.nio.charset.Charset. Must only be called when the position is byte aligned.

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.

public void putInt(int value, int numBits)

Overwrites numBits from this array using the numBits least significant bits from value. Bits are written in order from most significant to least significant. The read position is advanced by numBits.

Parameters:

value: The integer whose numBits least significant bits are written into ParsableBitArray.data.
numBits: The number of bits to write.

Source

/*
 * Copyright (C) 2016 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package androidx.media3.common.util;

import static java.lang.Math.min;

import com.google.common.base.Charsets;
import java.nio.charset.Charset;

/** Wraps a byte array, providing methods that allow it to be read as a bitstream. */
@UnstableApi
public final class ParsableBitArray {

  public byte[] data;

  // The offset within the data, stored as the current byte offset, and the bit offset within that
  // byte (from 0 to 7).
  private int byteOffset;
  private int bitOffset;
  private int byteLimit;

  /** Creates a new instance that initially has no backing data. */
  public ParsableBitArray() {
    data = Util.EMPTY_BYTE_ARRAY;
  }

  /**
   * Creates a new instance that wraps an existing array.
   *
   * @param data The data to wrap.
   */
  public ParsableBitArray(byte[] data) {
    this(data, data.length);
  }

  /**
   * Creates a new instance that wraps an existing array.
   *
   * @param data The data to wrap.
   * @param limit The limit in bytes.
   */
  public ParsableBitArray(byte[] data, int limit) {
    this.data = data;
    byteLimit = limit;
  }

  /**
   * Updates the instance to wrap {@code data}, and resets the position to zero.
   *
   * @param data The array to wrap.
   */
  public void reset(byte[] data) {
    reset(data, data.length);
  }

  /**
   * Sets this instance's data, position and limit to match the provided {@code parsableByteArray}.
   * Any modifications to the underlying data array will be visible in both instances
   *
   * @param parsableByteArray The {@link ParsableByteArray}.
   */
  public void reset(ParsableByteArray parsableByteArray) {
    reset(parsableByteArray.getData(), parsableByteArray.limit());
    setPosition(parsableByteArray.getPosition() * 8);
  }

  /**
   * Updates the instance to wrap {@code data}, and resets the position to zero.
   *
   * @param data The array to wrap.
   * @param limit The limit in bytes.
   */
  public void reset(byte[] data, int limit) {
    this.data = data;
    byteOffset = 0;
    bitOffset = 0;
    byteLimit = limit;
  }

  /** Returns the number of bits yet to be read. */
  public int bitsLeft() {
    return (byteLimit - byteOffset) * 8 - bitOffset;
  }

  /** Returns the current bit offset. */
  public int getPosition() {
    return byteOffset * 8 + bitOffset;
  }

  /**
   * Returns the current byte offset. Must only be called when the position is byte aligned.
   *
   * @throws IllegalStateException If the position isn't byte aligned.
   */
  public int getBytePosition() {
    Assertions.checkState(bitOffset == 0);
    return byteOffset;
  }

  /**
   * Sets the current bit offset.
   *
   * @param position The position to set.
   */
  public void setPosition(int position) {
    byteOffset = position / 8;
    bitOffset = position - (byteOffset * 8);
    assertValidOffset();
  }

  /** Skips a single bit. */
  public void skipBit() {
    if (++bitOffset == 8) {
      bitOffset = 0;
      byteOffset++;
    }
    assertValidOffset();
  }

  /**
   * Skips bits and moves current reading position forward.
   *
   * @param numBits The number of bits to skip.
   */
  public void skipBits(int numBits) {
    int numBytes = numBits / 8;
    byteOffset += numBytes;
    bitOffset += numBits - (numBytes * 8);
    if (bitOffset > 7) {
      byteOffset++;
      bitOffset -= 8;
    }
    assertValidOffset();
  }

  /**
   * Reads a single bit.
   *
   * @return Whether the bit is set.
   */
  public boolean readBit() {
    boolean returnValue = (data[byteOffset] & (0x80 >> bitOffset)) != 0;
    skipBit();
    return returnValue;
  }

  /**
   * Reads up to 32 bits.
   *
   * @param numBits The number of bits to read.
   * @return An integer whose bottom {@code numBits} bits hold the read data.
   */
  public int readBits(int numBits) {
    if (numBits == 0) {
      return 0;
    }
    int returnValue = 0;
    bitOffset += numBits;
    while (bitOffset > 8) {
      bitOffset -= 8;
      returnValue |= (data[byteOffset++] & 0xFF) << bitOffset;
    }
    returnValue |= (data[byteOffset] & 0xFF) >> (8 - bitOffset);
    returnValue &= 0xFFFFFFFF >>> (32 - numBits);
    if (bitOffset == 8) {
      bitOffset = 0;
      byteOffset++;
    }
    assertValidOffset();
    return returnValue;
  }

  /**
   * Reads up to 64 bits.
   *
   * @param numBits The number of bits to read.
   * @return A long whose bottom {@code numBits} bits hold the read data.
   */
  public long readBitsToLong(int numBits) {
    if (numBits <= 32) {
      return Util.toUnsignedLong(readBits(numBits));
    }
    return Util.toLong(readBits(numBits - 32), readBits(32));
  }

  /**
   * Reads {@code numBits} bits into {@code buffer}.
   *
   * @param buffer The array into which the read data should be written. The trailing {@code numBits
   *     % 8} bits are written into the most significant bits of the last modified {@code buffer}
   *     byte. The remaining ones are unmodified.
   * @param offset The offset in {@code buffer} at which the read data should be written.
   * @param numBits The number of bits to read.
   */
  public void readBits(byte[] buffer, int offset, int numBits) {
    // Whole bytes.
    int to = offset + (numBits >> 3) /* numBits / 8 */;
    for (int i = offset; i < to; i++) {
      buffer[i] = (byte) (data[byteOffset++] << bitOffset);
      buffer[i] = (byte) (buffer[i] | ((data[byteOffset] & 0xFF) >> (8 - bitOffset)));
    }
    // Trailing bits.
    int bitsLeft = numBits & 7 /* numBits % 8 */;
    if (bitsLeft == 0) {
      return;
    }
    // Set bits that are going to be overwritten to 0.
    buffer[to] = (byte) (buffer[to] & (0xFF >> bitsLeft));
    if (bitOffset + bitsLeft > 8) {
      // We read the rest of data[byteOffset] and increase byteOffset.
      buffer[to] = (byte) (buffer[to] | ((data[byteOffset++] & 0xFF) << bitOffset));
      bitOffset -= 8;
    }
    bitOffset += bitsLeft;
    int lastDataByteTrailingBits = (data[byteOffset] & 0xFF) >> (8 - bitOffset);
    buffer[to] |= (byte) (lastDataByteTrailingBits << (8 - bitsLeft));
    if (bitOffset == 8) {
      bitOffset = 0;
      byteOffset++;
    }
    assertValidOffset();
  }

  /**
   * Aligns the position to the next byte boundary. Does nothing if the position is already aligned.
   */
  public void byteAlign() {
    if (bitOffset == 0) {
      return;
    }
    bitOffset = 0;
    byteOffset++;
    assertValidOffset();
  }

  /**
   * Reads the next {@code length} bytes into {@code buffer}. Must only be called when the position
   * is byte aligned.
   *
   * @see System#arraycopy(Object, int, Object, int, int)
   * @param buffer The array into which the read data should be written.
   * @param offset The offset in {@code buffer} at which the read data should be written.
   * @param length The number of bytes to read.
   * @throws IllegalStateException If the position isn't byte aligned.
   */
  public void readBytes(byte[] buffer, int offset, int length) {
    Assertions.checkState(bitOffset == 0);
    System.arraycopy(data, byteOffset, buffer, offset, length);
    byteOffset += length;
    assertValidOffset();
  }

  /**
   * Skips the next {@code length} bytes. Must only be called when the position is byte aligned.
   *
   * @param length The number of bytes to read.
   * @throws IllegalStateException If the position isn't byte aligned.
   */
  public void skipBytes(int length) {
    Assertions.checkState(bitOffset == 0);
    byteOffset += length;
    assertValidOffset();
  }

  /**
   * Reads the next {@code length} bytes as a UTF-8 string. Must only be called when the position is
   * byte aligned.
   *
   * @param length The number of bytes to read.
   * @return The string encoded by the bytes in UTF-8.
   */
  public String readBytesAsString(int length) {
    return readBytesAsString(length, Charsets.UTF_8);
  }

  /**
   * Reads the next {@code length} bytes as a string encoded in {@link Charset}. Must only be called
   * when the position is byte aligned.
   *
   * @param length The number of bytes to read.
   * @param charset The character set of the encoded characters.
   * @return The string encoded by the bytes in the specified character set.
   */
  public String readBytesAsString(int length, Charset charset) {
    byte[] bytes = new byte[length];
    readBytes(bytes, 0, length);
    return new String(bytes, charset);
  }

  /**
   * Overwrites {@code numBits} from this array using the {@code numBits} least significant bits
   * from {@code value}. Bits are written in order from most significant to least significant. The
   * read position is advanced by {@code numBits}.
   *
   * @param value The integer whose {@code numBits} least significant bits are written into {@link
   *     #data}.
   * @param numBits The number of bits to write.
   */
  public void putInt(int value, int numBits) {
    int remainingBitsToRead = numBits;
    if (numBits < 32) {
      value &= (1 << numBits) - 1;
    }
    int firstByteReadSize = min(8 - bitOffset, numBits);
    int firstByteRightPaddingSize = 8 - bitOffset - firstByteReadSize;
    int firstByteBitmask = (0xFF00 >> bitOffset) | ((1 << firstByteRightPaddingSize) - 1);
    data[byteOffset] = (byte) (data[byteOffset] & firstByteBitmask);
    int firstByteInputBits = value >>> (numBits - firstByteReadSize);
    data[byteOffset] =
        (byte) (data[byteOffset] | (firstByteInputBits << firstByteRightPaddingSize));
    remainingBitsToRead -= firstByteReadSize;
    int currentByteIndex = byteOffset + 1;
    while (remainingBitsToRead > 8) {
      data[currentByteIndex++] = (byte) (value >>> (remainingBitsToRead - 8));
      remainingBitsToRead -= 8;
    }
    int lastByteRightPaddingSize = 8 - remainingBitsToRead;
    data[currentByteIndex] =
        (byte) (data[currentByteIndex] & ((1 << lastByteRightPaddingSize) - 1));
    int lastByteInput = value & ((1 << remainingBitsToRead) - 1);
    data[currentByteIndex] =
        (byte) (data[currentByteIndex] | (lastByteInput << lastByteRightPaddingSize));
    skipBits(numBits);
    assertValidOffset();
  }

  private void assertValidOffset() {
    // It is fine for position to be at the end of the array, but no further.
    Assertions.checkState(
        byteOffset >= 0 && (byteOffset < byteLimit || (byteOffset == byteLimit && bitOffset == 0)));
  }
}