[IO-855] Clarify PeekableInputStream.peek() behavior (#856)

Add tests for exact-match and non-consuming behavior.

Co-authored-by: Sarankumar Baskar <sbaskar@redhat.com>

Author: sarankumarbaskar

src/main/java/org/apache/commons/io/input/buffer/PeekableInputStream.java

@@ -50,11 +50,13 @@ public PeekableInputStream(final InputStream inputStream, final int bufferSize)
     }
 
     /**
-     * Returns whether the next bytes in the buffer are as given by {@code sourceBuffer}. This is equivalent to
-     * {@link #peek(byte[], int, int)} with {@code offset} == 0, and {@code length} == {@code sourceBuffer.length}
+     * Returns whether the next bytes in the buffer exactly match {@code sourceBuffer}. This is equivalent to
+     * {@link #peek(byte[], int, int)} with {@code offset} == 0, and {@code length} == {@code sourceBuffer.length}.
+     * This method does not perform a prefix or starts-with check; for example, peeking {@code "Some"} against a stream
+     * containing {@code "Some text buffer"} returns {@code false}. This method does not consume bytes from the stream.
      *
      * @param sourceBuffer the buffer to compare against.
-     * @return true if the next bytes are as given.
+     * @return true if the next bytes exactly match {@code sourceBuffer}.
      * @throws IOException Refilling the buffer failed.
      */
     public boolean peek(final byte[] sourceBuffer) throws IOException {
@@ -63,13 +65,13 @@ public boolean peek(final byte[] sourceBuffer) throws IOException {
     }
 
     /**
-     * Returns whether the next bytes in the buffer are as given by {@code sourceBuffer}, {code offset}, and
-     * {@code length}.
+     * Returns whether the next bytes in the buffer exactly match {@code length} bytes from {@code sourceBuffer}, starting at
+     * {@code offset}. This method does not consume bytes from the stream.
      *
      * @param sourceBuffer the buffer to compare against.
-     * @param offset the start offset.
+     * @param offset the start offset in {@code sourceBuffer}.
      * @param length the length to compare.
-     * @return true if the next bytes in the buffer are as given.
+     * @return true if the next bytes exactly match the requested range from {@code sourceBuffer}.
      * @throws IOException if there is a problem calling fillBuffer().
      */
     public boolean peek(final byte[] sourceBuffer, final int offset, final int length) throws IOException {

src/test/java/org/apache/commons/io/input/buffer/PeekableInputStreamTest.java

@@ -17,13 +17,15 @@
 
 package org.apache.commons.io.input.buffer;
 
+import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNotEquals;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.junit.jupiter.api.Assertions.fail;
 
 import java.io.ByteArrayInputStream;
 import java.io.IOException;
+import java.nio.charset.StandardCharsets;
 import java.util.Random;
 
 import org.junit.jupiter.api.Test;
@@ -100,4 +102,29 @@ void testRandomRead() throws Exception {
         }
         assertTrue(true, "Test finished OK");
     }
+
+    @Test
+    void testPeekExactMatch() throws IOException {
+        final byte[] input = "Some text buffer".getBytes(StandardCharsets.UTF_8);
+        try (PeekableInputStream inputStream = new PeekableInputStream(new ByteArrayInputStream(input))) {
+            assertTrue(inputStream.peek(input));
+        }
+    }
+
+    @Test
+    void testPeekPrefixDoesNotMatchLongerInput() throws IOException {
+        try (PeekableInputStream inputStream = new PeekableInputStream(
+                new ByteArrayInputStream("Some text buffer".getBytes(StandardCharsets.UTF_8)))) {
+            assertFalse(inputStream.peek("Some".getBytes(StandardCharsets.UTF_8)));
+        }
+    }
+
+    @Test
+    void testPeekDoesNotConsumeBytes() throws IOException {
+        final byte[] input = "Some".getBytes(StandardCharsets.UTF_8);
+        try (PeekableInputStream inputStream = new PeekableInputStream(new ByteArrayInputStream(input))) {
+            assertTrue(inputStream.peek(input));
+            assertEquals('S', inputStream.read());
+        }
+    }
 }