[prev in list] [next in list] [prev in thread] [next in thread] 

List:       jakarta-commons-dev
Subject:    svn commit: r1404331 - /commons/proper/io/trunk/src/main/java/org/apache/commons/io/IOUtils.java
From:       sebb () apache ! org
Date:       2012-10-31 20:17:28
Message-ID: 20121031201728.5738723888FE () eris ! apache ! org
[Download RAW message or body]

Author: sebb
Date: Wed Oct 31 20:17:27 2012
New Revision: 1404331

URL: http://svn.apache.org/viewvc?rev=1404331&view=rev
Log:
IO-355 - document why we use read() rather than skip()

Modified:
    commons/proper/io/trunk/src/main/java/org/apache/commons/io/IOUtils.java

Modified: commons/proper/io/trunk/src/main/java/org/apache/commons/io/IOUtils.java
URL: http://svn.apache.org/viewvc/commons/proper/io/trunk/src/main/java/org/apache/commons/io/IOUtils.java?rev=1404331&r1=1404330&r2=1404331&view=diff
 ==============================================================================
--- commons/proper/io/trunk/src/main/java/org/apache/commons/io/IOUtils.java \
                (original)
+++ commons/proper/io/trunk/src/main/java/org/apache/commons/io/IOUtils.java Wed Oct \
31 20:17:27 2012 @@ -2286,13 +2286,21 @@ public class IOUtils {
      * Skip bytes from an input byte stream.
      * This implementation guarantees that it will read as many bytes
      * as possible before giving up; this may not always be the case for
-     * subclasses of {@link Reader}.
+     * skip() implementations in subclasses of {@link InputStream}.
+     * <p>
+     * Note that the implementation uses {@link InputStream#read(byte[], int, int)} \
rather +     * than delegating to {@link InputStream#skip(long)}.
+     * This means that the method may be considerably less efficient than using the \
actual skip implementation, +     * this is done to guarantee that the correct number \
of bytes are skipped. +     * </p>
+     *
      *   
      * @param input byte stream to skip
      * @param toSkip number of bytes to skip.
      * @return number of bytes actually skipped.
      * 
      * @see InputStream#skip(long)
+     * @see <a href="https://issues.apache.org/jira/browse/IO-203">IO-203 - Add \
                skipFully() method for InputStreams</a>
      * 
      * @throws IOException if there is a problem reading the file
      * @throws IllegalArgumentException if toSkip is negative
@@ -2312,6 +2320,7 @@ public class IOUtils {
         }
         long remain = toSkip;
         while (remain > 0) {
+            // See https://issues.apache.org/jira/browse/IO-203 for why we use \
                read() rather than delegating to skip()
             long n = input.read(SKIP_BYTE_BUFFER, 0, (int) Math.min(remain, \
SKIP_BUFFER_SIZE));  if (n < 0) { // EOF
                 break;
@@ -2325,13 +2334,20 @@ public class IOUtils {
      * Skip characters from an input character stream.
      * This implementation guarantees that it will read as many characters
      * as possible before giving up; this may not always be the case for
-     * subclasses of {@link Reader}.
-     *   
+     * skip() implementations in subclasses of {@link Reader}.
+     * <p>
+     * Note that the implementation uses {@link Reader#read(char[], int, int)} \
rather +     * than delegating to {@link Reader#skip(long)}.
+     * This means that the method may be considerably less efficient than using the \
actual skip implementation, +     * this is done to guarantee that the correct number \
of characters are skipped. +     * </p>
+     *
      * @param input character stream to skip
      * @param toSkip number of characters to skip.
      * @return number of characters actually skipped.
      * 
      * @see Reader#skip(long)
+     * @see <a href="https://issues.apache.org/jira/browse/IO-203">IO-203 - Add \
                skipFully() method for InputStreams</a>
      * 
      * @throws IOException if there is a problem reading the file
      * @throws IllegalArgumentException if toSkip is negative
@@ -2351,6 +2367,7 @@ public class IOUtils {
         }
         long remain = toSkip;
         while (remain > 0) {
+            // See https://issues.apache.org/jira/browse/IO-203 for why we use \
                read() rather than delegating to skip()
             long n = input.read(SKIP_CHAR_BUFFER, 0, (int) Math.min(remain, \
SKIP_BUFFER_SIZE));  if (n < 0) { // EOF
                 break;


[prev in list] [next in list] [prev in thread] [next in thread]