Add RandomAccessFileInputStream.copy(long, long, OutputStream)

Author: garydgregory

src/changes/changes.xml

@@ -60,6 +60,7 @@ The <action> type attribute can be add,update,fix,remove.
       <action dev="ggregory" type="add"                due-to="Gary Gregory">Add RandomAccessFileOutputStream.getRandomAccessFile().</action>
       <action dev="ggregory" type="add"                due-to="Gary Gregory">Add ProxyInputStream.setReference(InputStream), was package-private setIn(InputStream).</action>
       <action dev="ggregory" type="add"                due-to="Gary Gregory">Add ProxyOutputStream.setReference(OutputStream).</action>
+      <action dev="ggregory" type="add"                due-to="Gary Gregory">Add RandomAccessFileInputStream.copy(long, long, OutputStream).</action>
       <!-- UPDATE -->
       <action dev="ggregory" type="update"             due-to="Dependabot, Gary Gregory">Bump commons.bytebuddy.version from 1.15.10 to 1.15.11 #710.</action>
     </release>

src/main/java/org/apache/commons/io/input/RandomAccessFileInputStream.java

@@ -19,9 +19,11 @@
 
 import java.io.File;
 import java.io.IOException;
+import java.io.OutputStream;
 import java.io.RandomAccessFile;
 import java.util.Objects;
 
+import org.apache.commons.io.IOUtils;
 import org.apache.commons.io.build.AbstractOrigin;
 import org.apache.commons.io.build.AbstractStreamBuilder;
 
@@ -188,6 +190,21 @@ public void close() throws IOException {
         }
     }
 
+    /**
+     * Copies our bytes from the given starting position for a size to the output stream.
+     *
+     * @param pos  Where to start copying. The offset position, measured in bytes from the beginning of the file, at which to set the file pointer.
+     * @param size The number of bytes to copy.
+     * @param os   Where to copy.
+     * @return The number of bytes copied..
+     * @throws IOException if {@code pos} is less than {@code 0} or if an I/O error occurs.
+     * @since 2.19.0
+     */
+    public long copy(final long pos, final long size, final OutputStream os) throws IOException {
+        randomAccessFile.seek(pos);
+        return IOUtils.copyLarge(this, os, 0, size);
+    }
+
     /**
      * Gets the underlying file.
      *

src/test/java/org/apache/commons/io/input/RandomAccessFileInputStreamTest.java

@@ -34,6 +34,7 @@
 import java.nio.file.StandardOpenOption;
 
 import org.apache.commons.io.RandomAccessFileMode;
+import org.apache.commons.io.output.ByteArrayOutputStream;
 import org.junit.jupiter.api.Test;
 
 /**
@@ -150,6 +151,37 @@ public void testConstructorCloseOnCloseFalse() throws IOException {
         }
     }
 
+    @Test
+    public void testCopy() throws IOException {
+        // @formatter:off
+        try (RandomAccessFileInputStream inputStream = RandomAccessFileInputStream.builder()
+                .setRandomAccessFile(createRandomAccessFile())
+                .setCloseOnClose(true)
+                .get()) {
+            // @formatter:on
+            // A Test Line.
+            try (ByteArrayOutputStream baos = new ByteArrayOutputStream()) {
+                // 0 and 12
+                assertEquals(12, inputStream.copy(0, 12, baos));
+                assertArrayEquals("A Test Line.".getBytes(StandardCharsets.ISO_8859_1), baos.toByteArray());
+                // 0 and 1
+                baos.reset();
+                assertEquals(1, inputStream.copy(0, 1, baos));
+                assertArrayEquals("A".getBytes(StandardCharsets.ISO_8859_1), baos.toByteArray());
+                // 11 and 1
+                baos.reset();
+                assertEquals(1, inputStream.copy(11, 1, baos));
+                assertArrayEquals(".".getBytes(StandardCharsets.ISO_8859_1), baos.toByteArray());
+                // 1 and 10
+                baos.reset();
+                assertEquals(10, inputStream.copy(1, 10, baos));
+                assertArrayEquals(" Test Line".getBytes(StandardCharsets.ISO_8859_1), baos.toByteArray());
+                // next
+                assertEquals('.', inputStream.read());
+            }
+        }
+    }
+
     @SuppressWarnings("resource") // instance variable access
     @Test
     public void testDeprecatedConstructorCloseOnCloseTrue() throws IOException {