Add peek() method to ExtractorInput

PiperOrigin-RevId: 284537150

library/core/src/main/java/com/google/android/exoplayer2/extractor/DefaultExtractorInput.java

@@ -58,7 +58,9 @@ public final class DefaultExtractorInput implements ExtractorInput {
   public int read(byte[] target, int offset, int length) throws IOException, InterruptedException {
     int bytesRead = readFromPeekBuffer(target, offset, length);
     if (bytesRead == 0) {
-      bytesRead = readFromDataSource(target, offset, length, 0, true);
+      bytesRead =
+          readFromDataSource(
+              target, offset, length, /* bytesAlreadyRead= */ 0, /* allowEndOfInput= */ true);
     }
     commitBytesRead(bytesRead);
     return bytesRead;
@@ -111,6 +113,31 @@ public final class DefaultExtractorInput implements ExtractorInput {
   }
 
   @Override
+  public int peek(byte[] target, int offset, int length) throws IOException, InterruptedException {
+    ensureSpaceForPeek(length);
+    int peekBufferRemainingBytes = peekBufferLength - peekBufferPosition;
+    int bytesPeeked;
+    if (peekBufferRemainingBytes == 0) {
+      bytesPeeked =
+          readFromDataSource(
+              peekBuffer,
+              peekBufferPosition,
+              length,
+              /* bytesAlreadyRead= */ 0,
+              /* allowEndOfInput= */ true);
+      if (bytesPeeked == C.RESULT_END_OF_INPUT) {
+        return C.RESULT_END_OF_INPUT;
+      }
+      peekBufferLength += bytesPeeked;
+    } else {
+      bytesPeeked = Math.min(length, peekBufferRemainingBytes);
+    }
+    System.arraycopy(peekBuffer, peekBufferPosition, target, offset, bytesPeeked);
+    peekBufferPosition += bytesPeeked;
+    return bytesPeeked;
+  }
+
+  @Override
   public boolean peekFully(byte[] target, int offset, int length, boolean allowEndOfInput)
       throws IOException, InterruptedException {
     if (!advancePeekPosition(length, allowEndOfInput)) {
@@ -201,7 +228,7 @@ public final class DefaultExtractorInput implements ExtractorInput {
   }
 
   /**
-   * Reads from the peek buffer
+   * Reads from the peek buffer.
    *
    * @param target A target array into which data should be written.
    * @param offset The offset into the target array at which to write.

library/core/src/main/java/com/google/android/exoplayer2/extractor/ExtractorInput.java

@@ -27,19 +27,19 @@ import java.io.InputStream;
  * for more info about each mode.
  *
  * <ul>
- *   <li>The {@code read()} and {@code skip()} methods provide {@link InputStream}-like byte-level
- *       access operations.
+ *   <li>The {@code read()/peek()} and {@code skip()} methods provide {@link InputStream}-like
+ *       byte-level access operations.
  *   <li>The {@code read/skip/peekFully()} and {@code advancePeekPosition()} methods assume the user
  *       wants to read an entire block/frame/header of known length.
  * </ul>
  *
  * <h3>{@link InputStream}-like methods</h3>
  *
- * <p>The {@code read()} and {@code skip()} methods provide {@link InputStream}-like byte-level
- * access operations. The {@code length} parameter is a maximum, and each method returns the number
- * of bytes actually processed. This may be less than {@code length} because the end of the input
- * was reached, or the method was interrupted, or the operation was aborted early for another
- * reason.
+ * <p>The {@code read()/peek()} and {@code skip()} methods provide {@link InputStream}-like
+ * byte-level access operations. The {@code length} parameter is a maximum, and each method returns
+ * the number of bytes actually processed. This may be less than {@code length} because the end of
+ * the input was reached, or the method was interrupted, or the operation was aborted early for
+ * another reason.
  *
  * <h3>Block-based methods</h3>
  *
@@ -102,7 +102,8 @@ public interface ExtractorInput {
       throws IOException, InterruptedException;
 
   /**
-   * Equivalent to {@code readFully(target, offset, length, false)}.
+   * Equivalent to {@link #readFully(byte[], int, int, boolean) readFully(target, offset, length,
+   * false)}.
    *
    * @param target A target array into which data should be written.
    * @param offset The offset into the target array at which to write.
@@ -155,8 +156,11 @@ public interface ExtractorInput {
   void skipFully(int length) throws IOException, InterruptedException;
 
   /**
-   * Peeks {@code length} bytes from the peek position, writing them into {@code target} at index
-   * {@code offset}. The current read position is left unchanged.
+   * Peeks up to {@code length} bytes from the peek position. The current read position is left
+   * unchanged.
+   *
+   * <p>This method blocks until at least one byte of data can be peeked, the end of the input is
+   * detected, or an exception is thrown.
    *
    * <p>Calling {@link #resetPeekPosition()} resets the peek position to equal the current read
    * position, so the caller can peek the same data again. Reading or skipping also resets the peek
@@ -164,6 +168,18 @@ public interface ExtractorInput {
    *
    * @param target A target array into which data should be written.
    * @param offset The offset into the target array at which to write.
+   * @param length The maximum number of bytes to peek from the input.
+   * @return The number of bytes peeked, or {@link C#RESULT_END_OF_INPUT} if the input has ended.
+   * @throws IOException If an error occurs peeking from the input.
+   * @throws InterruptedException If the thread has been interrupted.
+   */
+  int peek(byte[] target, int offset, int length) throws IOException, InterruptedException;
+
+  /**
+   * Like {@link #peek(byte[], int, int)}, but peeks the requested {@code length} in full.
+   *
+   * @param target A target array into which data should be written.
+   * @param offset The offset into the target array at which to write.
    * @param length The number of bytes to peek from the input.
    * @param allowEndOfInput True if encountering the end of the input having peeked no data is
    *     allowed, and should result in {@code false} being returned. False if it should be
@@ -181,12 +197,8 @@ public interface ExtractorInput {
       throws IOException, InterruptedException;
 
   /**
-   * Peeks {@code length} bytes from the peek position, writing them into {@code target} at index
-   * {@code offset}. The current read position is left unchanged.
-   * <p>
-   * Calling {@link #resetPeekPosition()} resets the peek position to equal the current read
-   * position, so the caller can peek the same data again. Reading and skipping also reset the peek
-   * position.
+   * Equivalent to {@link #peekFully(byte[], int, int, boolean) peekFully(target, offset, length,
+   * false)}.
    *
    * @param target A target array into which data should be written.
    * @param offset The offset into the target array at which to write.

testutils/src/main/java/com/google/android/exoplayer2/testutil/FakeExtractorInput.java

@@ -65,7 +65,8 @@ public final class FakeExtractorInput implements ExtractorInput {
   private int readPosition;
   private int peekPosition;
 
-  private final SparseBooleanArray partiallySatisfiedTargetPositions;
+  private final SparseBooleanArray partiallySatisfiedTargetReadPositions;
+  private final SparseBooleanArray partiallySatisfiedTargetPeekPositions;
   private final SparseBooleanArray failedReadPositions;
   private final SparseBooleanArray failedPeekPositions;
 
@@ -75,7 +76,8 @@ public final class FakeExtractorInput implements ExtractorInput {
     this.simulateUnknownLength = simulateUnknownLength;
     this.simulatePartialReads = simulatePartialReads;
     this.simulateIOErrors = simulateIOErrors;
-    partiallySatisfiedTargetPositions = new SparseBooleanArray();
+    partiallySatisfiedTargetReadPositions = new SparseBooleanArray();
+    partiallySatisfiedTargetPeekPositions = new SparseBooleanArray();
     failedReadPositions = new SparseBooleanArray();
     failedPeekPositions = new SparseBooleanArray();
   }
@@ -84,7 +86,8 @@ public final class FakeExtractorInput implements ExtractorInput {
   public void reset() {
     readPosition = 0;
     peekPosition = 0;
-    partiallySatisfiedTargetPositions.clear();
+    partiallySatisfiedTargetReadPositions.clear();
+    partiallySatisfiedTargetPeekPositions.clear();
     failedReadPositions.clear();
     failedPeekPositions.clear();
   }
@@ -104,7 +107,7 @@ public final class FakeExtractorInput implements ExtractorInput {
   @Override
   public int read(byte[] target, int offset, int length) throws IOException {
     checkIOException(readPosition, failedReadPositions);
-    length = getReadLength(length);
+    length = getLengthToRead(readPosition, length, partiallySatisfiedTargetReadPositions);
     return readFullyInternal(target, offset, length, true) ? length : C.RESULT_END_OF_INPUT;
   }
 
@@ -123,7 +126,7 @@ public final class FakeExtractorInput implements ExtractorInput {
   @Override
   public int skip(int length) throws IOException {
     checkIOException(readPosition, failedReadPositions);
-    length = getReadLength(length);
+    length = getLengthToRead(readPosition, length, partiallySatisfiedTargetReadPositions);
     return skipFullyInternal(length, true) ? length : C.RESULT_END_OF_INPUT;
   }
 
@@ -139,15 +142,17 @@ public final class FakeExtractorInput implements ExtractorInput {
   }
 
   @Override
+  public int peek(byte[] target, int offset, int length) throws IOException {
+    checkIOException(peekPosition, failedPeekPositions);
+    length = getLengthToRead(peekPosition, length, partiallySatisfiedTargetPeekPositions);
+    return peekFullyInternal(target, offset, length, true) ? length : C.RESULT_END_OF_INPUT;
+  }
+
+  @Override
   public boolean peekFully(byte[] target, int offset, int length, boolean allowEndOfInput)
       throws IOException {
     checkIOException(peekPosition, failedPeekPositions);
-    if (!checkXFully(allowEndOfInput, peekPosition, length)) {
-      return false;
-    }
-    System.arraycopy(data, peekPosition, target, offset, length);
-    peekPosition += length;
-    return true;
+    return peekFullyInternal(target, offset, length, allowEndOfInput);
   }
 
   @Override
@@ -221,18 +226,19 @@ public final class FakeExtractorInput implements ExtractorInput {
     return true;
   }
 
-  private int getReadLength(int requestedLength) {
-    if (readPosition == data.length) {
+  private int getLengthToRead(
+      int position, int requestedLength, SparseBooleanArray partiallySatisfiedTargetPositions) {
+    if (position == data.length) {
       // If the requested length is non-zero, the end of the input will be read.
       return requestedLength == 0 ? 0 : Integer.MAX_VALUE;
     }
-    int targetPosition = readPosition + requestedLength;
+    int targetPosition = position + requestedLength;
     if (simulatePartialReads && requestedLength > 1
         && !partiallySatisfiedTargetPositions.get(targetPosition)) {
       partiallySatisfiedTargetPositions.put(targetPosition, true);
       return 1;
     }
-    return Math.min(requestedLength, data.length - readPosition);
+    return Math.min(requestedLength, data.length - position);
   }
 
   private boolean readFullyInternal(byte[] target, int offset, int length, boolean allowEndOfInput)
@@ -255,6 +261,16 @@ public final class FakeExtractorInput implements ExtractorInput {
     return true;
   }
 
+  private boolean peekFullyInternal(byte[] target, int offset, int length, boolean allowEndOfInput)
+      throws EOFException {
+    if (!checkXFully(allowEndOfInput, peekPosition, length)) {
+      return false;
+    }
+    System.arraycopy(data, peekPosition, target, offset, length);
+    peekPosition += length;
+    return true;
+  }
+
   /**
    * Builder of {@link FakeExtractorInput} instances.
    */