* Added substream() abstract method to KaitaiStream

* Added implementations for ByteBuffer- (efficient) and RAF-backed
  (naive) concrete KaitaiStreams.
* Started simple set of tests to test this all locally within the
  package.

Author: GreyCat

pom.xml

@@ -143,4 +143,13 @@
       <url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url>
     </repository>
   </distributionManagement>
+
+  <dependencies>
+    <dependency>
+      <groupId>org.testng</groupId>
+      <artifactId>testng</artifactId>
+      <version>RELEASE</version>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
 </project>

src/main/java/io/kaitai/struct/ByteBufferKaitaiStream.java

@@ -361,4 +361,18 @@ public byte[] readBytesTerm(byte term, boolean includeTerm, boolean consumeTerm,
     }
 
     //endregion
+
+    @Override
+    public KaitaiStream substream(long n) {
+        if (n > Integer.MAX_VALUE) {
+            throw new IllegalArgumentException("Java ByteBuffer can't be limited beyond Integer.MAX_VALUE");
+        }
+
+        ByteBuffer newBuffer = bb.slice();
+        newBuffer.limit((int) n);
+
+        bb.position(bb.position() + (int) n);
+
+        return new ByteBufferKaitaiStream(newBuffer);
+    }
 }

src/main/java/io/kaitai/struct/KaitaiStream.java

@@ -434,6 +434,15 @@ public static byte[] processZlib(byte[] data) {
 
     //region Misc runtime operations
 
+    /**
+     * Reserves next `n` bytes from current stream as a KaitaiStream-compatible substream.
+     * Substream has its own pointer and addressing in the range of [0, n) bytes. This
+     * stream's pointer is advanced to the position right after this substream.
+     * @param n number of bytes to reserve for a substream
+     * @return substream covering n bytes from the current position
+     */
+    abstract public KaitaiStream substream(long n);
+
     /**
      * Performs modulo operation between two integers: dividend `a`
      * and divisor `b`. Divisor `b` is expected to be positive. The

src/main/java/io/kaitai/struct/RandomAccessFileKaitaiStream.java

@@ -363,6 +363,21 @@ public byte[] readBytesTerm(byte term, boolean includeTerm, boolean consumeTerm,
         }
     }
 
+    @Override
+    public KaitaiStream substream(long n) {
+        // This implementation mirrors what ksc was doing up to v0.10, and the fallback that
+        // it is still doing in case something non-trivial has to happen with the byte contents.
+        //
+        // Given that RandomAccessFile-based stream is not really efficient anyway, this seems
+        // to be a reasonable fallback without resorting to a special limiting implementation.
+        //
+        // If and when somebody will come up with a reason why substreams have to implemented
+        // for RAF, feel free to contribute relevant implementation with some rationale (e.g. a
+        // benchmark).
+
+        return new ByteBufferKaitaiStream(readBytes(n));
+    }
+
     //region Helper methods
 
     private ByteBuffer wrapBufferLe(int count) {

src/test/java/io/kaitai/struct/ByteBufferKaitaiStreamTest.java

@@ -0,0 +1,15 @@
+package io.kaitai.struct;
+
+import java.nio.BufferUnderflowException;
+
+public class ByteBufferKaitaiStreamTest extends KaitaiStreamTest {
+    @org.testng.annotations.BeforeMethod
+    public void setUp() {
+        stream = new ByteBufferKaitaiStream(new byte[] { '1', '2', '3', '4', '5' });
+    }
+
+    @Override
+    Class getEOFClass() {
+        return BufferUnderflowException.class;
+    }
+}

src/test/java/io/kaitai/struct/KaitaiStreamTest.java

@@ -0,0 +1,92 @@
+package io.kaitai.struct;
+
+import org.testng.annotations.Test;
+
+import java.nio.BufferUnderflowException;
+
+import static org.testng.Assert.*;
+
+public abstract class KaitaiStreamTest {
+    KaitaiStream stream;
+
+    abstract Class getEOFClass();
+
+    @org.testng.annotations.Test
+    public void testReadS1() {
+        short first = stream.readS1();
+        assertEquals(first, 0x31);
+        short second = stream.readS1();
+        assertEquals(second, 0x32);
+    }
+
+    @org.testng.annotations.Test
+    public void testReadS2be() {
+        short first = stream.readS2be();
+        assertEquals(first, 0x3132);
+        short second = stream.readS2be();
+        assertEquals(second, 0x3334);
+
+        assertThrows(getEOFClass(), new ThrowingRunnable() {
+            @Override
+            public void run() throws Throwable {
+                stream.readS2be();
+            }
+        });
+    }
+
+    @org.testng.annotations.Test
+    public void testReadBytes5() {
+        byte[] actual = stream.readBytes(5);
+        assertEquals(actual, new byte[] {'1', '2', '3', '4', '5'});
+    }
+
+    @org.testng.annotations.Test
+    public void testReadBytes6() {
+        assertThrows(getEOFClass(), new ThrowingRunnable() {
+            @Override
+            public void run() throws Throwable {
+                stream.readBytes(6);
+            }
+        });
+    }
+
+    @org.testng.annotations.Test
+    public void testSubstream() {
+        stream.seek(1);
+        assertEquals(stream.pos(), 1);
+
+        final KaitaiStream substream = stream.substream(3);
+
+        assertEquals(substream.pos(), 0);
+        assertEquals(stream.pos(), 4);
+
+        byte byte0Sub = substream.readS1();
+        assertEquals(byte0Sub, '2');
+        assertEquals(substream.pos(), 1);
+        assertEquals(stream.pos(), 4);
+
+        byte byte1Sub = substream.readS1();
+        assertEquals(byte1Sub, '3');
+        assertEquals(substream.pos(), 2);
+        assertEquals(stream.pos(), 4);
+
+        byte byte4Main = stream.readS1();
+        assertEquals(byte4Main, '5');
+        assertEquals(substream.pos(), 2);
+        assertEquals(stream.pos(), 5);
+
+        byte byte2Sub = substream.readS1();
+        assertEquals(byte2Sub, '4');
+        assertEquals(substream.pos(), 3);
+        assertEquals(stream.pos(), 5);
+
+        assertThrows(getEOFClass(), new ThrowingRunnable() {
+            @Override
+            public void run() throws Throwable {
+                substream.readS1();
+            }
+        });
+
+        assertTrue(substream.isEof());
+    }
+}

src/test/java/io/kaitai/struct/RandomAccessFileKaitaiStreamTest.java

@@ -0,0 +1,32 @@
+package io.kaitai.struct;
+
+import java.io.EOFException;
+import java.io.File;
+import java.io.FileWriter;
+import java.io.IOException;
+import java.nio.BufferUnderflowException;
+
+import static org.testng.Assert.*;
+
+public class RandomAccessFileKaitaiStreamTest extends KaitaiStreamTest {
+    static String TEST_SCRATCH_DIR = "target/test-scratch";
+
+    @org.testng.annotations.BeforeMethod
+    public void setUp() throws IOException {
+        File testScratchDir = new File(TEST_SCRATCH_DIR);
+        if (!testScratchDir.exists()) testScratchDir.mkdirs();
+
+        String testFileName = testScratchDir + "/12345.bin";
+
+        FileWriter writer = new FileWriter(testFileName);
+        writer.write("12345");
+        writer.close();
+
+        stream = new RandomAccessFileKaitaiStream(testFileName);
+    }
+
+    @Override
+    Class getEOFClass() {
+        return RuntimeException.class;
+    }
+}