Add skipFully() methods for InputStream and Reader

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/io/trunk@920114 13f79535-47bb-0310-9956-ffa450edef68

Author: sebbASF

src/java/org/apache/commons/io/IOUtils.java

@@ -21,6 +21,7 @@
 import java.io.ByteArrayInputStream;
 import java.io.CharArrayWriter;
 import java.io.Closeable;
+import java.io.EOFException;
 import java.io.File;
 import java.io.IOException;
 import java.io.InputStream;
@@ -1398,4 +1399,51 @@ public static boolean contentEquals(Reader input1, Reader input2)
         return (ch2 == -1);
     }
 
+    /**
+     * Skip the requested number of bytes or fail if there are not enough left.
+     * <p>
+     * This allows for the possibility that {@link InputStream#skip(long)} may
+     * not skip as many bytes as requested (most likely because of reaching EOF).
+     * 
+     * @param input stream to skip
+     * @param toSkip the number of bytes to skip
+     * @see InputStream#skip(long)
+     * 
+     * @throws IOException if there is a problem reading the file
+     * @throws IllegalArgumentException if toSkip is negative
+     * @throws EOFException if the number of bytes skipped was incorrect 
+     */
+    public static void skipFully(InputStream input, long toSkip) throws IOException {
+        if (toSkip < 0){
+            throw new IllegalArgumentException("Bytes to skip must not be negative: "+toSkip);
+        }
+        long skipped = input.skip(toSkip);
+        if (skipped != toSkip) {
+            throw new EOFException("Bytes to skip: "+toSkip+" actual: "+skipped);
+        }
+    }
+
+    /**
+     * Skip the requested number of bytes or fail if there are not enough left.
+     * <p>
+     * This allows for the possibility that {@link Reader#skip(long)} may
+     * not skip as many bytes as requested (most likely because of reaching EOF).
+     * 
+     * @param input stream to skip
+     * @param toSkip the number of bytes to skip
+     * @see Reader#skip(long)
+     * 
+     * @throws IOException if there is a problem reading the file
+     * @throws IllegalArgumentException if toSkip is negative
+     * @throws EOFException if the number of bytes skipped was incorrect
+     */
+    public static void skipFully(Reader input, long toSkip) throws IOException {
+        if (toSkip < 0){
+            throw new IllegalArgumentException("Bytes to skip must not be negative: "+toSkip);
+        }
+        long skipped = input.skip(toSkip);
+        if (skipped != toSkip) {
+            throw new EOFException("Bytes to skip: "+toSkip+" actual: "+skipped);
+        }
+    }
 }

src/test/org/apache/commons/io/IOUtilsTestCase.java

@@ -16,6 +16,8 @@
  */
 package org.apache.commons.io;
 
+import java.io.ByteArrayInputStream;
+import java.io.CharArrayReader;
 import java.io.File;
 import java.io.FileInputStream;
 import java.io.FileOutputStream;
@@ -459,4 +461,47 @@ public void testReadLines_Reader() throws Exception {
             deleteFile(file);
         }
     }
+
+    public void testSkipStream() throws Exception{
+        final int size = 1027;
+
+        InputStream input = new ByteArrayInputStream(new byte [size]);
+        try {
+            IOUtils.skipFully(input, -1);
+            fail("Should have failed with IllegalArgumentException");
+        } catch (IllegalArgumentException expected){
+            // expected
+        }
+        IOUtils.skipFully(input, 0);
+        IOUtils.skipFully(input, size-1);
+        try {
+            IOUtils.skipFully(input, 2);
+            fail("Should have failed with IOException");
+        } catch (IOException expected) {
+            // expected
+        }
+        IOUtils.closeQuietly(input);
+
+    }
+
+    public void testSkipReader() throws Exception{
+        final int size = 1027;
+
+        Reader input = new CharArrayReader(new char[size]);
+        IOUtils.skipFully(input, 0);
+        IOUtils.skipFully(input, size-3);
+        try {
+            IOUtils.skipFully(input, -1);
+            fail("Should have failed with IllegalArgumentException");
+        } catch (IllegalArgumentException expected){
+            // expected
+        }
+        try {
+            IOUtils.skipFully(input, 5);
+            fail("Should have failed with IOException");
+        } catch (IOException expected) {
+            // expected
+        }
+        IOUtils.closeQuietly(input);
+    }
 }