Coverage Report - org.apache.commons.io.IOUtils
 
Classes in this File Line Coverage Branch Coverage Complexity
IOUtils
89%
398/446
88%
197/222
2.202
 
 1  
 /*
 2  
  * Licensed to the Apache Software Foundation (ASF) under one or more
 3  
  * contributor license agreements.  See the NOTICE file distributed with
 4  
  * this work for additional information regarding copyright ownership.
 5  
  * The ASF licenses this file to You under the Apache License, Version 2.0
 6  
  * (the "License"); you may not use this file except in compliance with
 7  
  * the License.  You may obtain a copy of the License at
 8  
  *
 9  
  *      http://www.apache.org/licenses/LICENSE-2.0
 10  
  *
 11  
  * Unless required by applicable law or agreed to in writing, software
 12  
  * distributed under the License is distributed on an "AS IS" BASIS,
 13  
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 14  
  * See the License for the specific language governing permissions and
 15  
  * limitations under the License.
 16  
  */
 17  
 package org.apache.commons.io;
 18  
 
 19  
 import java.io.BufferedInputStream;
 20  
 import java.io.BufferedOutputStream;
 21  
 import java.io.BufferedReader;
 22  
 import java.io.BufferedWriter;
 23  
 import java.io.ByteArrayInputStream;
 24  
 import java.io.CharArrayWriter;
 25  
 import java.io.Closeable;
 26  
 import java.io.EOFException;
 27  
 import java.io.File;
 28  
 import java.io.IOException;
 29  
 import java.io.InputStream;
 30  
 import java.io.InputStreamReader;
 31  
 import java.io.OutputStream;
 32  
 import java.io.OutputStreamWriter;
 33  
 import java.io.PrintWriter;
 34  
 import java.io.Reader;
 35  
 import java.io.UnsupportedEncodingException;
 36  
 import java.io.Writer;
 37  
 import java.net.HttpURLConnection;
 38  
 import java.net.ServerSocket;
 39  
 import java.net.Socket;
 40  
 import java.net.URI;
 41  
 import java.net.URL;
 42  
 import java.net.URLConnection;
 43  
 import java.nio.ByteBuffer;
 44  
 import java.nio.channels.ReadableByteChannel;
 45  
 import java.nio.channels.Selector;
 46  
 import java.nio.charset.Charset;
 47  
 import java.nio.charset.UnsupportedCharsetException;
 48  
 import java.util.ArrayList;
 49  
 import java.util.Collection;
 50  
 import java.util.List;
 51  
 
 52  
 import org.apache.commons.io.output.ByteArrayOutputStream;
 53  
 import org.apache.commons.io.output.StringBuilderWriter;
 54  
 
 55  
 /**
 56  
  * General IO stream manipulation utilities.
 57  
  * <p>
 58  
  * This class provides static utility methods for input/output operations.
 59  
  * <ul>
 60  
  * <li>closeQuietly - these methods close a stream ignoring nulls and exceptions
 61  
  * <li>toXxx/read - these methods read data from a stream
 62  
  * <li>write - these methods write data to a stream
 63  
  * <li>copy - these methods copy all the data from one stream to another
 64  
  * <li>contentEquals - these methods compare the content of two streams
 65  
  * </ul>
 66  
  * <p>
 67  
  * The byte-to-char methods and char-to-byte methods involve a conversion step.
 68  
  * Two methods are provided in each case, one that uses the platform default
 69  
  * encoding and the other which allows you to specify an encoding. You are
 70  
  * encouraged to always specify an encoding because relying on the platform
 71  
  * default can lead to unexpected results, for example when moving from
 72  
  * development to production.
 73  
  * <p>
 74  
  * All the methods in this class that read a stream are buffered internally.
 75  
  * This means that there is no cause to use a <code>BufferedInputStream</code>
 76  
  * or <code>BufferedReader</code>. The default buffer size of 4K has been shown
 77  
  * to be efficient in tests.
 78  
  * <p>
 79  
  * Wherever possible, the methods in this class do <em>not</em> flush or close
 80  
  * the stream. This is to avoid making non-portable assumptions about the
 81  
  * streams' origin and further use. Thus the caller is still responsible for
 82  
  * closing streams after use.
 83  
  * <p>
 84  
  * Origin of code: Excalibur.
 85  
  *
 86  
  * @version $Id: IOUtils.java 1565317 2014-02-06 16:02:20Z ggregory $
 87  
  */
 88  
 public class IOUtils {
 89  
     // NOTE: This class is focussed on InputStream, OutputStream, Reader and
 90  
     // Writer. Each method should take at least one of these as a parameter,
 91  
     // or return one of them.
 92  
 
 93  
     private static final int EOF = -1;
 94  
     /**
 95  
      * The Unix directory separator character.
 96  
      */
 97  
     public static final char DIR_SEPARATOR_UNIX = '/';
 98  
     /**
 99  
      * The Windows directory separator character.
 100  
      */
 101  
     public static final char DIR_SEPARATOR_WINDOWS = '\\';
 102  
     /**
 103  
      * The system directory separator character.
 104  
      */
 105  58
     public static final char DIR_SEPARATOR = File.separatorChar;
 106  
     /**
 107  
      * The Unix line separator string.
 108  
      */
 109  
     public static final String LINE_SEPARATOR_UNIX = "\n";
 110  
     /**
 111  
      * The Windows line separator string.
 112  
      */
 113  
     public static final String LINE_SEPARATOR_WINDOWS = "\r\n";
 114  
     /**
 115  
      * The system line separator string.
 116  
      */
 117  
     public static final String LINE_SEPARATOR;
 118  
 
 119  
     static {
 120  
         // avoid security issues
 121  58
         final StringBuilderWriter buf = new StringBuilderWriter(4);
 122  58
         final PrintWriter out = new PrintWriter(buf);
 123  58
         out.println();
 124  58
         LINE_SEPARATOR = buf.toString();
 125  58
         out.close();
 126  58
     }
 127  
 
 128  
     /**
 129  
      * The default buffer size ({@value}) to use for
 130  
      * {@link #copyLarge(InputStream, OutputStream)}
 131  
      * and
 132  
      * {@link #copyLarge(Reader, Writer)}
 133  
      */
 134  
     private static final int DEFAULT_BUFFER_SIZE = 1024 * 4;
 135  
 
 136  
     /**
 137  
      * The default buffer size to use for the skip() methods.
 138  
      */
 139  
     private static final int SKIP_BUFFER_SIZE = 2048;
 140  
 
 141  
     // Allocated in the relevant skip method if necessary.
 142  
     /*
 143  
      * N.B. no need to synchronize these because:
 144  
      * - we don't care if the buffer is created multiple times (the data is ignored)
 145  
      * - we always use the same size buffer, so if it it is recreated it will still be OK
 146  
      * (if the buffer size were variable, we would need to synch. to ensure some other thread
 147  
      * did not create a smaller one)
 148  
      */
 149  
     private static char[] SKIP_CHAR_BUFFER;
 150  
     private static byte[] SKIP_BYTE_BUFFER;
 151  
 
 152  
     /**
 153  
      * Instances should NOT be constructed in standard programming.
 154  
      */
 155  
     public IOUtils() {
 156  0
         super();
 157  0
     }
 158  
 
 159  
     //-----------------------------------------------------------------------
 160  
 
 161  
     /**
 162  
      * Closes a URLConnection.
 163  
      *
 164  
      * @param conn the connection to close.
 165  
      * @since 2.4
 166  
      */
 167  
     public static void close(final URLConnection conn) {
 168  6
         if (conn instanceof HttpURLConnection) {
 169  0
             ((HttpURLConnection) conn).disconnect();
 170  
         }
 171  6
     }
 172  
 
 173  
     /**
 174  
      * Closes an <code>Reader</code> unconditionally.
 175  
      * <p>
 176  
      * Equivalent to {@link Reader#close()}, except any exceptions will be ignored.
 177  
      * This is typically used in finally blocks.
 178  
      * <p>
 179  
      * Example code:
 180  
      * <pre>
 181  
      *   char[] data = new char[1024];
 182  
      *   Reader in = null;
 183  
      *   try {
 184  
      *       in = new FileReader("foo.txt");
 185  
      *       in.read(data);
 186  
      *       in.close(); //close errors are handled
 187  
      *   } catch (Exception e) {
 188  
      *       // error handling
 189  
      *   } finally {
 190  
      *       IOUtils.closeQuietly(in);
 191  
      *   }
 192  
      * </pre>
 193  
      *
 194  
      * @param input  the Reader to close, may be null or already closed
 195  
      */
 196  
     public static void closeQuietly(final Reader input) {
 197  154
         closeQuietly((Closeable)input);
 198  154
     }
 199  
 
 200  
     /**
 201  
      * Closes an <code>Writer</code> unconditionally.
 202  
      * <p>
 203  
      * Equivalent to {@link Writer#close()}, except any exceptions will be ignored.
 204  
      * This is typically used in finally blocks.
 205  
      * <p>
 206  
      * Example code:
 207  
      * <pre>
 208  
      *   Writer out = null;
 209  
      *   try {
 210  
      *       out = new StringWriter();
 211  
      *       out.write("Hello World");
 212  
      *       out.close(); //close errors are handled
 213  
      *   } catch (Exception e) {
 214  
      *       // error handling
 215  
      *   } finally {
 216  
      *       IOUtils.closeQuietly(out);
 217  
      *   }
 218  
      * </pre>
 219  
      *
 220  
      * @param output  the Writer to close, may be null or already closed
 221  
      */
 222  
     public static void closeQuietly(final Writer output) {
 223  100
         closeQuietly((Closeable)output);
 224  100
     }
 225  
 
 226  
     /**
 227  
      * Closes an <code>InputStream</code> unconditionally.
 228  
      * <p>
 229  
      * Equivalent to {@link InputStream#close()}, except any exceptions will be ignored.
 230  
      * This is typically used in finally blocks.
 231  
      * <p>
 232  
      * Example code:
 233  
      * <pre>
 234  
      *   byte[] data = new byte[1024];
 235  
      *   InputStream in = null;
 236  
      *   try {
 237  
      *       in = new FileInputStream("foo.txt");
 238  
      *       in.read(data);
 239  
      *       in.close(); //close errors are handled
 240  
      *   } catch (Exception e) {
 241  
      *       // error handling
 242  
      *   } finally {
 243  
      *       IOUtils.closeQuietly(in);
 244  
      *   }
 245  
      * </pre>
 246  
      *
 247  
      * @param input  the InputStream to close, may be null or already closed
 248  
      */
 249  
     public static void closeQuietly(final InputStream input) {
 250  280
         closeQuietly((Closeable)input);
 251  280
     }
 252  
 
 253  
     /**
 254  
      * Closes an <code>OutputStream</code> unconditionally.
 255  
      * <p>
 256  
      * Equivalent to {@link OutputStream#close()}, except any exceptions will be ignored.
 257  
      * This is typically used in finally blocks.
 258  
      * <p>
 259  
      * Example code:
 260  
      * <pre>
 261  
      * byte[] data = "Hello, World".getBytes();
 262  
      *
 263  
      * OutputStream out = null;
 264  
      * try {
 265  
      *     out = new FileOutputStream("foo.txt");
 266  
      *     out.write(data);
 267  
      *     out.close(); //close errors are handled
 268  
      * } catch (IOException e) {
 269  
      *     // error handling
 270  
      * } finally {
 271  
      *     IOUtils.closeQuietly(out);
 272  
      * }
 273  
      * </pre>
 274  
      *
 275  
      * @param output  the OutputStream to close, may be null or already closed
 276  
      */
 277  
     public static void closeQuietly(final OutputStream output) {
 278  2318
         closeQuietly((Closeable)output);
 279  2318
     }
 280  
 
 281  
     /**
 282  
      * Closes a <code>Closeable</code> unconditionally.
 283  
      * <p>
 284  
      * Equivalent to {@link Closeable#close()}, except any exceptions will be ignored. This is typically used in
 285  
      * finally blocks.
 286  
      * <p>
 287  
      * Example code:
 288  
      * 
 289  
      * <pre>
 290  
      * Closeable closeable = null;
 291  
      * try {
 292  
      *     closeable = new FileReader(&quot;foo.txt&quot;);
 293  
      *     // process closeable
 294  
      *     closeable.close();
 295  
      * } catch (Exception e) {
 296  
      *     // error handling
 297  
      * } finally {
 298  
      *     IOUtils.closeQuietly(closeable);
 299  
      * }
 300  
      * </pre>
 301  
      * 
 302  
      * Closing all streams:
 303  
      * 
 304  
      * <pre>
 305  
      * try {
 306  
      *     return IOUtils.copy(inputStream, outputStream);
 307  
      * } finally {
 308  
      *     IOUtils.closeQuietly(inputStream);
 309  
      *     IOUtils.closeQuietly(outputStream);
 310  
      * }
 311  
      * </pre>
 312  
      * 
 313  
      * @param closeable
 314  
      *            the objects to close, may be null or already closed
 315  
      * @since 2.0
 316  
      */
 317  
     public static void closeQuietly(final Closeable closeable) {
 318  
         try {
 319  3320
             if (closeable != null) {
 320  3128
                 closeable.close();
 321  
             }
 322  6
         } catch (final IOException ioe) {
 323  
             // ignore
 324  3314
         }
 325  3320
     }
 326  
 
 327  
     /**
 328  
      * Closes a <code>Closeable</code> unconditionally.
 329  
      * <p>
 330  
      * Equivalent to {@link Closeable#close()}, except any exceptions will be ignored. This is typically used in
 331  
      * finally blocks.
 332  
      * <p>
 333  
      * Example code:
 334  
      * 
 335  
      * <pre>
 336  
      * Closeable closeable = null;
 337  
      * try {
 338  
      *     closeable = new FileReader(&quot;foo.txt&quot;);
 339  
      *     // process closeable
 340  
      *     closeable.close();
 341  
      * } catch (Exception e) {
 342  
      *     // error handling
 343  
      * } finally {
 344  
      *     IOUtils.closeQuietly(closeable);
 345  
      * }
 346  
      * </pre>
 347  
      * 
 348  
      * Closing all streams:
 349  
      * 
 350  
      * <pre>
 351  
      * try {
 352  
      *     return IOUtils.copy(inputStream, outputStream);
 353  
      * } finally {
 354  
      *     IOUtils.closeQuietly(inputStream);
 355  
      *     IOUtils.closeQuietly(outputStream);
 356  
      * }
 357  
      * </pre>
 358  
      * 
 359  
      * @param closeables
 360  
      *            the objects to close, may be null or already closed
 361  
      * @since 2.5
 362  
      */
 363  
     public static void closeQuietly(final Closeable... closeables) {
 364  80
         if (closeables == null) {
 365  0
             return;
 366  
         }
 367  382
         for (final Closeable closeable : closeables) {
 368  302
             closeQuietly(closeable);
 369  
         }
 370  80
     }
 371  
 
 372  
     /**
 373  
      * Closes a <code>Socket</code> unconditionally.
 374  
      * <p>
 375  
      * Equivalent to {@link Socket#close()}, except any exceptions will be ignored.
 376  
      * This is typically used in finally blocks.
 377  
      * <p>
 378  
      * Example code:
 379  
      * <pre>
 380  
      *   Socket socket = null;
 381  
      *   try {
 382  
      *       socket = new Socket("http://www.foo.com/", 80);
 383  
      *       // process socket
 384  
      *       socket.close();
 385  
      *   } catch (Exception e) {
 386  
      *       // error handling
 387  
      *   } finally {
 388  
      *       IOUtils.closeQuietly(socket);
 389  
      *   }
 390  
      * </pre>
 391  
      *
 392  
      * @param sock the Socket to close, may be null or already closed
 393  
      * @since 2.0
 394  
      */
 395  
     public static void closeQuietly(final Socket sock){
 396  6
         if (sock != null){
 397  
             try {
 398  4
                 sock.close();
 399  2
             } catch (final IOException ioe) {
 400  
                 // ignored
 401  2
             }
 402  
         }
 403  6
     }
 404  
 
 405  
     /**
 406  
      * Closes a <code>Selector</code> unconditionally.
 407  
      * <p>
 408  
      * Equivalent to {@link Selector#close()}, except any exceptions will be ignored.
 409  
      * This is typically used in finally blocks.
 410  
      * <p>
 411  
      * Example code:
 412  
      * <pre>
 413  
      *   Selector selector = null;
 414  
      *   try {
 415  
      *       selector = Selector.open();
 416  
      *       // process socket
 417  
      *
 418  
      *   } catch (Exception e) {
 419  
      *       // error handling
 420  
      *   } finally {
 421  
      *       IOUtils.closeQuietly(selector);
 422  
      *   }
 423  
      * </pre>
 424  
      *
 425  
      * @param selector the Selector to close, may be null or already closed
 426  
      * @since 2.2
 427  
      */
 428  
     public static void closeQuietly(final Selector selector){
 429  10
         if (selector != null){
 430  
             try {
 431  8
               selector.close();
 432  2
             } catch (final IOException ioe) {
 433  
                 // ignored
 434  6
             }
 435  
         }
 436  10
     }
 437  
 
 438  
     /**
 439  
      * Closes a <code>ServerSocket</code> unconditionally.
 440  
      * <p>
 441  
      * Equivalent to {@link ServerSocket#close()}, except any exceptions will be ignored.
 442  
      * This is typically used in finally blocks.
 443  
      * <p>
 444  
      * Example code:
 445  
      * <pre>
 446  
      *   ServerSocket socket = null;
 447  
      *   try {
 448  
      *       socket = new ServerSocket();
 449  
      *       // process socket
 450  
      *       socket.close();
 451  
      *   } catch (Exception e) {
 452  
      *       // error handling
 453  
      *   } finally {
 454  
      *       IOUtils.closeQuietly(socket);
 455  
      *   }
 456  
      * </pre>
 457  
      *
 458  
      * @param sock the ServerSocket to close, may be null or already closed
 459  
      * @since 2.2
 460  
      */
 461  
     public static void closeQuietly(final ServerSocket sock){
 462  6
         if (sock != null){
 463  
             try {
 464  4
                 sock.close();
 465  2
             } catch (final IOException ioe) {
 466  
                 // ignored
 467  2
             }
 468  
         }
 469  6
     }
 470  
 
 471  
     /**
 472  
      * Fetches entire contents of an <code>InputStream</code> and represent
 473  
      * same data as result InputStream.
 474  
      * <p>
 475  
      * This method is useful where,
 476  
      * <ul>
 477  
      * <li>Source InputStream is slow.</li>
 478  
      * <li>It has network resources associated, so we cannot keep it open for
 479  
      * long time.</li>
 480  
      * <li>It has network timeout associated.</li>
 481  
      * </ul>
 482  
      * It can be used in favor of {@link #toByteArray(InputStream)}, since it
 483  
      * avoids unnecessary allocation and copy of byte[].<br>
 484  
      * This method buffers the input internally, so there is no need to use a
 485  
      * <code>BufferedInputStream</code>.
 486  
      *
 487  
      * @param input Stream to be fully buffered.
 488  
      * @return A fully buffered stream.
 489  
      * @throws IOException if an I/O error occurs
 490  
      * @since 2.0
 491  
      */
 492  
     public static InputStream toBufferedInputStream(final InputStream input) throws IOException {
 493  2
         return ByteArrayOutputStream.toBufferedInputStream(input);
 494  
     }
 495  
 
 496  
     /**
 497  
      * Fetches entire contents of an <code>InputStream</code> and represent
 498  
      * same data as result InputStream.
 499  
      * <p>
 500  
      * This method is useful where,
 501  
      * <ul>
 502  
      * <li>Source InputStream is slow.</li>
 503  
      * <li>It has network resources associated, so we cannot keep it open for
 504  
      * long time.</li>
 505  
      * <li>It has network timeout associated.</li>
 506  
      * </ul>
 507  
      * It can be used in favor of {@link #toByteArray(InputStream)}, since it
 508  
      * avoids unnecessary allocation and copy of byte[].<br>
 509  
      * This method buffers the input internally, so there is no need to use a
 510  
      * <code>BufferedInputStream</code>.
 511  
      *
 512  
      * @param input Stream to be fully buffered.
 513  
      * @param size the initial buffer size
 514  
      * @return A fully buffered stream.
 515  
      * @throws IOException if an I/O error occurs
 516  
      * @since 2.5
 517  
      */
 518  
     public static InputStream toBufferedInputStream(final InputStream input, int size) throws IOException {
 519  2
         return ByteArrayOutputStream.toBufferedInputStream(input, size);
 520  
     }
 521  
 
 522  
     /**
 523  
      * Returns the given reader if it is a {@link BufferedReader}, otherwise creates a BufferedReader from the given
 524  
      * reader.
 525  
      *
 526  
      * @param reader
 527  
      *            the reader to wrap or return (not null)
 528  
      * @return the given reader or a new {@link BufferedReader} for the given reader
 529  
      * @since 2.2
 530  
      * @see #buffer(Reader)
 531  
      * @throws NullPointerException if the input parameter is null
 532  
      */
 533  
     public static BufferedReader toBufferedReader(final Reader reader) {
 534  78
         return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader);
 535  
     }
 536  
 
 537  
     /**
 538  
      * Returns the given reader if it is a {@link BufferedReader}, otherwise creates a BufferedReader from the given
 539  
      * reader.
 540  
      *
 541  
      * @param reader
 542  
      *            the reader to wrap or return (not null)
 543  
      * @param size the buffer size, if a new BufferedReader is created.
 544  
      * @return the given reader or a new {@link BufferedReader} for the given reader
 545  
      * @since 2.5
 546  
      * @see #buffer(Reader)
 547  
      * @throws NullPointerException if the input parameter is null
 548  
      */
 549  
     public static BufferedReader toBufferedReader(final Reader reader, int size) {
 550  0
         return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader, size);
 551  
     }
 552  
 
 553  
     /**
 554  
      * Returns the given reader if it is already a {@link BufferedReader}, otherwise creates a BufferedReader from the given
 555  
      * reader.
 556  
      *
 557  
      * @param reader
 558  
      *            the reader to wrap or return (not null)
 559  
      * @return the given reader or a new {@link BufferedReader} for the given reader
 560  
      * @since 2.5
 561  
      * @throws NullPointerException if the input parameter is null
 562  
      */
 563  
     public static BufferedReader buffer(final Reader reader) {
 564  8
         return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader);
 565  
     }
 566  
 
 567  
     /**
 568  
      * Returns the given reader if it is already a {@link BufferedReader}, otherwise creates a BufferedReader from the given
 569  
      * reader.
 570  
      *
 571  
      * @param reader
 572  
      *            the reader to wrap or return (not null)
 573  
      * @param size the buffer size, if a new BufferedReader is created.
 574  
      * @return the given reader or a new {@link BufferedReader} for the given reader
 575  
      * @since 2.5
 576  
      * @throws NullPointerException if the input parameter is null
 577  
      */
 578  
     public static BufferedReader buffer(final Reader reader, int size) {
 579  4
         return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader, size);
 580  
     }
 581  
 
 582  
     /**
 583  
      * Returns the given Writer if it is already a {@link BufferedWriter}, otherwise creates a BufferedWriter from the given
 584  
      * Writer.
 585  
      *
 586  
      * @param writer
 587  
      *            the Writer to wrap or return (not null)
 588  
      * @return the given Writer or a new {@link BufferedWriter} for the given Writer
 589  
      * @since 2.5
 590  
      * @throws NullPointerException if the input parameter is null
 591  
      */
 592  
     public static BufferedWriter buffer(final Writer writer) {
 593  8
         return writer instanceof BufferedWriter ? (BufferedWriter) writer : new BufferedWriter(writer);
 594  
     }
 595  
 
 596  
     /**
 597  
      * Returns the given Writer if it is already a {@link BufferedWriter}, otherwise creates a BufferedWriter from the given
 598  
      * Writer.
 599  
      *
 600  
      * @param writer
 601  
      *            the Writer to wrap or return (not null)
 602  
      * @param size the buffer size, if a new BufferedWriter is created.
 603  
      * @return the given Writer or a new {@link BufferedWriter} for the given Writer
 604  
      * @since 2.5
 605  
      * @throws NullPointerException if the input parameter is null
 606  
      */
 607  
     public static BufferedWriter buffer(final Writer writer, int size) {
 608  4
         return writer instanceof BufferedWriter ? (BufferedWriter) writer : new BufferedWriter(writer, size);
 609  
     }
 610  
 
 611  
     /**
 612  
      * Returns the given OutputStream if it is already a {@link BufferedOutputStream}, otherwise creates a BufferedOutputStream from the given
 613  
      * OutputStream.
 614  
      *
 615  
      * @param outputStream
 616  
      *            the OutputStream to wrap or return (not null)
 617  
      * @return the given OutputStream or a new {@link BufferedOutputStream} for the given OutputStream
 618  
      * @since 2.5
 619  
      * @throws NullPointerException if the input parameter is null
 620  
      */
 621  
     public static BufferedOutputStream buffer(final OutputStream outputStream) {
 622  
         // reject null early on rather than waiting for IO operation to fail
 623  8
         if (outputStream == null) { // not checked by BufferedOutputStream
 624  2
             throw new NullPointerException();
 625  
         }
 626  6
         return outputStream instanceof BufferedOutputStream ? (BufferedOutputStream) outputStream : new BufferedOutputStream(outputStream);
 627  
     }
 628  
 
 629  
     /**
 630  
      * Returns the given OutputStream if it is already a {@link BufferedOutputStream}, otherwise creates a BufferedOutputStream from the given
 631  
      * OutputStream.
 632  
      *
 633  
      * @param outputStream
 634  
      *            the OutputStream to wrap or return (not null)
 635  
      * @param size the buffer size, if a new BufferedOutputStream is created.
 636  
      * @return the given OutputStream or a new {@link BufferedOutputStream} for the given OutputStream
 637  
      * @since 2.5
 638  
      * @throws NullPointerException if the input parameter is null
 639  
      */
 640  
     public static BufferedOutputStream buffer(final OutputStream outputStream, int size) {
 641  
         // reject null early on rather than waiting for IO operation to fail
 642  4
         if (outputStream == null) { // not checked by BufferedOutputStream
 643  0
             throw new NullPointerException();
 644  
         }
 645  4
         return outputStream instanceof BufferedOutputStream ? (BufferedOutputStream) outputStream : new BufferedOutputStream(outputStream, size);
 646  
     }
 647  
 
 648  
     /**
 649  
      * Returns the given InputStream if it is already a {@link BufferedInputStream}, otherwise creates a BufferedInputStream from the given
 650  
      * InputStream.
 651  
      *
 652  
      * @param inputStream
 653  
      *            the InputStream to wrap or return (not null)
 654  
      * @return the given InputStream or a new {@link BufferedInputStream} for the given InputStream
 655  
      * @since 2.5
 656  
      * @throws NullPointerException if the input parameter is null
 657  
      */
 658  
     public static BufferedInputStream buffer(final InputStream inputStream) {
 659  
         // reject null early on rather than waiting for IO operation to fail
 660  8
         if (inputStream == null) { // not checked by BufferedInputStream
 661  2
             throw new NullPointerException();
 662  
         }
 663  6
         return inputStream instanceof BufferedInputStream ? (BufferedInputStream) inputStream : new BufferedInputStream(inputStream);
 664  
     }
 665  
 
 666  
     /**
 667  
      * Returns the given InputStream if it is already a {@link BufferedInputStream}, otherwise creates a BufferedInputStream from the given
 668  
      * InputStream.
 669  
      *
 670  
      * @param inputStream
 671  
      *            the InputStream to wrap or return (not null)
 672  
      * @param size the buffer size, if a new BufferedInputStream is created.
 673  
      * @return the given InputStream or a new {@link BufferedInputStream} for the given InputStream
 674  
      * @since 2.5
 675  
      * @throws NullPointerException if the input parameter is null
 676  
      */
 677  
     public static BufferedInputStream buffer(final InputStream inputStream, int size) {
 678  
         // reject null early on rather than waiting for IO operation to fail
 679  4
         if (inputStream == null) { // not checked by BufferedInputStream
 680  0
             throw new NullPointerException();
 681  
         }
 682  4
         return inputStream instanceof BufferedInputStream ? (BufferedInputStream) inputStream : new BufferedInputStream(inputStream, size);
 683  
     }
 684  
 
 685  
     // read toByteArray
 686  
     //-----------------------------------------------------------------------
 687  
     /**
 688  
      * Gets the contents of an <code>InputStream</code> as a <code>byte[]</code>.
 689  
      * <p>
 690  
      * This method buffers the input internally, so there is no need to use a
 691  
      * <code>BufferedInputStream</code>.
 692  
      *
 693  
      * @param input  the <code>InputStream</code> to read from
 694  
      * @return the requested byte array
 695  
      * @throws NullPointerException if the input is null
 696  
      * @throws IOException if an I/O error occurs
 697  
      */
 698  
     public static byte[] toByteArray(final InputStream input) throws IOException {
 699  48
         final ByteArrayOutputStream output = new ByteArrayOutputStream();
 700  48
         copy(input, output);
 701  48
         return output.toByteArray();
 702  
     }
 703  
 
 704  
     /**
 705  
      * Gets contents of an <code>InputStream</code> as a <code>byte[]</code>.
 706  
      * Use this method instead of <code>toByteArray(InputStream)</code>
 707  
      * when <code>InputStream</code> size is known.
 708  
      * <b>NOTE:</b> the method checks that the length can safely be cast to an int without truncation
 709  
      * before using {@link IOUtils#toByteArray(java.io.InputStream, int)} to read into the byte array.
 710  
      * (Arrays can have no more than Integer.MAX_VALUE entries anyway)
 711  
      *
 712  
      * @param input the <code>InputStream</code> to read from
 713  
      * @param size the size of <code>InputStream</code>
 714  
      * @return the requested byte array
 715  
      * @throws IOException if an I/O error occurs or <code>InputStream</code> size differ from parameter size
 716  
      * @throws IllegalArgumentException if size is less than zero or size is greater than Integer.MAX_VALUE
 717  
      * @see IOUtils#toByteArray(java.io.InputStream, int)
 718  
      * @since 2.1
 719  
      */
 720  
     public static byte[] toByteArray(final InputStream input, final long size) throws IOException {
 721  
 
 722  10
       if(size > Integer.MAX_VALUE) {
 723  2
           throw new IllegalArgumentException("Size cannot be greater than Integer max value: " + size);
 724  
       }
 725  
 
 726  8
       return toByteArray(input, (int) size);
 727  
     }
 728  
 
 729  
     /**
 730  
      * Gets the contents of an <code>InputStream</code> as a <code>byte[]</code>.
 731  
      * Use this method instead of <code>toByteArray(InputStream)</code>
 732  
      * when <code>InputStream</code> size is known
 733  
      * @param input the <code>InputStream</code> to read from
 734  
      * @param size the size of <code>InputStream</code>
 735  
      * @return the requested byte array
 736  
      * @throws IOException if an I/O error occurs or <code>InputStream</code> size differ from parameter size
 737  
      * @throws IllegalArgumentException if size is less than zero
 738  
      * @since 2.1
 739  
      */
 740  
     public static byte[] toByteArray(final InputStream input, final int size) throws IOException {
 741  
 
 742  12
         if (size < 0) {
 743  2
             throw new IllegalArgumentException("Size must be equal or greater than zero: " + size);
 744  
         }
 745  
 
 746  10
         if (size == 0) {
 747  4
             return new byte[0];
 748  
         }
 749  
 
 750  6
         final byte[] data = new byte[size];
 751  6
         int offset = 0;
 752  
         int readed;
 753  
 
 754  12
         while (offset < size && (readed = input.read(data, offset, size - offset)) != EOF) {
 755  6
             offset += readed;
 756  
         }
 757  
 
 758  6
         if (offset != size) {
 759  2
             throw new IOException("Unexpected readed size. current: " + offset + ", excepted: " + size);
 760  
         }
 761  
 
 762  4
         return data;
 763  
     }
 764  
 
 765  
     /**
 766  
      * Gets the contents of a <code>Reader</code> as a <code>byte[]</code>
 767  
      * using the default character encoding of the platform.
 768  
      * <p>
 769  
      * This method buffers the input internally, so there is no need to use a
 770  
      * <code>BufferedReader</code>.
 771  
      *
 772  
      * @param input  the <code>Reader</code> to read from
 773  
      * @return the requested byte array
 774  
      * @throws NullPointerException if the input is null
 775  
      * @throws IOException if an I/O error occurs
 776  
      * @deprecated 2.5 use {@link #toByteArray(Reader, Charset)} instead
 777  
      */
 778  
     @Deprecated
 779  
     public static byte[] toByteArray(final Reader input) throws IOException {
 780  2
         return toByteArray(input, Charset.defaultCharset());
 781  
     }
 782  
 
 783  
     /**
 784  
      * Gets the contents of a <code>Reader</code> as a <code>byte[]</code>
 785  
      * using the specified character encoding.
 786  
      * <p>
 787  
      * This method buffers the input internally, so there is no need to use a
 788  
      * <code>BufferedReader</code>.
 789  
      *
 790  
      * @param input  the <code>Reader</code> to read from
 791  
      * @param encoding  the encoding to use, null means platform default
 792  
      * @return the requested byte array
 793  
      * @throws NullPointerException if the input is null
 794  
      * @throws IOException if an I/O error occurs
 795  
      * @since 2.3
 796  
      */
 797  
     public static byte[] toByteArray(final Reader input, final Charset encoding) throws IOException {
 798  4
         final ByteArrayOutputStream output = new ByteArrayOutputStream();
 799  4
         copy(input, output, encoding);
 800  4
         return output.toByteArray();
 801  
     }
 802  
 
 803  
     /**
 804  
      * Gets the contents of a <code>Reader</code> as a <code>byte[]</code>
 805  
      * using the specified character encoding.
 806  
      * <p>
 807  
      * Character encoding names can be found at
 808  
      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
 809  
      * <p>
 810  
      * This method buffers the input internally, so there is no need to use a
 811  
      * <code>BufferedReader</code>.
 812  
      *
 813  
      * @param input  the <code>Reader</code> to read from
 814  
      * @param encoding  the encoding to use, null means platform default
 815  
      * @return the requested byte array
 816  
      * @throws NullPointerException if the input is null
 817  
      * @throws IOException if an I/O error occurs
 818  
      * @throws UnsupportedCharsetException
 819  
      *             thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not
 820  
      *             supported.
 821  
      * @since 1.1
 822  
      */
 823  
     public static byte[] toByteArray(final Reader input, final String encoding) throws IOException {
 824  2
         return toByteArray(input, Charsets.toCharset(encoding));
 825  
     }
 826  
 
 827  
     /**
 828  
      * Gets the contents of a <code>String</code> as a <code>byte[]</code>
 829  
      * using the default character encoding of the platform.
 830  
      * <p>
 831  
      * This is the same as {@link String#getBytes()}.
 832  
      *
 833  
      * @param input  the <code>String</code> to convert
 834  
      * @return the requested byte array
 835  
      * @throws NullPointerException if the input is null
 836  
      * @throws IOException if an I/O error occurs (never occurs)
 837  
      * @deprecated 2.5 Use {@link String#getBytes()} instead
 838  
      */
 839  
     @Deprecated
 840  
     public static byte[] toByteArray(final String input) throws IOException {
 841  
         // make explicit the use of the default charset
 842  2
         return input.getBytes(Charset.defaultCharset());
 843  
     }
 844  
 
 845  
     /**
 846  
      * Gets the contents of a <code>URI</code> as a <code>byte[]</code>.
 847  
      *
 848  
      * @param uri
 849  
      *            the <code>URI</code> to read
 850  
      * @return the requested byte array
 851  
      * @throws NullPointerException
 852  
      *             if the uri is null
 853  
      * @throws IOException
 854  
      *             if an I/O exception occurs
 855  
      * @since 2.4
 856  
      */
 857  
     public static byte[] toByteArray(final URI uri) throws IOException {
 858  2
         return IOUtils.toByteArray(uri.toURL());
 859  
     }
 860  
 
 861  
     /**
 862  
      * Gets the contents of a <code>URL</code> as a <code>byte[]</code>.
 863  
      *
 864  
      * @param url
 865  
      *            the <code>URL</code> to read
 866  
      * @return the requested byte array
 867  
      * @throws NullPointerException
 868  
      *             if the input is null
 869  
      * @throws IOException
 870  
      *             if an I/O exception occurs
 871  
      * @since 2.4
 872  
      */
 873  
     public static byte[] toByteArray(final URL url) throws IOException {
 874  4
         final URLConnection conn = url.openConnection();
 875  
         try {
 876  4
             return IOUtils.toByteArray(conn);
 877  
         } finally {
 878  4
             close(conn);
 879  
         }
 880  
     }
 881  
 
 882  
     /**
 883  
      * Gets the contents of a <code>URLConnection</code> as a <code>byte[]</code>.
 884  
      *
 885  
      * @param urlConn
 886  
      *            the <code>URLConnection</code> to read
 887  
      * @return the requested byte array
 888  
      * @throws NullPointerException
 889  
      *             if the urlConn is null
 890  
      * @throws IOException
 891  
      *             if an I/O exception occurs
 892  
      * @since 2.4
 893  
      */
 894  
     public static byte[] toByteArray(final URLConnection urlConn) throws IOException {
 895  6
         final InputStream inputStream = urlConn.getInputStream();
 896  
         try {
 897  6
             return IOUtils.toByteArray(inputStream);
 898  
         } finally {
 899  6
             inputStream.close();
 900  
         }
 901  
     }
 902  
 
 903  
     // read char[]
 904  
     //-----------------------------------------------------------------------
 905  
     /**
 906  
      * Gets the contents of an <code>InputStream</code> as a character array
 907  
      * using the default character encoding of the platform.
 908  
      * <p>
 909  
      * This method buffers the input internally, so there is no need to use a
 910  
      * <code>BufferedInputStream</code>.
 911  
      *
 912  
      * @param is  the <code>InputStream</code> to read from
 913  
      * @return the requested character array
 914  
      * @throws NullPointerException if the input is null
 915  
      * @throws IOException if an I/O error occurs
 916  
      * @since 1.1
 917  
      * @deprecated 2.5 use {@link #toCharArray(InputStream, Charset)} instead
 918  
      */
 919  
     @Deprecated
 920  
     public static char[] toCharArray(final InputStream is) throws IOException {
 921  2
         return toCharArray(is, Charset.defaultCharset());
 922  
     }
 923  
 
 924  
     /**
 925  
      * Gets the contents of an <code>InputStream</code> as a character array
 926  
      * using the specified character encoding.
 927  
      * <p>
 928  
      * This method buffers the input internally, so there is no need to use a
 929  
      * <code>BufferedInputStream</code>.
 930  
      *
 931  
      * @param is  the <code>InputStream</code> to read from
 932  
      * @param encoding  the encoding to use, null means platform default
 933  
      * @return the requested character array
 934  
      * @throws NullPointerException if the input is null
 935  
      * @throws IOException if an I/O error occurs
 936  
      * @since 2.3
 937  
      */
 938  
     public static char[] toCharArray(final InputStream is, final Charset encoding)
 939  
             throws IOException {
 940  4
         final CharArrayWriter output = new CharArrayWriter();
 941  4
         copy(is, output, encoding);
 942  4
         return output.toCharArray();
 943  
     }
 944  
 
 945  
     /**
 946  
      * Gets the contents of an <code>InputStream</code> as a character array
 947  
      * using the specified character encoding.
 948  
      * <p>
 949  
      * Character encoding names can be found at
 950  
      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
 951  
      * <p>
 952  
      * This method buffers the input internally, so there is no need to use a
 953  
      * <code>BufferedInputStream</code>.
 954  
      *
 955  
      * @param is  the <code>InputStream</code> to read from
 956  
      * @param encoding  the encoding to use, null means platform default
 957  
      * @return the requested character array
 958  
      * @throws NullPointerException if the input is null
 959  
      * @throws IOException if an I/O error occurs
 960  
      * @throws UnsupportedCharsetException
 961  
      *             thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not
 962  
      *             supported.
 963  
      * @since 1.1
 964  
      */
 965  
     public static char[] toCharArray(final InputStream is, final String encoding) throws IOException {
 966  2
         return toCharArray(is, Charsets.toCharset(encoding));
 967  
     }
 968  
 
 969  
     /**
 970  
      * Gets the contents of a <code>Reader</code> as a character array.
 971  
      * <p>
 972  
      * This method buffers the input internally, so there is no need to use a
 973  
      * <code>BufferedReader</code>.
 974  
      *
 975  
      * @param input  the <code>Reader</code> to read from
 976  
      * @return the requested character array
 977  
      * @throws NullPointerException if the input is null
 978  
      * @throws IOException if an I/O error occurs
 979  
      * @since 1.1
 980  
      */
 981  
     public static char[] toCharArray(final Reader input) throws IOException {
 982  2
         final CharArrayWriter sw = new CharArrayWriter();
 983  2
         copy(input, sw);
 984  2
         return sw.toCharArray();
 985  
     }
 986  
 
 987  
     // read toString
 988  
     //-----------------------------------------------------------------------
 989  
     /**
 990  
      * Gets the contents of an <code>InputStream</code> as a String
 991  
      * using the default character encoding of the platform.
 992  
      * <p>
 993  
      * This method buffers the input internally, so there is no need to use a
 994  
      * <code>BufferedInputStream</code>.
 995  
      *
 996  
      * @param input  the <code>InputStream</code> to read from
 997  
      * @return the requested String
 998  
      * @throws NullPointerException if the input is null
 999  
      * @throws IOException if an I/O error occurs
 1000  
      * @deprecated 2.5 use {@link #toString(InputStream, Charset)} instead
 1001  
      */
 1002  
     @Deprecated
 1003  
     public static String toString(final InputStream input) throws IOException {
 1004  2
         return toString(input, Charset.defaultCharset());
 1005  
     }
 1006  
 
 1007  
     /**
 1008  
      * Gets the contents of an <code>InputStream</code> as a String
 1009  
      * using the specified character encoding.
 1010  
      * <p>
 1011  
      * This method buffers the input internally, so there is no need to use a
 1012  
      * <code>BufferedInputStream</code>.
 1013  
      * </p>
 1014  
      * @param input  the <code>InputStream</code> to read from
 1015  
      * @param encoding  the encoding to use, null means platform default
 1016  
      * @return the requested String
 1017  
      * @throws NullPointerException if the input is null
 1018  
      * @throws IOException if an I/O error occurs
 1019  
      * @since 2.3
 1020  
      */
 1021  
     public static String toString(final InputStream input, final Charset encoding) throws IOException {
 1022  68
         final StringBuilderWriter sw = new StringBuilderWriter();
 1023  68
         copy(input, sw, encoding);
 1024  68
         return sw.toString();
 1025  
     }
 1026  
 
 1027  
     /**
 1028  
      * Gets the contents of an <code>InputStream</code> as a String
 1029  
      * using the specified character encoding.
 1030  
      * <p>
 1031  
      * Character encoding names can be found at
 1032  
      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
 1033  
      * <p>
 1034  
      * This method buffers the input internally, so there is no need to use a
 1035  
      * <code>BufferedInputStream</code>.
 1036  
      *
 1037  
      * @param input  the <code>InputStream</code> to read from
 1038  
      * @param encoding  the encoding to use, null means platform default
 1039  
      * @return the requested String
 1040  
      * @throws NullPointerException if the input is null
 1041  
      * @throws IOException if an I/O error occurs
 1042  
      * @throws UnsupportedCharsetException
 1043  
      *             thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not
 1044  
      *             supported.
 1045  
      */
 1046  
     public static String toString(final InputStream input, final String encoding)
 1047  
             throws IOException {
 1048  0
         return toString(input, Charsets.toCharset(encoding));
 1049  
     }
 1050  
 
 1051  
     /**
 1052  
      * Gets the contents of a <code>Reader</code> as a String.
 1053  
      * <p>
 1054  
      * This method buffers the input internally, so there is no need to use a
 1055  
      * <code>BufferedReader</code>.
 1056  
      *
 1057  
      * @param input  the <code>Reader</code> to read from
 1058  
      * @return the requested String
 1059  
      * @throws NullPointerException if the input is null
 1060  
      * @throws IOException if an I/O error occurs
 1061  
      */
 1062  
     public static String toString(final Reader input) throws IOException {
 1063  12
         final StringBuilderWriter sw = new StringBuilderWriter();
 1064  12
         copy(input, sw);
 1065  12
         return sw.toString();
 1066  
     }
 1067  
 
 1068  
     /**
 1069  
      * Gets the contents at the given URI.
 1070  
      *
 1071  
      * @param uri
 1072  
      *            The URI source.
 1073  
      * @return The contents of the URL as a String.
 1074  
      * @throws IOException if an I/O exception occurs.
 1075  
      * @since 2.1
 1076  
      * @deprecated 2.5 use {@link #toString(URI, Charset)} instead
 1077  
      */
 1078  
     @Deprecated
 1079  
     public static String toString(final URI uri) throws IOException {
 1080  2
         return toString(uri, Charset.defaultCharset());
 1081  
     }
 1082  
 
 1083  
     /**
 1084  
      * Gets the contents at the given URI.
 1085  
      *
 1086  
      * @param uri
 1087  
      *            The URI source.
 1088  
      * @param encoding
 1089  
      *            The encoding name for the URL contents.
 1090  
      * @return The contents of the URL as a String.
 1091  
      * @throws IOException if an I/O exception occurs.
 1092  
      * @since 2.3.
 1093  
      */
 1094  
     public static String toString(final URI uri, final Charset encoding) throws IOException {
 1095  6
         return toString(uri.toURL(), Charsets.toCharset(encoding));
 1096  
     }
 1097  
 
 1098  
     /**
 1099  
      * Gets the contents at the given URI.
 1100  
      *
 1101  
      * @param uri
 1102  
      *            The URI source.
 1103  
      * @param encoding
 1104  
      *            The encoding name for the URL contents.
 1105  
      * @return The contents of the URL as a String.
 1106  
      * @throws IOException if an I/O exception occurs.
 1107  
      * @throws UnsupportedCharsetException
 1108  
      *             thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not
 1109  
      *             supported.
 1110  
      * @since 2.1
 1111  
      */
 1112  
     public static String toString(final URI uri, final String encoding) throws IOException {
 1113  4
         return toString(uri, Charsets.toCharset(encoding));
 1114  
     }
 1115  
 
 1116  
     /**
 1117  
      * Gets the contents at the given URL.
 1118  
      *
 1119  
      * @param url
 1120  
      *            The URL source.
 1121  
      * @return The contents of the URL as a String.
 1122  
      * @throws IOException if an I/O exception occurs.
 1123  
      * @since 2.1
 1124  
      * @deprecated 2.5 use {@link #toString(URL, Charset)} instead
 1125  
      */
 1126  
     @Deprecated
 1127  
     public static String toString(final URL url) throws IOException {
 1128  2
         return toString(url, Charset.defaultCharset());
 1129  
     }
 1130  
 
 1131  
     /**
 1132  
      * Gets the contents at the given URL.
 1133  
      *
 1134  
      * @param url
 1135  
      *            The URL source.
 1136  
      * @param encoding
 1137  
      *            The encoding name for the URL contents.
 1138  
      * @return The contents of the URL as a String.
 1139  
      * @throws IOException if an I/O exception occurs.
 1140  
      * @since 2.3
 1141  
      */
 1142  
     public static String toString(final URL url, final Charset encoding) throws IOException {
 1143  12
         final InputStream inputStream = url.openStream();
 1144  
         try {
 1145  12
             return toString(inputStream, encoding);
 1146  
         } finally {
 1147  12
             inputStream.close();
 1148  
         }
 1149  
     }
 1150  
 
 1151  
     /**
 1152  
      * Gets the contents at the given URL.
 1153  
      *
 1154  
      * @param url
 1155  
      *            The URL source.
 1156  
      * @param encoding
 1157  
      *            The encoding name for the URL contents.
 1158  
      * @return The contents of the URL as a String.
 1159  
      * @throws IOException if an I/O exception occurs.
 1160  
      * @throws UnsupportedCharsetException
 1161  
      *             thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not
 1162  
      *             supported.
 1163  
      * @since 2.1
 1164  
      */
 1165  
     public static String toString(final URL url, final String encoding) throws IOException {
 1166  4
         return toString(url, Charsets.toCharset(encoding));
 1167  
     }
 1168  
 
 1169  
     /**
 1170  
      * Gets the contents of a <code>byte[]</code> as a String
 1171  
      * using the default character encoding of the platform.
 1172  
      *
 1173  
      * @param input the byte array to read from
 1174  
      * @return the requested String
 1175  
      * @throws NullPointerException if the input is null
 1176  
      * @throws IOException if an I/O error occurs (never occurs)
 1177  
      * @deprecated 2.5 Use {@link String#String(byte[])} instead
 1178  
      */
 1179  
     @Deprecated
 1180  
     public static String toString(final byte[] input) throws IOException {
 1181  
         // make explicit the use of the default charset
 1182  2
         return new String(input, Charset.defaultCharset());
 1183  
     }
 1184  
 
 1185  
     /**
 1186  
      * Gets the contents of a <code>byte[]</code> as a String
 1187  
      * using the specified character encoding.
 1188  
      * <p>
 1189  
      * Character encoding names can be found at
 1190  
      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
 1191  
      *
 1192  
      * @param input the byte array to read from
 1193  
      * @param encoding  the encoding to use, null means platform default
 1194  
      * @return the requested String
 1195  
      * @throws NullPointerException if the input is null
 1196  
      * @throws IOException if an I/O error occurs (never occurs)
 1197  
      */
 1198  
     public static String toString(final byte[] input, final String encoding) throws IOException {
 1199  0
         return new String(input, Charsets.toCharset(encoding));
 1200  
     }
 1201  
 
 1202  
     // readLines
 1203  
     //-----------------------------------------------------------------------
 1204  
     /**
 1205  
      * Gets the contents of an <code>InputStream</code> as a list of Strings,
 1206  
      * one entry per line, using the default character encoding of the platform.
 1207  
      * <p>
 1208  
      * This method buffers the input internally, so there is no need to use a
 1209  
      * <code>BufferedInputStream</code>.
 1210  
      *
 1211  
      * @param input  the <code>InputStream</code> to read from, not null
 1212  
      * @return the list of Strings, never null
 1213  
      * @throws NullPointerException if the input is null
 1214  
      * @throws IOException if an I/O error occurs
 1215  
      * @since 1.1
 1216  
      * @deprecated 2.5 use {@link #readLines(InputStream, Charset)} instead
 1217  
      */
 1218  
     @Deprecated
 1219  
     public static List<String> readLines(final InputStream input) throws IOException {
 1220  2
         return readLines(input, Charset.defaultCharset());
 1221  
     }
 1222  
 
 1223  
     /**
 1224  
      * Gets the contents of an <code>InputStream</code> as a list of Strings,
 1225  
      * one entry per line, using the specified character encoding.
 1226  
      * <p>
 1227  
      * This method buffers the input internally, so there is no need to use a
 1228  
      * <code>BufferedInputStream</code>.
 1229  
      *
 1230  
      * @param input  the <code>InputStream</code> to read from, not null
 1231  
      * @param encoding  the encoding to use, null means platform default
 1232  
      * @return the list of Strings, never null
 1233  
      * @throws NullPointerException if the input is null
 1234  
      * @throws IOException if an I/O error occurs
 1235  
      * @since 2.3
 1236  
      */
 1237  
     public static List<String> readLines(final InputStream input, final Charset encoding) throws IOException {
 1238  8
         final InputStreamReader reader = new InputStreamReader(input, Charsets.toCharset(encoding));
 1239  8
         return readLines(reader);
 1240  
     }
 1241  
 
 1242  
     /**
 1243  
      * Gets the contents of an <code>InputStream</code> as a list of Strings,
 1244  
      * one entry per line, using the specified character encoding.
 1245  
      * <p>
 1246  
      * Character encoding names can be found at
 1247  
      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
 1248  
      * <p>
 1249  
      * This method buffers the input internally, so there is no need to use a
 1250  
      * <code>BufferedInputStream</code>.
 1251  
      *
 1252  
      * @param input  the <code>InputStream</code> to read from, not null
 1253  
      * @param encoding  the encoding to use, null means platform default
 1254  
      * @return the list of Strings, never null
 1255  
      * @throws NullPointerException if the input is null
 1256  
      * @throws IOException if an I/O error occurs
 1257  
      * @throws UnsupportedCharsetException
 1258  
      *             thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not
 1259  
      *             supported.
 1260  
      * @since 1.1
 1261  
      */
 1262  
     public static List<String> readLines(final InputStream input, final String encoding) throws IOException {
 1263  2
         return readLines(input, Charsets.toCharset(encoding));
 1264  
     }
 1265  
 
 1266  
     /**
 1267  
      * Gets the contents of a <code>Reader</code> as a list of Strings,
 1268  
      * one entry per line.
 1269  
      * <p>
 1270  
      * This method buffers the input internally, so there is no need to use a
 1271  
      * <code>BufferedReader</code>.
 1272  
      *
 1273  
      * @param input  the <code>Reader</code> to read from, not null
 1274  
      * @return the list of Strings, never null
 1275  
      * @throws NullPointerException if the input is null
 1276  
      * @throws IOException if an I/O error occurs
 1277  
      * @since 1.1
 1278  
      */
 1279  
     public static List<String> readLines(final Reader input) throws IOException {
 1280  10
         final BufferedReader reader = toBufferedReader(input);
 1281  10
         final List<String> list = new ArrayList<String>();
 1282  10
         String line = reader.readLine();
 1283  56
         while (line != null) {
 1284  46
             list.add(line);
 1285  46
             line = reader.readLine();
 1286  
         }
 1287  10
         return list;
 1288  
     }
 1289  
 
 1290  
     // lineIterator
 1291  
     //-----------------------------------------------------------------------
 1292  
     /**
 1293  
      * Returns an Iterator for the lines in a <code>Reader</code>.
 1294  
      * <p>
 1295  
      * <code>LineIterator</code> holds a reference to the open
 1296  
      * <code>Reader</code> specified here. When you have finished with the
 1297  
      * iterator you should close the reader to free internal resources.
 1298  
      * This can be done by closing the reader directly, or by calling
 1299  
      * {@link LineIterator#close()} or {@link LineIterator#closeQuietly(LineIterator)}.
 1300  
      * <p>
 1301  
      * The recommended usage pattern is:
 1302  
      * <pre>
 1303  
      * try {
 1304  
      *   LineIterator it = IOUtils.lineIterator(reader);
 1305  
      *   while (it.hasNext()) {
 1306  
      *     String line = it.nextLine();
 1307  
      *     /// do something with line
 1308  
      *   }
 1309  
      * } finally {
 1310  
      *   IOUtils.closeQuietly(reader);
 1311  
      * }
 1312  
      * </pre>
 1313  
      *
 1314  
      * @param reader  the <code>Reader</code> to read from, not null
 1315  
      * @return an Iterator of the lines in the reader, never null
 1316  
      * @throws IllegalArgumentException if the reader is null
 1317  
      * @since 1.2
 1318  
      */
 1319  
     public static LineIterator lineIterator(final Reader reader) {
 1320  0
         return new LineIterator(reader);
 1321  
     }
 1322  
 
 1323  
     /**
 1324  
      * Returns an Iterator for the lines in an <code>InputStream</code>, using
 1325  
      * the character encoding specified (or default encoding if null).
 1326  
      * <p>
 1327  
      * <code>LineIterator</code> holds a reference to the open
 1328  
      * <code>InputStream</code> specified here. When you have finished with
 1329  
      * the iterator you should close the stream to free internal resources.
 1330  
      * This can be done by closing the stream directly, or by calling
 1331  
      * {@link LineIterator#close()} or {@link LineIterator#closeQuietly(LineIterator)}.
 1332  
      * <p>
 1333  
      * The recommended usage pattern is:
 1334  
      * <pre>
 1335  
      * try {
 1336  
      *   LineIterator it = IOUtils.lineIterator(stream, charset);
 1337  
      *   while (it.hasNext()) {
 1338  
      *     String line = it.nextLine();
 1339  
      *     /// do something with line
 1340  
      *   }
 1341  
      * } finally {
 1342  
      *   IOUtils.closeQuietly(stream);
 1343  
      * }
 1344  
      * </pre>
 1345  
      *
 1346  
      * @param input  the <code>InputStream</code> to read from, not null
 1347  
      * @param encoding  the encoding to use, null means platform default
 1348  
      * @return an Iterator of the lines in the reader, never null
 1349  
      * @throws IllegalArgumentException if the input is null
 1350  
      * @throws IOException if an I/O error occurs, such as if the encoding is invalid
 1351  
      * @since 2.3
 1352  
      */
 1353  
     public static LineIterator lineIterator(final InputStream input, final Charset encoding) throws IOException {
 1354  20
         return new LineIterator(new InputStreamReader(input, Charsets.toCharset(encoding)));
 1355  
     }
 1356  
 
 1357  
     /**
 1358  
      * Returns an Iterator for the lines in an <code>InputStream</code>, using
 1359  
      * the character encoding specified (or default encoding if null).
 1360  
      * <p>
 1361  
      * <code>LineIterator</code> holds a reference to the open
 1362  
      * <code>InputStream</code> specified here. When you have finished with
 1363  
      * the iterator you should close the stream to free internal resources.
 1364  
      * This can be done by closing the stream directly, or by calling
 1365  
      * {@link LineIterator#close()} or {@link LineIterator#closeQuietly(LineIterator)}.
 1366  
      * <p>
 1367  
      * The recommended usage pattern is:
 1368  
      * <pre>
 1369  
      * try {
 1370  
      *   LineIterator it = IOUtils.lineIterator(stream, "UTF-8");
 1371  
      *   while (it.hasNext()) {
 1372  
      *     String line = it.nextLine();
 1373  
      *     /// do something with line
 1374  
      *   }
 1375  
      * } finally {
 1376  
      *   IOUtils.closeQuietly(stream);
 1377  
      * }
 1378  
      * </pre>
 1379  
      *
 1380  
      * @param input  the <code>InputStream</code> to read from, not null
 1381  
      * @param encoding  the encoding to use, null means platform default
 1382  
      * @return an Iterator of the lines in the reader, never null
 1383  
      * @throws IllegalArgumentException if the input is null
 1384  
      * @throws IOException if an I/O error occurs, such as if the encoding is invalid
 1385  
      * @throws UnsupportedCharsetException
 1386  
      *             thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not
 1387  
      *             supported.
 1388  
      * @since 1.2
 1389  
      */
 1390  
     public static LineIterator lineIterator(final InputStream input, final String encoding) throws IOException {
 1391  22
         return lineIterator(input, Charsets.toCharset(encoding));
 1392  
     }
 1393  
 
 1394  
     //-----------------------------------------------------------------------
 1395  
     /**
 1396  
      * Converts the specified CharSequence to an input stream, encoded as bytes
 1397  
      * using the default character encoding of the platform.
 1398  
      *
 1399  
      * @param input the CharSequence to convert
 1400  
      * @return an input stream
 1401  
      * @since 2.0
 1402  
      * @deprecated 2.5 use {@link #toInputStream(CharSequence, Charset)} instead
 1403  
      */
 1404  
     @Deprecated
 1405  
     public static InputStream toInputStream(final CharSequence input) {
 1406  2
         return toInputStream(input, Charset.defaultCharset());
 1407  
     }
 1408  
 
 1409  
     /**
 1410  
      * Converts the specified CharSequence to an input stream, encoded as bytes
 1411  
      * using the specified character encoding.
 1412  
      *
 1413  
      * @param input the CharSequence to convert
 1414  
      * @param encoding the encoding to use, null means platform default
 1415  
      * @return an input stream
 1416  
      * @since 2.3
 1417  
      */
 1418  
     public static InputStream toInputStream(final CharSequence input, final Charset encoding) {
 1419  6
         return toInputStream(input.toString(), encoding);
 1420  
     }
 1421  
 
 1422  
     /**
 1423  
      * Converts the specified CharSequence to an input stream, encoded as bytes
 1424  
      * using the specified character encoding.
 1425  
      * <p>
 1426  
      * Character encoding names can be found at
 1427  
      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
 1428  
      *
 1429  
      * @param input the CharSequence to convert
 1430  
      * @param encoding the encoding to use, null means platform default
 1431  
      * @return an input stream
 1432  
      * @throws IOException if the encoding is invalid
 1433  
      * @throws UnsupportedCharsetException
 1434  
      *             thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not
 1435  
      *             supported.
 1436  
      * @since 2.0
 1437  
      */
 1438  
     public static InputStream toInputStream(final CharSequence input, final String encoding) throws IOException {
 1439  4
         return toInputStream(input, Charsets.toCharset(encoding));
 1440  
     }
 1441  
 
 1442  
     //-----------------------------------------------------------------------
 1443  
     /**
 1444  
      * Converts the specified string to an input stream, encoded as bytes
 1445  
      * using the default character encoding of the platform.
 1446  
      *
 1447  
      * @param input the string to convert
 1448  
      * @return an input stream
 1449  
      * @since 1.1
 1450  
      * @deprecated 2.5 use {@link #toInputStream(String, Charset)} instead
 1451  
      */
 1452  
     @Deprecated
 1453  
     public static InputStream toInputStream(final String input) {
 1454  2
         return toInputStream(input, Charset.defaultCharset());
 1455  
     }
 1456  
 
 1457  
     /**
 1458  
      * Converts the specified string to an input stream, encoded as bytes
 1459  
      * using the specified character encoding.
 1460  
      *
 1461  
      * @param input the string to convert
 1462  
      * @param encoding the encoding to use, null means platform default
 1463  
      * @return an input stream
 1464  
      * @since 2.3
 1465  
      */
 1466  
     public static InputStream toInputStream(final String input, final Charset encoding) {
 1467  8
         return new ByteArrayInputStream(input.getBytes(Charsets.toCharset(encoding)));
 1468  
     }
 1469  
 
 1470  
     /**
 1471  
      * Converts the specified string to an input stream, encoded as bytes
 1472  
      * using the specified character encoding.
 1473  
      * <p>
 1474  
      * Character encoding names can be found at
 1475  
      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
 1476  
      *
 1477  
      * @param input the string to convert
 1478  
      * @param encoding the encoding to use, null means platform default
 1479  
      * @return an input stream
 1480  
      * @throws IOException if the encoding is invalid
 1481  
      * @throws UnsupportedCharsetException
 1482  
      *             thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not
 1483  
      *             supported.
 1484  
      * @since 1.1
 1485  
      */
 1486  
     public static InputStream toInputStream(final String input, final String encoding) throws IOException {
 1487  4
         final byte[] bytes = input.getBytes(Charsets.toCharset(encoding));
 1488  4
         return new ByteArrayInputStream(bytes);
 1489  
     }
 1490  
 
 1491  
     // write byte[]
 1492  
     //-----------------------------------------------------------------------
 1493  
     /**
 1494  
      * Writes bytes from a <code>byte[]</code> to an <code>OutputStream</code>.
 1495  
      *
 1496  
      * @param data  the byte array to write, do not modify during output,
 1497  
      * null ignored
 1498  
      * @param output  the <code>OutputStream</code> to write to
 1499  
      * @throws NullPointerException if output is null
 1500  
      * @throws IOException if an I/O error occurs
 1501  
      * @since 1.1
 1502  
      */
 1503  
     public static void write(final byte[] data, final OutputStream output)
 1504  
             throws IOException {
 1505  12
         if (data != null) {
 1506  10
             output.write(data);
 1507  
         }
 1508  10
     }
 1509  
 
 1510  
     /**
 1511  
      * Writes bytes from a <code>byte[]</code> to an <code>OutputStream</code> using chunked writes.
 1512  
      * This is intended for writing very large byte arrays which might otherwise cause excessive
 1513  
      * memory usage if the native code has to allocate a copy.
 1514  
      *
 1515  
      * @param data  the byte array to write, do not modify during output,
 1516  
      * null ignored
 1517  
      * @param output  the <code>OutputStream</code> to write to
 1518  
      * @throws NullPointerException if output is null
 1519  
      * @throws IOException if an I/O error occurs
 1520  
      * @since 2.5
 1521  
      */
 1522  
     public static void writeChunked(final byte[] data, final OutputStream output)
 1523  
             throws IOException {
 1524  0
         if (data != null) {
 1525  0
             int bytes = data.length;
 1526  0
             int offset = 0;
 1527  0
             while(bytes > 0) {
 1528  0
                 int chunk = Math.min(bytes, DEFAULT_BUFFER_SIZE);
 1529  0
                 output.write(data, offset, chunk);
 1530  0
                 bytes -= chunk;
 1531  0
                 offset += chunk;
 1532  0
             }
 1533  
         }
 1534  0
     }
 1535  
 
 1536  
     /**
 1537  
      * Writes bytes from a <code>byte[]</code> to chars on a <code>Writer</code>
 1538  
      * using the default character encoding of the platform.
 1539  
      * <p>
 1540  
      * This method uses {@link String#String(byte[])}.
 1541  
      *
 1542  
      * @param data  the byte array to write, do not modify during output,
 1543  
      * null ignored
 1544  
      * @param output  the <code>Writer</code> to write to
 1545  
      * @throws NullPointerException if output is null
 1546  
      * @throws IOException if an I/O error occurs
 1547  
      * @since 1.1
 1548  
      * @deprecated 2.5 use {@link #write(byte[], Writer, Charset)} instead
 1549  
      */
 1550  
     @Deprecated
 1551  
     public static void write(final byte[] data, final Writer output) throws IOException {
 1552  6
         write(data, output, Charset.defaultCharset());
 1553  4
     }
 1554  
 
 1555  
     /**
 1556  
      * Writes bytes from a <code>byte[]</code> to chars on a <code>Writer</code>
 1557  
      * using the specified character encoding.
 1558  
      * <p>
 1559  
      * This method uses {@link String#String(byte[], String)}.
 1560  
      *
 1561  
      * @param data  the byte array to write, do not modify during output,
 1562  
      * null ignored
 1563  
      * @param output  the <code>Writer</code> to write to
 1564  
      * @param encoding  the encoding to use, null means platform default
 1565  
      * @throws NullPointerException if output is null
 1566  
      * @throws IOException if an I/O error occurs
 1567  
      * @since 2.3
 1568  
      */
 1569  
     public static void write(final byte[] data, final Writer output, final Charset encoding) throws IOException {
 1570  14
         if (data != null) {
 1571  10
             output.write(new String(data, Charsets.toCharset(encoding)));
 1572  
         }
 1573  10
     }
 1574  
 
 1575  
     /**
 1576  
      * Writes bytes from a <code>byte[]</code> to chars on a <code>Writer</code>
 1577  
      * using the specified character encoding.
 1578  
      * <p>
 1579  
      * Character encoding names can be found at
 1580  
      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
 1581  
      * <p>
 1582  
      * This method uses {@link String#String(byte[], String)}.
 1583  
      *
 1584  
      * @param data  the byte array to write, do not modify during output,
 1585  
      * null ignored
 1586  
      * @param output  the <code>Writer</code> to write to
 1587  
      * @param encoding  the encoding to use, null means platform default
 1588  
      * @throws NullPointerException if output is null
 1589  
      * @throws IOException if an I/O error occurs
 1590  
      * @throws UnsupportedCharsetException
 1591  
      *             thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not
 1592  
      *             supported.
 1593  
      * @since 1.1
 1594  
      */
 1595  
     public static void write(final byte[] data, final Writer output, final String encoding) throws IOException {
 1596  8
         write(data, output, Charsets.toCharset(encoding));
 1597  6
     }
 1598  
 
 1599  
     // write char[]
 1600  
     //-----------------------------------------------------------------------
 1601  
     /**
 1602  
      * Writes chars from a <code>char[]</code> to a <code>Writer</code>
 1603  
      *
 1604  
      * @param data  the char array to write, do not modify during output,
 1605  
      * null ignored
 1606  
      * @param output  the <code>Writer</code> to write to
 1607  
      * @throws NullPointerException if output is null
 1608  
      * @throws IOException if an I/O error occurs
 1609  
      * @since 1.1
 1610  
      */
 1611  
     public static void write(final char[] data, final Writer output) throws IOException {
 1612  6
         if (data != null) {
 1613  4
             output.write(data);
 1614  
         }
 1615  4
     }
 1616  
 
 1617  
     /**
 1618  
      * Writes chars from a <code>char[]</code> to a <code>Writer</code> using chunked writes.
 1619  
      * This is intended for writing very large byte arrays which might otherwise cause excessive
 1620  
      * memory usage if the native code has to allocate a copy.
 1621  
      *
 1622  
      * @param data  the char array to write, do not modify during output,
 1623  
      * null ignored
 1624  
      * @param output  the <code>Writer</code> to write to
 1625  
      * @throws NullPointerException if output is null
 1626  
      * @throws IOException if an I/O error occurs
 1627  
      * @since 2.5
 1628  
      */
 1629  
     public static void writeChunked(final char[] data, final Writer output) throws IOException {
 1630  0
         if (data != null) {
 1631  0
             int bytes = data.length;
 1632  0
             int offset = 0;
 1633  0
             while(bytes > 0) {
 1634  0
                 int chunk = Math.min(bytes, DEFAULT_BUFFER_SIZE);
 1635  0
                 output.write(data, offset, chunk);
 1636  0
                 bytes -= chunk;
 1637  0
                 offset += chunk;
 1638  0
             }
 1639  
         }
 1640  0
     }
 1641  
 
 1642  
     /**
 1643  
      * Writes chars from a <code>char[]</code> to bytes on an
 1644  
      * <code>OutputStream</code>.
 1645  
      * <p>
 1646  
      * This method uses {@link String#String(char[])} and
 1647  
      * {@link String#getBytes()}.
 1648  
      *
 1649  
      * @param data  the char array to write, do not modify during output,
 1650  
      * null ignored
 1651  
      * @param output  the <code>OutputStream</code> to write to
 1652  
      * @throws NullPointerException if output is null
 1653  
      * @throws IOException if an I/O error occurs
 1654  
      * @since 1.1
 1655  
      * @deprecated 2.5 use {@link #write(char[], OutputStream, Charset)} instead
 1656  
      */
 1657  
     @Deprecated
 1658  
     public static void write(final char[] data, final OutputStream output)
 1659  
             throws IOException {
 1660  10
         write(data, output, Charset.defaultCharset());
 1661  6
     }
 1662  
 
 1663  
     /**
 1664  
      * Writes chars from a <code>char[]</code> to bytes on an
 1665  
      * <code>OutputStream</code> using the specified character encoding.
 1666  
      * <p>
 1667  
      * This method uses {@link String#String(char[])} and
 1668  
      * {@link String#getBytes(String)}.
 1669  
      *
 1670  
      * @param data  the char array to write, do not modify during output,
 1671  
      * null ignored
 1672  
      * @param output  the <code>OutputStream</code> to write to
 1673  
      * @param encoding  the encoding to use, null means platform default
 1674  
      * @throws NullPointerException if output is null
 1675  
      * @throws IOException if an I/O error occurs
 1676  
      * @since 2.3
 1677  
      */
 1678  
     public static void write(final char[] data, final OutputStream output, final Charset encoding) throws IOException {
 1679  14
         if (data != null) {
 1680  10
             output.write(new String(data).getBytes(Charsets.toCharset(encoding)));
 1681  
         }
 1682  10
     }
 1683  
 
 1684  
     /**
 1685  
      * Writes chars from a <code>char[]</code> to bytes on an
 1686  
      * <code>OutputStream</code> using the specified character encoding.
 1687  
      * <p>
 1688  
      * Character encoding names can be found at
 1689  
      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
 1690  
      * <p>
 1691  
      * This method uses {@link String#String(char[])} and
 1692  
      * {@link String#getBytes(String)}.
 1693  
      *
 1694  
      * @param data  the char array to write, do not modify during output,
 1695  
      * null ignored
 1696  
      * @param output  the <code>OutputStream</code> to write to
 1697  
      * @param encoding  the encoding to use, null means platform default
 1698  
      * @throws NullPointerException if output is null
 1699  
      * @throws IOException if an I/O error occurs
 1700  
      * @throws UnsupportedCharsetException
 1701  
      *             thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not
 1702  
      *             supported.
 1703  
      * @since 1.1
 1704  
      */
 1705  
     public static void write(final char[] data, final OutputStream output, final String encoding)
 1706  
             throws IOException {
 1707  4
         write(data, output, Charsets.toCharset(encoding));
 1708  4
     }
 1709  
 
 1710  
     // write CharSequence
 1711  
     //-----------------------------------------------------------------------
 1712  
     /**
 1713  
      * Writes chars from a <code>CharSequence</code> to a <code>Writer</code>.
 1714  
      *
 1715  
      * @param data  the <code>CharSequence</code> to write, null ignored
 1716  
      * @param output  the <code>Writer</code> to write to
 1717  
      * @throws NullPointerException if output is null
 1718  
      * @throws IOException if an I/O error occurs
 1719  
      * @since 2.0
 1720  
      */
 1721  
     public static void write(final CharSequence data, final Writer output) throws IOException {
 1722  6
         if (data != null) {
 1723  4
             write(data.toString(), output);
 1724  
         }
 1725  4
     }
 1726  
 
 1727  
     /**
 1728  
      * Writes chars from a <code>CharSequence</code> to bytes on an
 1729  
      * <code>OutputStream</code> using the default character encoding of the
 1730  
      * platform.
 1731  
      * <p>
 1732  
      * This method uses {@link String#getBytes()}.
 1733  
      *
 1734  
      * @param data  the <code>CharSequence</code> to write, null ignored
 1735  
      * @param output  the <code>OutputStream</code> to write to
 1736  
      * @throws NullPointerException if output is null
 1737  
      * @throws IOException if an I/O error occurs
 1738  
      * @since 2.0
 1739  
      * @deprecated 2.5 use {@link #write(CharSequence, OutputStream, Charset)} instead
 1740  
      */
 1741  
     @Deprecated
 1742  
     public static void write(final CharSequence data, final OutputStream output)
 1743  
             throws IOException {
 1744  10
         write(data, output, Charset.defaultCharset());
 1745  6
     }
 1746  
 
 1747  
     /**
 1748  
      * Writes chars from a <code>CharSequence</code> to bytes on an
 1749  
      * <code>OutputStream</code> using the specified character encoding.
 1750  
      * <p>
 1751  
      * This method uses {@link String#getBytes(String)}.
 1752  
      *
 1753  
      * @param data  the <code>CharSequence</code> to write, null ignored
 1754  
      * @param output  the <code>OutputStream</code> to write to
 1755  
      * @param encoding  the encoding to use, null means platform default
 1756  
      * @throws NullPointerException if output is null
 1757  
      * @throws IOException if an I/O error occurs
 1758  
      * @since 2.3
 1759  
      */
 1760  
     public static void write(final CharSequence data, final OutputStream output, final Charset encoding) throws IOException {
 1761  14
         if (data != null) {
 1762  10
             write(data.toString(), output, encoding);
 1763  
         }
 1764  10
     }
 1765  
 
 1766  
     /**
 1767  
      * Writes chars from a <code>CharSequence</code> to bytes on an
 1768  
      * <code>OutputStream</code> using the specified character encoding.
 1769  
      * <p>
 1770  
      * Character encoding names can be found at
 1771  
      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
 1772  
      * <p>
 1773  
      * This method uses {@link String#getBytes(String)}.
 1774  
      *
 1775  
      * @param data  the <code>CharSequence</code> to write, null ignored
 1776  
      * @param output  the <code>OutputStream</code> to write to
 1777  
      * @param encoding  the encoding to use, null means platform default
 1778  
      * @throws NullPointerException if output is null
 1779  
      * @throws IOException if an I/O error occurs
 1780  
      * @throws UnsupportedCharsetException
 1781  
      *             thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not
 1782  
      *             supported.
 1783  
      * @since 2.0
 1784  
      */
 1785  
     public static void write(final CharSequence data, final OutputStream output, final String encoding) throws IOException {
 1786  4
         write(data, output, Charsets.toCharset(encoding));
 1787  4
     }
 1788  
 
 1789  
     // write String
 1790  
     //-----------------------------------------------------------------------
 1791  
     /**
 1792  
      * Writes chars from a <code>String</code> to a <code>Writer</code>.
 1793  
      *
 1794  
      * @param data  the <code>String</code> to write, null ignored
 1795  
      * @param output  the <code>Writer</code> to write to
 1796  
      * @throws NullPointerException if output is null
 1797  
      * @throws IOException if an I/O error occurs
 1798  
      * @since 1.1
 1799  
      */
 1800  
     public static void write(final String data, final Writer output) throws IOException {
 1801  10
         if (data != null) {
 1802  8
             output.write(data);
 1803  
         }
 1804  6
     }
 1805  
 
 1806  
     /**
 1807  
      * Writes chars from a <code>String</code> to bytes on an
 1808  
      * <code>OutputStream</code> using the default character encoding of the
 1809  
      * platform.
 1810  
      * <p>
 1811  
      * This method uses {@link String#getBytes()}.
 1812  
      *
 1813  
      * @param data  the <code>String</code> to write, null ignored
 1814  
      * @param output  the <code>OutputStream</code> to write to
 1815  
      * @throws NullPointerException if output is null
 1816  
      * @throws IOException if an I/O error occurs
 1817  
      * @since 1.1
 1818  
      * @deprecated 2.5 use {@link #write(String, OutputStream, Charset)} instead
 1819  
      */
 1820  
     @Deprecated
 1821  
     public static void write(final String data, final OutputStream output)
 1822  
             throws IOException {
 1823  10
         write(data, output, Charset.defaultCharset());
 1824  6
     }
 1825  
 
 1826  
     /**
 1827  
      * Writes chars from a <code>String</code> to bytes on an
 1828  
      * <code>OutputStream</code> using the specified character encoding.
 1829  
      * <p>
 1830  
      * This method uses {@link String#getBytes(String)}.
 1831  
      *
 1832  
      * @param data  the <code>String</code> to write, null ignored
 1833  
      * @param output  the <code>OutputStream</code> to write to
 1834  
      * @param encoding  the encoding to use, null means platform default
 1835  
      * @throws NullPointerException if output is null
 1836  
      * @throws IOException if an I/O error occurs
 1837  
      * @since 2.3
 1838  
      */
 1839  
     public static void write(final String data, final OutputStream output, final Charset encoding) throws IOException {
 1840  158
         if (data != null) {
 1841  154
             output.write(data.getBytes(Charsets.toCharset(encoding)));
 1842  
         }
 1843  150
     }
 1844  
 
 1845  
     /**
 1846  
      * Writes chars from a <code>String</code> to bytes on an
 1847  
      * <code>OutputStream</code> using the specified character encoding.
 1848  
      * <p>
 1849  
      * Character encoding names can be found at
 1850  
      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
 1851  
      * <p>
 1852  
      * This method uses {@link String#getBytes(String)}.
 1853  
      *
 1854  
      * @param data  the <code>String</code> to write, null ignored
 1855  
      * @param output  the <code>OutputStream</code> to write to
 1856  
      * @param encoding  the encoding to use, null means platform default
 1857  
      * @throws NullPointerException if output is null
 1858  
      * @throws IOException if an I/O error occurs
 1859  
      * @throws UnsupportedCharsetException
 1860  
      *             thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not
 1861  
      *             supported.
 1862  
      * @since 1.1
 1863  
      */
 1864  
     public static void write(final String data, final OutputStream output, final String encoding)
 1865  
             throws IOException {
 1866  4
         write(data, output, Charsets.toCharset(encoding));
 1867  4
     }
 1868  
 
 1869  
     // write StringBuffer
 1870  
     //-----------------------------------------------------------------------
 1871  
     /**
 1872  
      * Writes chars from a <code>StringBuffer</code> to a <code>Writer</code>.
 1873  
      *
 1874  
      * @param data  the <code>StringBuffer</code> to write, null ignored
 1875  
      * @param output  the <code>Writer</code> to write to
 1876  
      * @throws NullPointerException if output is null
 1877  
      * @throws IOException if an I/O error occurs
 1878  
      * @since 1.1
 1879  
      * @deprecated replaced by write(CharSequence, Writer)
 1880  
      */
 1881  
     @Deprecated
 1882  
     public static void write(final StringBuffer data, final Writer output)
 1883  
             throws IOException {
 1884  0
         if (data != null) {
 1885  0
             output.write(data.toString());
 1886  
         }
 1887  0
     }
 1888  
 
 1889  
     /**
 1890  
      * Writes chars from a <code>StringBuffer</code> to bytes on an
 1891  
      * <code>OutputStream</code> using the default character encoding of the
 1892  
      * platform.
 1893  
      * <p>
 1894  
      * This method uses {@link String#getBytes()}.
 1895  
      *
 1896  
      * @param data  the <code>StringBuffer</code> to write, null ignored
 1897  
      * @param output  the <code>OutputStream</code> to write to
 1898  
      * @throws NullPointerException if output is null
 1899  
      * @throws IOException if an I/O error occurs
 1900  
      * @since 1.1
 1901  
      * @deprecated replaced by write(CharSequence, OutputStream)
 1902  
      */
 1903  
     @Deprecated
 1904  
     public static void write(final StringBuffer data, final OutputStream output)
 1905  
             throws IOException {
 1906  0
         write(data, output, (String) null);
 1907  0
     }
 1908  
 
 1909  
     /**
 1910  
      * Writes chars from a <code>StringBuffer</code> to bytes on an
 1911  
      * <code>OutputStream</code> using the specified character encoding.
 1912  
      * <p>
 1913  
      * Character encoding names can be found at
 1914  
      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
 1915  
      * <p>
 1916  
      * This method uses {@link String#getBytes(String)}.
 1917  
      *
 1918  
      * @param data  the <code>StringBuffer</code> to write, null ignored
 1919  
      * @param output  the <code>OutputStream</code> to write to
 1920  
      * @param encoding  the encoding to use, null means platform default
 1921  
      * @throws NullPointerException if output is null
 1922  
      * @throws IOException if an I/O error occurs
 1923  
      * @throws UnsupportedCharsetException
 1924  
      *             thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not
 1925  
      *             supported.
 1926  
      * @since 1.1
 1927  
      * @deprecated replaced by write(CharSequence, OutputStream, String)
 1928  
      */
 1929  
     @Deprecated
 1930  
     public static void write(final StringBuffer data, final OutputStream output, final String encoding) throws IOException {
 1931  0
         if (data != null) {
 1932  0
             output.write(data.toString().getBytes(Charsets.toCharset(encoding)));
 1933  
         }
 1934  0
     }
 1935  
 
 1936  
     // writeLines
 1937  
     //-----------------------------------------------------------------------
 1938  
     /**
 1939  
      * Writes the <code>toString()</code> value of each item in a collection to
 1940  
      * an <code>OutputStream</code> line by line, using the default character
 1941  
      * encoding of the platform and the specified line ending.
 1942  
      *
 1943  
      * @param lines  the lines to write, null entries produce blank lines
 1944  
      * @param lineEnding  the line separator to use, null is system default
 1945  
      * @param output  the <code>OutputStream</code> to write to, not null, not closed
 1946  
      * @throws NullPointerException if the output is null
 1947  
      * @throws IOException if an I/O error occurs
 1948  
      * @since 1.1
 1949  
      * @deprecated 2.5 use {@link #writeLines(Collection, String, OutputStream, Charset)} instead
 1950  
      */
 1951  
     @Deprecated
 1952  
     public static void writeLines(final Collection<?> lines, final String lineEnding,
 1953  
             final OutputStream output) throws IOException {
 1954  8
         writeLines(lines, lineEnding, output, Charset.defaultCharset());
 1955  6
     }
 1956  
 
 1957  
     /**
 1958  
      * Writes the <code>toString()</code> value of each item in a collection to
 1959  
      * an <code>OutputStream</code> line by line, using the specified character
 1960  
      * encoding and the specified line ending.
 1961  
      *
 1962  
      * @param lines  the lines to write, null entries produce blank lines
 1963  
      * @param lineEnding  the line separator to use, null is system default
 1964  
      * @param output  the <code>OutputStream</code> to write to, not null, not closed
 1965  
      * @param encoding  the encoding to use, null means platform default
 1966  
      * @throws NullPointerException if the output is null
 1967  
      * @throws IOException if an I/O error occurs
 1968  
      * @since 2.3
 1969  
      */
 1970  
     public static void writeLines(final Collection<?> lines, String lineEnding, final OutputStream output, final Charset encoding)
 1971  
             throws IOException {
 1972  68
         if (lines == null) {
 1973  6
             return;
 1974  
         }
 1975  62
         if (lineEnding == null) {
 1976  50
             lineEnding = LINE_SEPARATOR;
 1977  
         }
 1978  62
         final Charset cs = Charsets.toCharset(encoding);
 1979  62
         for (final Object line : lines) {
 1980  206
             if (line != null) {
 1981  194
                 output.write(line.toString().getBytes(cs));
 1982  
             }
 1983  202
             output.write(lineEnding.getBytes(cs));
 1984  202
         }
 1985  58
     }
 1986  
 
 1987  
     /**
 1988  
      * Writes the <code>toString()</code> value of each item in a collection to
 1989  
      * an <code>OutputStream</code> line by line, using the specified character
 1990  
      * encoding and the specified line ending.
 1991  
      * <p>
 1992  
      * Character encoding names can be found at
 1993  
      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
 1994  
      *
 1995  
      * @param lines  the lines to write, null entries produce blank lines
 1996  
      * @param lineEnding  the line separator to use, null is system default
 1997  
      * @param output  the <code>OutputStream</code> to write to, not null, not closed
 1998  
      * @param encoding  the encoding to use, null means platform default
 1999  
      * @throws NullPointerException if the output is null
 2000  
      * @throws IOException if an I/O error occurs
 2001  
      * @throws UnsupportedCharsetException
 2002  
      *             thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not
 2003  
      *             supported.
 2004  
      * @since 1.1
 2005  
      */
 2006  
     public static void writeLines(final Collection<?> lines, final String lineEnding,
 2007  
             final OutputStream output, final String encoding) throws IOException {
 2008  60
         writeLines(lines, lineEnding, output, Charsets.toCharset(encoding));
 2009  58
     }
 2010  
 
 2011  
     /**
 2012  
      * Writes the <code>toString()</code> value of each item in a collection to
 2013  
      * a <code>Writer</code> line by line, using the specified line ending.
 2014  
      *
 2015  
      * @param lines  the lines to write, null entries produce blank lines
 2016  
      * @param lineEnding  the line separator to use, null is system default
 2017  
      * @param writer  the <code>Writer</code> to write to, not null, not closed
 2018  
      * @throws NullPointerException if the input is null
 2019  
      * @throws IOException if an I/O error occurs
 2020  
      * @since 1.1
 2021  
      */
 2022  
     public static void writeLines(final Collection<?> lines, String lineEnding,
 2023  
             final Writer writer) throws IOException {
 2024  8
         if (lines == null) {
 2025  2
             return;
 2026  
         }
 2027  6
         if (lineEnding == null) {
 2028  2
             lineEnding = LINE_SEPARATOR;
 2029  
         }
 2030  6
         for (final Object line : lines) {
 2031  18
             if (line != null) {
 2032  16
                 writer.write(line.toString());
 2033  
             }
 2034  16
             writer.write(lineEnding);
 2035  16
         }
 2036  4
     }
 2037  
 
 2038  
     // copy from InputStream
 2039  
     //-----------------------------------------------------------------------
 2040  
     /**
 2041  
      * Copies bytes from an <code>InputStream</code> to an
 2042  
      * <code>OutputStream</code>.
 2043  
      * <p>
 2044  
      * This method buffers the input internally, so there is no need to use a
 2045  
      * <code>BufferedInputStream</code>.
 2046  
      * <p>
 2047  
      * Large streams (over 2GB) will return a bytes copied value of
 2048  
      * <code>-1</code> after the copy has completed since the correct
 2049  
      * number of bytes cannot be returned as an int. For large streams
 2050  
      * use the <code>copyLarge(InputStream, OutputStream)</code> method.
 2051  
      *
 2052  
      * @param input  the <code>InputStream</code> to read from
 2053  
      * @param output  the <code>OutputStream</code> to write to
 2054  
      * @return the number of bytes copied, or -1 if &gt; Integer.MAX_VALUE
 2055  
      * @throws NullPointerException if the input or output is null
 2056  
      * @throws IOException if an I/O error occurs
 2057  
      * @since 1.1
 2058  
      */
 2059  
     public static int copy(final InputStream input, final OutputStream output) throws IOException {
 2060  78
         final long count = copyLarge(input, output);
 2061  72
         if (count > Integer.MAX_VALUE) {
 2062  2
             return -1;
 2063  
         }
 2064  70
         return (int) count;
 2065  
     }
 2066  
 
 2067  
     /**
 2068  
      * Copies bytes from an <code>InputStream</code> to an <code>OutputStream</code> using an internal buffer of the
 2069  
      * given size.
 2070  
      * <p>
 2071  
      * This method buffers the input internally, so there is no need to use a <code>BufferedInputStream</code>.
 2072  
      * <p>
 2073  
      *
 2074  
      * @param input
 2075  
      *            the <code>InputStream</code> to read from
 2076  
      * @param output
 2077  
      *            the <code>OutputStream</code> to write to
 2078  
      * @param bufferSize
 2079  
      *            the bufferSize used to copy from the input to the output
 2080  
      * @return the number of bytes copied
 2081  
      * @throws NullPointerException
 2082  
      *             if the input or output is null
 2083  
      * @throws IOException
 2084  
      *             if an I/O error occurs
 2085  
      * @since 2.5
 2086  
      */
 2087  
     public static long copy(final InputStream input, final OutputStream output, final int bufferSize) throws IOException {
 2088  120
         return copyLarge(input, output, new byte[bufferSize]);
 2089  
     }
 2090  
 
 2091  
     /**
 2092  
      * Copies bytes from a large (over 2GB) <code>InputStream</code> to an
 2093  
      * <code>OutputStream</code>.
 2094  
      * <p>
 2095  
      * This method buffers the input internally, so there is no need to use a
 2096  
      * <code>BufferedInputStream</code>.
 2097  
      * <p>
 2098  
      * The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}.
 2099  
      *
 2100  
      * @param input  the <code>InputStream</code> to read from
 2101  
      * @param output  the <code>OutputStream</code> to write to
 2102  
      * @return the number of bytes copied
 2103  
      * @throws NullPointerException if the input or output is null
 2104  
      * @throws IOException if an I/O error occurs
 2105  
      * @since 1.3
 2106  
      */
 2107  
     public static long copyLarge(final InputStream input, final OutputStream output)
 2108  
             throws IOException {
 2109  90
         return copy(input, output, DEFAULT_BUFFER_SIZE);
 2110  
     }
 2111  
 
 2112  
     /**
 2113  
      * Copies bytes from a large (over 2GB) <code>InputStream</code> to an
 2114  
      * <code>OutputStream</code>.
 2115  
      * <p>
 2116  
      * This method uses the provided buffer, so there is no need to use a
 2117  
      * <code>BufferedInputStream</code>.
 2118  
      * <p>
 2119  
      *
 2120  
      * @param input  the <code>InputStream</code> to read from
 2121  
      * @param output  the <code>OutputStream</code> to write to
 2122  
      * @param buffer the buffer to use for the copy
 2123  
      * @return the number of bytes copied
 2124  
      * @throws NullPointerException if the input or output is null
 2125  
      * @throws IOException if an I/O error occurs
 2126  
      * @since 2.2
 2127  
      */
 2128  
     public static long copyLarge(final InputStream input, final OutputStream output, final byte[] buffer)
 2129  
             throws IOException {
 2130  120
         long count = 0;
 2131  120
         int n = 0;
 2132  6308096
         while (EOF != (n = input.read(buffer))) {
 2133  6307978
             output.write(buffer, 0, n);
 2134  6307976
             count += n;
 2135  
         }
 2136  114
         return count;
 2137  
     }
 2138  
 
 2139  
     /**
 2140  
      * Copies some or all bytes from a large (over 2GB) <code>InputStream</code> to an
 2141  
      * <code>OutputStream</code>, optionally skipping input bytes.
 2142  
      * <p>
 2143  
      * This method buffers the input internally, so there is no need to use a
 2144  
      * <code>BufferedInputStream</code>.
 2145  
      * </p>
 2146  
      * <p>
 2147  
      * Note that the implementation uses {@link #skip(InputStream, long)}.
 2148  
      * This means that the method may be considerably less efficient than using the actual skip implementation,
 2149  
      * this is done to guarantee that the correct number of characters are skipped.
 2150  
      * </p>
 2151  
      * The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}.
 2152  
      *
 2153  
      * @param input  the <code>InputStream</code> to read from
 2154  
      * @param output  the <code>OutputStream</code> to write to
 2155  
      * @param inputOffset : number of bytes to skip from input before copying
 2156  
      *         -ve values are ignored
 2157  
      * @param length : number of bytes to copy. -ve means all
 2158  
      * @return the number of bytes copied
 2159  
      * @throws NullPointerException if the input or output is null
 2160  
      * @throws IOException if an I/O error occurs
 2161  
      * @since 2.2
 2162  
      */
 2163  
     public static long copyLarge(final InputStream input, final OutputStream output, final long inputOffset, final long length)
 2164  
             throws IOException {
 2165  10
         return copyLarge(input, output, inputOffset, length, new byte[DEFAULT_BUFFER_SIZE]);
 2166  
     }
 2167  
 
 2168  
     /**
 2169  
      * Copies some or all bytes from a large (over 2GB) <code>InputStream</code> to an
 2170  
      * <code>OutputStream</code>, optionally skipping input bytes.
 2171  
      * <p>
 2172  
      * This method uses the provided buffer, so there is no need to use a
 2173  
      * <code>BufferedInputStream</code>.
 2174  
      * </p>
 2175  
      * <p>
 2176  
      * Note that the implementation uses {@link #skip(InputStream, long)}.
 2177  
      * This means that the method may be considerably less efficient than using the actual skip implementation,
 2178  
      * this is done to guarantee that the correct number of characters are skipped.
 2179  
      * </p>
 2180  
      *
 2181  
      * @param input  the <code>InputStream</code> to read from
 2182  
      * @param output  the <code>OutputStream</code> to write to
 2183  
      * @param inputOffset : number of bytes to skip from input before copying
 2184  
      *         -ve values are ignored
 2185  
      * @param length : number of bytes to copy. -ve means all
 2186  
      * @param buffer the buffer to use for the copy
 2187  
      *
 2188  
      * @return the number of bytes copied
 2189  
      * @throws NullPointerException if the input or output is null
 2190  
      * @throws IOException if an I/O error occurs
 2191  
      * @since 2.2
 2192  
      */
 2193  
     public static long copyLarge(final InputStream input, final OutputStream output,
 2194  
             final long inputOffset, final long length, final byte[] buffer)  throws IOException {
 2195  10
         if (inputOffset > 0) {
 2196  4
             skipFully(input, inputOffset);
 2197  
         }
 2198  8
         if (length == 0) {
 2199  0
             return 0;
 2200  
         }
 2201  8
         final int bufferLength = buffer.length;
 2202  8
         int bytesToRead = bufferLength;
 2203  8
         if (length > 0 && length < bufferLength) {
 2204  6
             bytesToRead = (int) length;
 2205  
         }
 2206  
         int read;
 2207  8
         long totalRead = 0;
 2208  16
         while (bytesToRead > 0 && EOF != (read = input.read(buffer, 0, bytesToRead))) {
 2209  8
             output.write(buffer, 0, read);
 2210  8
             totalRead += read;
 2211  8
             if (length > 0) { // only adjust length if not reading to the end
 2212  
                 // Note the cast must work because buffer.length is an integer
 2213  6
                 bytesToRead = (int) Math.min(length - totalRead, bufferLength);
 2214  
             }
 2215  
         }
 2216  8
         return totalRead;
 2217  
     }
 2218  
 
 2219  
     /**
 2220  
      * Copies bytes from an <code>InputStream</code> to chars on a
 2221  
      * <code>Writer</code> using the default character encoding of the platform.
 2222  
      * <p>
 2223  
      * This method buffers the input internally, so there is no need to use a
 2224  
      * <code>BufferedInputStream</code>.
 2225  
      * <p>
 2226  
      * This method uses {@link InputStreamReader}.
 2227  
      *
 2228  
      * @param input  the <code>InputStream</code> to read from
 2229  
      * @param output  the <code>Writer</code> to write to
 2230  
      * @throws NullPointerException if the input or output is null
 2231  
      * @throws IOException if an I/O error occurs
 2232  
      * @since 1.1
 2233  
      * @deprecated 2.5 use {@link #copy(InputStream, Writer, Charset)} instead
 2234  
      */
 2235  
     @Deprecated
 2236  
     public static void copy(final InputStream input, final Writer output)
 2237  
             throws IOException {
 2238  6
         copy(input, output, Charset.defaultCharset());
 2239  2
     }
 2240  
 
 2241  
     /**
 2242  
      * Copies bytes from an <code>InputStream</code> to chars on a
 2243  
      * <code>Writer</code> using the specified character encoding.
 2244  
      * <p>
 2245  
      * This method buffers the input internally, so there is no need to use a
 2246  
      * <code>BufferedInputStream</code>.
 2247  
      * <p>
 2248  
      * This method uses {@link InputStreamReader}.
 2249  
      *
 2250  
      * @param input  the <code>InputStream</code> to read from
 2251  
      * @param output  the <code>Writer</code> to write to
 2252  
      * @param inputEncoding  the encoding to use for the input stream, null means platform default
 2253  
      * @throws NullPointerException if the input or output is null
 2254  
      * @throws IOException if an I/O error occurs
 2255  
      * @since 2.3
 2256  
      */
 2257  
     public static void copy(final InputStream input, final Writer output, final Charset inputEncoding) throws IOException {
 2258  86
         final InputStreamReader in = new InputStreamReader(input, Charsets.toCharset(inputEncoding));
 2259  82
         copy(in, output);
 2260  78
     }
 2261  
 
 2262  
     /**
 2263  
      * Copies bytes from an <code>InputStream</code> to chars on a
 2264  
      * <code>Writer</code> using the specified character encoding.
 2265  
      * <p>
 2266  
      * This method buffers the input internally, so there is no need to use a
 2267  
      * <code>BufferedInputStream</code>.
 2268  
      * <p>
 2269  
      * Character encoding names can be found at
 2270  
      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
 2271  
      * <p>
 2272  
      * This method uses {@link InputStreamReader}.
 2273  
      *
 2274  
      * @param input  the <code>InputStream</code> to read from
 2275  
      * @param output  the <code>Writer</code> to write to
 2276  
      * @param inputEncoding  the encoding to use for the InputStream, null means platform default
 2277  
      * @throws NullPointerException if the input or output is null
 2278  
      * @throws IOException if an I/O error occurs
 2279  
      * @throws UnsupportedCharsetException
 2280  
      *             thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not
 2281  
      *             supported.
 2282  
      * @since 1.1
 2283  
      */
 2284  
     public static void copy(final InputStream input, final Writer output, final String inputEncoding) throws IOException {
 2285  8
         copy(input, output, Charsets.toCharset(inputEncoding));
 2286  4
     }
 2287  
 
 2288  
     // copy from Reader
 2289  
     //-----------------------------------------------------------------------
 2290  
     /**
 2291  
      * Copies chars from a <code>Reader</code> to a <code>Writer</code>.
 2292  
      * <p>
 2293  
      * This method buffers the input internally, so there is no need to use a
 2294  
      * <code>BufferedReader</code>.
 2295  
      * <p>
 2296  
      * Large streams (over 2GB) will return a chars copied value of
 2297  
      * <code>-1</code> after the copy has completed since the correct
 2298  
      * number of chars cannot be returned as an int. For large streams
 2299  
      * use the <code>copyLarge(Reader, Writer)</code> method.
 2300  
      *
 2301  
      * @param input  the <code>Reader</code> to read from
 2302  
      * @param output  the <code>Writer</code> to write to
 2303  
      * @return the number of characters copied, or -1 if &gt; Integer.MAX_VALUE
 2304  
      * @throws NullPointerException if the input or output is null
 2305  
      * @throws IOException if an I/O error occurs
 2306  
      * @since 1.1
 2307  
      */
 2308  
     public static int copy(final Reader input, final Writer output) throws IOException {
 2309  118
         final long count = copyLarge(input, output);
 2310  106
         if (count > Integer.MAX_VALUE) {
 2311  2
             return -1;
 2312  
         }
 2313  104
         return (int) count;
 2314  
     }
 2315  
 
 2316  
     /**
 2317  
      * Copies chars from a large (over 2GB) <code>Reader</code> to a <code>Writer</code>.
 2318  
      * <p>
 2319  
      * This method buffers the input internally, so there is no need to use a
 2320  
      * <code>BufferedReader</code>.
 2321  
      * <p>
 2322  
      * The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}.
 2323  
      *
 2324  
      * @param input  the <code>Reader</code> to read from
 2325  
      * @param output  the <code>Writer</code> to write to
 2326  
      * @return the number of characters copied
 2327  
      * @throws NullPointerException if the input or output is null
 2328  
      * @throws IOException if an I/O error occurs
 2329  
      * @since 1.3
 2330  
      */
 2331  
     public static long copyLarge(final Reader input, final Writer output) throws IOException {
 2332  120
         return copyLarge(input, output, new char[DEFAULT_BUFFER_SIZE]);
 2333  
     }
 2334  
 
 2335  
     /**
 2336  
      * Copies chars from a large (over 2GB) <code>Reader</code> to a <code>Writer</code>.
 2337  
      * <p>
 2338  
      * This method uses the provided buffer, so there is no need to use a
 2339  
      * <code>BufferedReader</code>.
 2340  
      * <p>
 2341  
      *
 2342  
      * @param input  the <code>Reader</code> to read from
 2343  
      * @param output  the <code>Writer</code> to write to
 2344  
      * @param buffer the buffer to be used for the copy
 2345  
      * @return the number of characters copied
 2346  
      * @throws NullPointerException if the input or output is null
 2347  
      * @throws IOException if an I/O error occurs
 2348  
      * @since 2.2
 2349  
      */
 2350  
     public static long copyLarge(final Reader input, final Writer output, final char [] buffer) throws IOException {
 2351  120
         long count = 0;
 2352  120
         int n = 0;
 2353  2097418
         while (EOF != (n = input.read(buffer))) {
 2354  2097304
             output.write(buffer, 0, n);
 2355  2097298
             count += n;
 2356  
         }
 2357  108
         return count;
 2358  
     }
 2359  
 
 2360  
     /**
 2361  
      * Copies some or all chars from a large (over 2GB) <code>InputStream</code> to an
 2362  
      * <code>OutputStream</code>, optionally skipping input chars.
 2363  
      * <p>
 2364  
      * This method buffers the input internally, so there is no need to use a
 2365  
      * <code>BufferedReader</code>.
 2366  
      * <p>
 2367  
      * The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}.
 2368  
      *
 2369  
      * @param input  the <code>Reader</code> to read from
 2370  
      * @param output  the <code>Writer</code> to write to
 2371  
      * @param inputOffset : number of chars to skip from input before copying
 2372  
      *         -ve values are ignored
 2373  
      * @param length : number of chars to copy. -ve means all
 2374  
      * @return the number of chars copied
 2375  
      * @throws NullPointerException if the input or output is null
 2376  
      * @throws IOException if an I/O error occurs
 2377  
      * @since 2.2
 2378  
      */
 2379  
     public static long copyLarge(final Reader input, final Writer output, final long inputOffset, final long length)
 2380  
             throws IOException {
 2381  10
         return  copyLarge(input, output, inputOffset, length, new char[DEFAULT_BUFFER_SIZE]);
 2382  
     }
 2383  
 
 2384  
     /**
 2385  
      * Copies some or all chars from a large (over 2GB) <code>InputStream</code> to an
 2386  
      * <code>OutputStream</code>, optionally skipping input chars.
 2387  
      * <p>
 2388  
      * This method uses the provided buffer, so there is no need to use a
 2389  
      * <code>BufferedReader</code>.
 2390  
      * <p>
 2391  
      *
 2392  
      * @param input  the <code>Reader</code> to read from
 2393  
      * @param output  the <code>Writer</code> to write to
 2394  
      * @param inputOffset : number of chars to skip from input before copying
 2395  
      *         -ve values are ignored
 2396  
      * @param length : number of chars to copy. -ve means all
 2397  
      * @param buffer the buffer to be used for the copy
 2398  
      * @return the number of chars copied
 2399  
      * @throws NullPointerException if the input or output is null
 2400  
      * @throws IOException if an I/O error occurs
 2401  
      * @since 2.2
 2402  
      */
 2403  
     public static long copyLarge(final Reader input, final Writer output, final long inputOffset, final long length, final char [] buffer)
 2404  
             throws IOException {
 2405  10
         if (inputOffset > 0) {
 2406  4
             skipFully(input, inputOffset);
 2407  
         }
 2408  8
         if (length == 0) {
 2409  0
             return 0;
 2410  
         }
 2411  8
         int bytesToRead = buffer.length;
 2412  8
         if (length > 0 && length < buffer.length) {
 2413  6
             bytesToRead = (int) length;
 2414  
         }
 2415  
         int read;
 2416  8
         long totalRead = 0;
 2417  16
         while (bytesToRead > 0 && EOF != (read = input.read(buffer, 0, bytesToRead))) {
 2418  8
             output.write(buffer, 0, read);
 2419  8
             totalRead += read;
 2420  8
             if (length > 0) { // only adjust length if not reading to the end
 2421  
                 // Note the cast must work because buffer.length is an integer
 2422  6
                 bytesToRead = (int) Math.min(length - totalRead, buffer.length);
 2423  
             }
 2424  
         }
 2425  8
         return totalRead;
 2426  
     }
 2427  
 
 2428  
     /**
 2429  
      * Copies chars from a <code>Reader</code> to bytes on an
 2430  
      * <code>OutputStream</code> using the default character encoding of the
 2431  
      * platform, and calling flush.
 2432  
      * <p>
 2433  
      * This method buffers the input internally, so there is no need to use a
 2434  
      * <code>BufferedReader</code>.
 2435  
      * <p>
 2436  
      * Due to the implementation of OutputStreamWriter, this method performs a
 2437  
      * flush.
 2438  
      * <p>
 2439  
      * This method uses {@link OutputStreamWriter}.
 2440  
      *
 2441  
      * @param input  the <code>Reader</code> to read from
 2442  
      * @param output  the <code>OutputStream</code> to write to
 2443  
      * @throws NullPointerException if the input or output is null
 2444  
      * @throws IOException if an I/O error occurs
 2445  
      * @since 1.1
 2446  
      * @deprecated 2.5 use {@link #copy(Reader, OutputStream, Charset)} instead
 2447  
      */
 2448  
     @Deprecated
 2449  
     public static void copy(final Reader input, final OutputStream output)
 2450  
             throws IOException {
 2451  6
         copy(input, output, Charset.defaultCharset());
 2452  2
     }
 2453  
 
 2454  
     /**
 2455  
      * Copies chars from a <code>Reader</code> to bytes on an
 2456  
      * <code>OutputStream</code> using the specified character encoding, and
 2457  
      * calling flush.
 2458  
      * <p>
 2459  
      * This method buffers the input internally, so there is no need to use a
 2460  
      * <code>BufferedReader</code>.
 2461  
      * </p>
 2462  
      * <p>
 2463  
      * Due to the implementation of OutputStreamWriter, this method performs a
 2464  
      * flush.
 2465  
      * </p>
 2466  
      * <p>
 2467  
      * This method uses {@link OutputStreamWriter}.
 2468  
      * </p>
 2469  
      *
 2470  
      * @param input  the <code>Reader</code> to read from
 2471  
      * @param output  the <code>OutputStream</code> to write to
 2472  
      * @param outputEncoding  the encoding to use for the OutputStream, null means platform default
 2473  
      * @throws NullPointerException if the input or output is null
 2474  
      * @throws IOException if an I/O error occurs
 2475  
      * @since 2.3
 2476  
      */
 2477  
     public static void copy(final Reader input, final OutputStream output, final Charset outputEncoding) throws IOException {
 2478  18
         final OutputStreamWriter out = new OutputStreamWriter(output, Charsets.toCharset(outputEncoding));
 2479  14
         copy(input, out);
 2480  
         // XXX Unless anyone is planning on rewriting OutputStreamWriter,
 2481  
         // we have to flush here.
 2482  10
         out.flush();
 2483  10
     }
 2484  
 
 2485  
     /**
 2486  
      * Copies chars from a <code>Reader</code> to bytes on an
 2487  
      * <code>OutputStream</code> using the specified character encoding, and
 2488  
      * calling flush.
 2489  
      * <p>
 2490  
      * This method buffers the input internally, so there is no need to use a
 2491  
      * <code>BufferedReader</code>.
 2492  
      * <p>
 2493  
      * Character encoding names can be found at
 2494  
      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
 2495  
      * <p>
 2496  
      * Due to the implementation of OutputStreamWriter, this method performs a
 2497  
      * flush.
 2498  
      * <p>
 2499  
      * This method uses {@link OutputStreamWriter}.
 2500  
      *
 2501  
      * @param input  the <code>Reader</code> to read from
 2502  
      * @param output  the <code>OutputStream</code> to write to
 2503  
      * @param outputEncoding  the encoding to use for the OutputStream, null means platform default
 2504  
      * @throws NullPointerException if the input or output is null
 2505  
      * @throws IOException if an I/O error occurs
 2506  
      * @throws UnsupportedCharsetException
 2507  
      *             thrown instead of {@link UnsupportedEncodingException} in version 2.2 if the encoding is not
 2508  
      *             supported.
 2509  
      * @since 1.1
 2510  
      */
 2511  
     public static void copy(final Reader input, final OutputStream output, final String outputEncoding) throws IOException {
 2512  8
         copy(input, output, Charsets.toCharset(outputEncoding));
 2513  4
     }
 2514  
 
 2515  
     // content equals
 2516  
     //-----------------------------------------------------------------------
 2517  
     /**
 2518  
      * Compares the contents of two Streams to determine if they are equal or
 2519  
      * not.
 2520  
      * <p>
 2521  
      * This method buffers the input internally using
 2522  
      * <code>BufferedInputStream</code> if they are not already buffered.
 2523  
      *
 2524  
      * @param input1  the first stream
 2525  
      * @param input2  the second stream
 2526  
      * @return true if the content of the streams are equal or they both don't
 2527  
      * exist, false otherwise
 2528  
      * @throws NullPointerException if either input is null
 2529  
      * @throws IOException if an I/O error occurs
 2530  
      */
 2531  
     public static boolean contentEquals(InputStream input1, InputStream input2)
 2532  
             throws IOException {
 2533  24
         if (input1 == input2) {
 2534  4
             return true;
 2535  
         }
 2536  20
         if (!(input1 instanceof BufferedInputStream)) {
 2537  18
             input1 = new BufferedInputStream(input1);
 2538  
         }
 2539  20
         if (!(input2 instanceof BufferedInputStream)) {
 2540  18
             input2 = new BufferedInputStream(input2);
 2541  
         }
 2542  
 
 2543  20
         int ch = input1.read();
 2544  9130
         while (EOF != ch) {
 2545  9114
             final int ch2 = input2.read();
 2546  9114
             if (ch != ch2) {
 2547  4
                 return false;
 2548  
             }
 2549  9110
             ch = input1.read();
 2550  9110
         }
 2551  
 
 2552  16
         final int ch2 = input2.read();
 2553  16
         return ch2 == EOF;
 2554  
     }
 2555  
 
 2556  
     /**
 2557  
      * Compares the contents of two Readers to determine if they are equal or
 2558  
      * not.
 2559  
      * <p>
 2560  
      * This method buffers the input internally using
 2561  
      * <code>BufferedReader</code> if they are not already buffered.
 2562  
      *
 2563  
      * @param input1  the first reader
 2564  
      * @param input2  the second reader
 2565  
      * @return true if the content of the readers are equal or they both don't
 2566  
      * exist, false otherwise
 2567  
      * @throws NullPointerException if either input is null
 2568  
      * @throws IOException if an I/O error occurs
 2569  
      * @since 1.1
 2570  
      */
 2571  
     public static boolean contentEquals(Reader input1, Reader input2)
 2572  
             throws IOException {
 2573  14
         if (input1 == input2) {
 2574  4
             return true;
 2575  
         }
 2576  
 
 2577  10
         input1 = toBufferedReader(input1);
 2578  10
         input2 = toBufferedReader(input2);
 2579  
 
 2580  10
         int ch = input1.read();
 2581  28
         while (EOF != ch) {
 2582  20
             final int ch2 = input2.read();
 2583  20
             if (ch != ch2) {
 2584  2
                 return false;
 2585  
             }
 2586  18
             ch = input1.read();
 2587  18
         }
 2588  
 
 2589  8
         final int ch2 = input2.read();
 2590  8
         return ch2 == EOF;
 2591  
     }
 2592  
 
 2593  
     /**
 2594  
      * Compares the contents of two Readers to determine if they are equal or
 2595  
      * not, ignoring EOL characters.
 2596  
      * <p>
 2597  
      * This method buffers the input internally using
 2598  
      * <code>BufferedReader</code> if they are not already buffered.
 2599  
      *
 2600  
      * @param input1  the first reader
 2601  
      * @param input2  the second reader
 2602  
      * @return true if the content of the readers are equal (ignoring EOL differences),  false otherwise
 2603  
      * @throws NullPointerException if either input is null
 2604  
      * @throws IOException if an I/O error occurs
 2605  
      * @since 2.2
 2606  
      */
 2607  
     public static boolean contentEqualsIgnoreEOL(final Reader input1, final Reader input2)
 2608  
             throws IOException {
 2609  28
         if (input1 == input2) {
 2610  4
             return true;
 2611  
         }
 2612  24
         final BufferedReader br1 = toBufferedReader(input1);
 2613  24
         final BufferedReader br2 = toBufferedReader(input2);
 2614  
 
 2615  24
         String line1 = br1.readLine();
 2616  24
         String line2 = br2.readLine();
 2617  56
         while (line1 != null && line2 != null && line1.equals(line2)) {
 2618  32
             line1 = br1.readLine();
 2619  32
             line2 = br2.readLine();
 2620  
         }
 2621  24
         return line1 == null ? line2 == null ? true : false : line1.equals(line2);
 2622  
     }
 2623  
 
 2624  
     /**
 2625  
      * Skips bytes from an input byte stream.
 2626  
      * This implementation guarantees that it will read as many bytes
 2627  
      * as possible before giving up; this may not always be the case for
 2628  
      * skip() implementations in subclasses of {@link InputStream}.
 2629  
      * <p>
 2630  
      * Note that the implementation uses {@link InputStream#read(byte[], int, int)} rather
 2631  
      * than delegating to {@link InputStream#skip(long)}.
 2632  
      * This means that the method may be considerably less efficient than using the actual skip implementation,
 2633  
      * this is done to guarantee that the correct number of bytes are skipped.
 2634  
      * </p>
 2635  
      *
 2636  
      *
 2637  
      * @param input byte stream to skip
 2638  
      * @param toSkip number of bytes to skip.
 2639  
      * @return number of bytes actually skipped.
 2640  
      *
 2641  
      * @see InputStream#skip(long)
 2642  
      * @see <a href="https://issues.apache.org/jira/browse/IO-203">IO-203 - Add skipFully() method for InputStreams</a>
 2643  
      *
 2644  
      * @throws IOException if there is a problem reading the file
 2645  
      * @throws IllegalArgumentException if toSkip is negative
 2646  
      * @since 2.0
 2647  
      */
 2648  
     public static long skip(final InputStream input, final long toSkip) throws IOException {
 2649  16
         if (toSkip < 0) {
 2650  0
             throw new IllegalArgumentException("Skip count must be non-negative, actual: " + toSkip);
 2651  
         }
 2652  
         /*
 2653  
          * N.B. no need to synchronize this because: - we don't care if the buffer is created multiple times (the data
 2654  
          * is ignored) - we always use the same size buffer, so if it it is recreated it will still be OK (if the buffer
 2655  
          * size were variable, we would need to synch. to ensure some other thread did not create a smaller one)
 2656  
          */
 2657  16
         if (SKIP_BYTE_BUFFER == null) {
 2658  2
             SKIP_BYTE_BUFFER = new byte[SKIP_BUFFER_SIZE];
 2659  
         }
 2660  16
         long remain = toSkip;
 2661  30
         while (remain > 0) {
 2662  
             // See https://issues.apache.org/jira/browse/IO-203 for why we use read() rather than delegating to skip()
 2663  22
             final long n = input.read(SKIP_BYTE_BUFFER, 0, (int) Math.min(remain, SKIP_BUFFER_SIZE));
 2664  22
             if (n < 0) { // EOF
 2665  8
                 break;
 2666  
             }
 2667  14
             remain -= n;
 2668  14
         }
 2669  16
         return toSkip - remain;
 2670  
     }
 2671  
 
 2672  
     /**
 2673  
      * Skips bytes from a ReadableByteChannel.
 2674  
      * This implementation guarantees that it will read as many bytes
 2675  
      * as possible before giving up.
 2676  
      *
 2677  
      * @param input ReadableByteChannel to skip
 2678  
      * @param toSkip number of bytes to skip.
 2679  
      * @return number of bytes actually skipped.
 2680  
      *
 2681  
      * @throws IOException if there is a problem reading the ReadableByteChannel
 2682  
      * @throws IllegalArgumentException if toSkip is negative
 2683  
      * @since 2.5
 2684  
      */
 2685  
     public static long skip(final ReadableByteChannel input, final long toSkip) throws IOException {
 2686  12
         if (toSkip < 0) {
 2687  0
             throw new IllegalArgumentException("Skip count must be non-negative, actual: " + toSkip);
 2688  
         }
 2689  12
         final ByteBuffer skipByteBuffer = ByteBuffer.allocate((int) Math.min(toSkip, SKIP_BUFFER_SIZE));
 2690  12
         long remain = toSkip;
 2691  24
         while (remain > 0) {
 2692  18
             skipByteBuffer.position(0);
 2693  18
             skipByteBuffer.limit((int) Math.min(remain, SKIP_BUFFER_SIZE));
 2694  18
             final int n = input.read(skipByteBuffer);
 2695  18
             if (n == EOF) {
 2696  6
                 break;
 2697  
             }
 2698  12
             remain -= n;
 2699  12
         }
 2700  12
         return toSkip - remain;
 2701  
     }
 2702  
 
 2703  
     /**
 2704  
      * Skips characters from an input character stream.
 2705  
      * This implementation guarantees that it will read as many characters
 2706  
      * as possible before giving up; this may not always be the case for
 2707  
      * skip() implementations in subclasses of {@link Reader}.
 2708  
      * <p>
 2709  
      * Note that the implementation uses {@link Reader#read(char[], int, int)} rather
 2710  
      * than delegating to {@link Reader#skip(long)}.
 2711  
      * This means that the method may be considerably less efficient than using the actual skip implementation,
 2712  
      * this is done to guarantee that the correct number of characters are skipped.
 2713  
      * </p>
 2714  
      *
 2715  
      * @param input character stream to skip
 2716  
      * @param toSkip number of characters to skip.
 2717  
      * @return number of characters actually skipped.
 2718  
      *
 2719  
      * @see Reader#skip(long)
 2720  
      * @see <a href="https://issues.apache.org/jira/browse/IO-203">IO-203 - Add skipFully() method for InputStreams</a>
 2721  
      *
 2722  
      * @throws IOException if there is a problem reading the file
 2723  
      * @throws IllegalArgumentException if toSkip is negative
 2724  
      * @since 2.0
 2725  
      */
 2726  
     public static long skip(final Reader input, final long toSkip) throws IOException {
 2727  18
         if (toSkip < 0) {
 2728  2
             throw new IllegalArgumentException("Skip count must be non-negative, actual: " + toSkip);
 2729  
         }
 2730  
         /*
 2731  
          * N.B. no need to synchronize this because: - we don't care if the buffer is created multiple times (the data
 2732  
          * is ignored) - we always use the same size buffer, so if it it is recreated it will still be OK (if the buffer
 2733  
          * size were variable, we would need to synch. to ensure some other thread did not create a smaller one)
 2734  
          */
 2735  16
         if (SKIP_CHAR_BUFFER == null) {
 2736  2
             SKIP_CHAR_BUFFER = new char[SKIP_BUFFER_SIZE];
 2737  
         }
 2738  16
         long remain = toSkip;
 2739  30
         while (remain > 0) {
 2740  
             // See https://issues.apache.org/jira/browse/IO-203 for why we use read() rather than delegating to skip()
 2741  22
             final long n = input.read(SKIP_CHAR_BUFFER, 0, (int) Math.min(remain, SKIP_BUFFER_SIZE));
 2742  22
             if (n < 0) { // EOF
 2743  8
                 break;
 2744  
             }
 2745  14
             remain -= n;
 2746  14
         }
 2747  16
         return toSkip - remain;
 2748  
     }
 2749  
 
 2750  
     /**
 2751  
      * Skips the requested number of bytes or fail if there are not enough left.
 2752  
      * <p>
 2753  
      * This allows for the possibility that {@link InputStream#skip(long)} may
 2754  
      * not skip as many bytes as requested (most likely because of reaching EOF).
 2755  
      * <p>
 2756  
      * Note that the implementation uses {@link #skip(InputStream, long)}.
 2757  
      * This means that the method may be considerably less efficient than using the actual skip implementation,
 2758  
      * this is done to guarantee that the correct number of characters are skipped.
 2759  
      * </p>
 2760  
      *
 2761  
      * @param input stream to skip
 2762  
      * @param toSkip the number of bytes to skip
 2763  
      * @see InputStream#skip(long)
 2764  
      *
 2765  
      * @throws IOException if there is a problem reading the file
 2766  
      * @throws IllegalArgumentException if toSkip is negative
 2767  
      * @throws EOFException if the number of bytes skipped was incorrect
 2768  
      * @since 2.0
 2769  
      */
 2770  
     public static void skipFully(final InputStream input, final long toSkip) throws IOException {
 2771  12
         if (toSkip < 0) {
 2772  2
             throw new IllegalArgumentException("Bytes to skip must not be negative: " + toSkip);
 2773  
         }
 2774  10
         final long skipped = skip(input, toSkip);
 2775  10
         if (skipped != toSkip) {
 2776  4
             throw new EOFException("Bytes to skip: " + toSkip + " actual: " + skipped);
 2777  
         }
 2778  6
     }
 2779  
 
 2780  
     /**
 2781  
      * Skips the requested number of bytes or fail if there are not enough left.
 2782  
      *
 2783  
      * @param input ReadableByteChannel to skip
 2784  
      * @param toSkip the number of bytes to skip
 2785  
      *
 2786  
      * @throws IOException if there is a problem reading the ReadableByteChannel
 2787  
      * @throws IllegalArgumentException if toSkip is negative
 2788  
      * @throws EOFException if the number of bytes skipped was incorrect
 2789  
      * @since 2.5
 2790  
      */
 2791  
     public static void skipFully(final ReadableByteChannel input, final long toSkip) throws IOException {
 2792  8
         if (toSkip < 0) {
 2793  2
             throw new IllegalArgumentException("Bytes to skip must not be negative: " + toSkip);
 2794  
         }
 2795  6
         final long skipped = skip(input, toSkip);
 2796  6
         if (skipped != toSkip) {
 2797  2
             throw new EOFException("Bytes to skip: " + toSkip + " actual: " + skipped);
 2798  
         }
 2799  4
     }
 2800  
 
 2801  
     /**
 2802  
      * Skips the requested number of characters or fail if there are not enough left.
 2803  
      * <p>
 2804  
      * This allows for the possibility that {@link Reader#skip(long)} may
 2805  
      * not skip as many characters as requested (most likely because of reaching EOF).
 2806  
      * <p>
 2807  
      * Note that the implementation uses {@link #skip(Reader, long)}.
 2808  
      * This means that the method may be considerably less efficient than using the actual skip implementation,
 2809  
      * this is done to guarantee that the correct number of characters are skipped.
 2810  
      * </p>
 2811  
      *
 2812  
      * @param input stream to skip
 2813  
      * @param toSkip the number of characters to skip
 2814  
      * @see Reader#skip(long)
 2815  
      *
 2816  
      * @throws IOException if there is a problem reading the file
 2817  
      * @throws IllegalArgumentException if toSkip is negative
 2818  
      * @throws EOFException if the number of characters skipped was incorrect
 2819  
      * @since 2.0
 2820  
      */
 2821  
     public static void skipFully(final Reader input, final long toSkip) throws IOException {
 2822  12
         final long skipped = skip(input, toSkip);
 2823  10
         if (skipped != toSkip) {
 2824  4
             throw new EOFException("Chars to skip: " + toSkip + " actual: " + skipped);
 2825  
         }
 2826  6
     }
 2827  
 
 2828  
 
 2829  
     /**
 2830  
      * Reads characters from an input character stream.
 2831  
      * This implementation guarantees that it will read as many characters
 2832  
      * as possible before giving up; this may not always be the case for
 2833  
      * subclasses of {@link Reader}.
 2834  
      *
 2835  
      * @param input where to read input from
 2836  
      * @param buffer destination
 2837  
      * @param offset initial offset into buffer
 2838  
      * @param length length to read, must be &gt;= 0
 2839  
      * @return actual length read; may be less than requested if EOF was reached
 2840  
      * @throws IOException if a read error occurs
 2841  
      * @since 2.2
 2842  
      */
 2843  
     public static int read(final Reader input, final char[] buffer, final int offset, final int length) throws IOException {
 2844  10
         if (length < 0) {
 2845  2
             throw new IllegalArgumentException("Length must not be negative: " + length);
 2846  
         }
 2847  8
         int remaining = length;
 2848  14
         while (remaining > 0) {
 2849  8
             final int location = length - remaining;
 2850  8
             final int count = input.read(buffer, offset + location, remaining);
 2851  8
             if (EOF == count) { // EOF
 2852  2
                 break;
 2853  
             }
 2854  6
             remaining -= count;
 2855  6
         }
 2856  8
         return length - remaining;
 2857  
     }
 2858  
 
 2859  
     /**
 2860  
      * Reads characters from an input character stream.
 2861  
      * This implementation guarantees that it will read as many characters
 2862  
      * as possible before giving up; this may not always be the case for
 2863  
      * subclasses of {@link Reader}.
 2864  
      *
 2865  
      * @param input where to read input from
 2866  
      * @param buffer destination
 2867  
      * @return actual length read; may be less than requested if EOF was reached
 2868  
      * @throws IOException if a read error occurs
 2869  
      * @since 2.2
 2870  
      */
 2871  
     public static int read(final Reader input, final char[] buffer) throws IOException {
 2872  0
         return read(input, buffer, 0, buffer.length);
 2873  
     }
 2874  
 
 2875  
     /**
 2876  
      * Reads bytes from an input stream.
 2877  
      * This implementation guarantees that it will read as many bytes
 2878  
      * as possible before giving up; this may not always be the case for
 2879  
      * subclasses of {@link InputStream}.
 2880  
      *
 2881  
      * @param input where to read input from
 2882  
      * @param buffer destination
 2883  
      * @param offset initial offset into buffer
 2884  
      * @param length length to read, must be &gt;= 0
 2885  
      * @return actual length read; may be less than requested if EOF was reached
 2886  
      * @throws IOException if a read error occurs
 2887  
      * @since 2.2
 2888  
      */
 2889  
     public static int read(final InputStream input, final byte[] buffer, final int offset, final int length) throws IOException {
 2890  12
         if (length < 0) {
 2891  2
             throw new IllegalArgumentException("Length must not be negative: " + length);
 2892  
         }
 2893  10
         int remaining = length;
 2894  18
         while (remaining > 0) {
 2895  10
             final int location = length - remaining;
 2896  10
             final int count = input.read(buffer, offset + location, remaining);
 2897  10
             if (EOF == count) { // EOF
 2898  2
                 break;
 2899  
             }
 2900  8
             remaining -= count;
 2901  8
         }
 2902  10
         return length - remaining;
 2903  
     }
 2904  
 
 2905  
     /**
 2906  
      * Reads bytes from an input stream.
 2907  
      * This implementation guarantees that it will read as many bytes
 2908  
      * as possible before giving up; this may not always be the case for
 2909  
      * subclasses of {@link InputStream}.
 2910  
      *
 2911  
      * @param input where to read input from
 2912  
      * @param buffer destination
 2913  
      * @return actual length read; may be less than requested if EOF was reached
 2914  
      * @throws IOException if a read error occurs
 2915  
      * @since 2.2
 2916  
      */
 2917  
     public static int read(final InputStream input, final byte[] buffer) throws IOException {
 2918  0
         return read(input, buffer, 0, buffer.length);
 2919  
     }
 2920  
 
 2921  
     /**
 2922  
      * Reads bytes from a ReadableByteChannel.
 2923  
      * <p>
 2924  
      * This implementation guarantees that it will read as many bytes
 2925  
      * as possible before giving up; this may not always be the case for
 2926  
      * subclasses of {@link ReadableByteChannel}.
 2927  
      *
 2928  
      * @param input the byte channel to read
 2929  
      * @param buffer byte buffer destination
 2930  
      * @return the actual length read; may be less than requested if EOF was reached
 2931  
      * @throws IOException if a read error occurs
 2932  
      * @since 2.5
 2933  
      */
 2934  
     public static int read(final ReadableByteChannel input, final ByteBuffer buffer) throws IOException {
 2935  14
         final int length = buffer.remaining();
 2936  18
         while (buffer.remaining() > 0) {
 2937  8
             final int count = input.read(buffer);
 2938  8
             if (EOF == count) { // EOF
 2939  4
                 break;
 2940  
             }
 2941  4
         }
 2942  14
         return length - buffer.remaining();
 2943  
     }
 2944  
 
 2945  
     /**
 2946  
      * Reads the requested number of characters or fail if there are not enough left.
 2947  
      * <p>
 2948  
      * This allows for the possibility that {@link Reader#read(char[], int, int)} may
 2949  
      * not read as many characters as requested (most likely because of reaching EOF).
 2950  
      *
 2951  
      * @param input where to read input from
 2952  
      * @param buffer destination
 2953  
      * @param offset initial offset into buffer
 2954  
      * @param length length to read, must be &gt;= 0
 2955  
      *
 2956  
      * @throws IOException if there is a problem reading the file
 2957  
      * @throws IllegalArgumentException if length is negative
 2958  
      * @throws EOFException if the number of characters read was incorrect
 2959  
      * @since 2.2
 2960  
      */
 2961  
     public static void readFully(final Reader input, final char[] buffer, final int offset, final int length) throws IOException {
 2962  10
         final int actual = read(input, buffer, offset, length);
 2963  8
         if (actual != length) {
 2964  2
             throw new EOFException("Length to read: " + length + " actual: " + actual);
 2965  
         }
 2966  6
     }
 2967  
 
 2968  
     /**
 2969  
      * Reads the requested number of characters or fail if there are not enough left.
 2970  
      * <p>
 2971  
      * This allows for the possibility that {@link Reader#read(char[], int, int)} may
 2972  
      * not read as many characters as requested (most likely because of reaching EOF).
 2973  
      *
 2974  
      * @param input where to read input from
 2975  
      * @param buffer destination
 2976  
      *
 2977  
      * @throws IOException if there is a problem reading the file
 2978  
      * @throws IllegalArgumentException if length is negative
 2979  
      * @throws EOFException if the number of characters read was incorrect
 2980  
      * @since 2.2
 2981  
      */
 2982  
     public static void readFully(final Reader input, final char[] buffer) throws IOException {
 2983  0
         readFully(input, buffer, 0, buffer.length);
 2984  0
     }
 2985  
 
 2986  
     /**
 2987  
      * Reads the requested number of bytes or fail if there are not enough left.
 2988  
      * <p>
 2989  
      * This allows for the possibility that {@link InputStream#read(byte[], int, int)} may
 2990  
      * not read as many bytes as requested (most likely because of reaching EOF).
 2991  
      *
 2992  
      * @param input where to read input from
 2993  
      * @param buffer destination
 2994  
      * @param offset initial offset into buffer
 2995  
      * @param length length to read, must be &gt;= 0
 2996  
      *
 2997  
      * @throws IOException if there is a problem reading the file
 2998  
      * @throws IllegalArgumentException if length is negative
 2999  
      * @throws EOFException if the number of bytes read was incorrect
 3000  
      * @since 2.2
 3001  
      */
 3002  
     public static void readFully(final InputStream input, final byte[] buffer, final int offset, final int length) throws IOException {
 3003  12
         final int actual = read(input, buffer, offset, length);
 3004  10
         if (actual != length) {
 3005  2
             throw new EOFException("Length to read: " + length + " actual: " + actual);
 3006  
         }
 3007  8
     }
 3008  
 
 3009  
     /**
 3010  
      * Reads the requested number of bytes or fail if there are not enough left.
 3011  
      * <p>
 3012  
      * This allows for the possibility that {@link InputStream#read(byte[], int, int)} may
 3013  
      * not read as many bytes as requested (most likely because of reaching EOF).
 3014  
      *
 3015  
      * @param input where to read input from
 3016  
      * @param buffer destination
 3017  
      *
 3018  
      * @throws IOException if there is a problem reading the file
 3019  
      * @throws IllegalArgumentException if length is negative
 3020  
      * @throws EOFException if the number of bytes read was incorrect
 3021  
      * @since 2.2
 3022  
      */
 3023  
     public static void readFully(final InputStream input, final byte[] buffer) throws IOException {
 3024  0
         readFully(input, buffer, 0, buffer.length);
 3025  0
     }
 3026  
 
 3027  
     /**
 3028  
      * Reads the requested number of bytes or fail if there are not enough left.
 3029  
      * <p>
 3030  
      * This allows for the possibility that {@link InputStream#read(byte[], int, int)} may
 3031  
      * not read as many bytes as requested (most likely because of reaching EOF).
 3032  
      *
 3033  
      * @param input where to read input from
 3034  
      * @param length length to read, must be &gt;= 0
 3035  
      *
 3036  
      * @throws IOException if there is a problem reading the file
 3037  
      * @throws IllegalArgumentException if length is negative
 3038  
      * @throws EOFException if the number of bytes read was incorrect
 3039  
      *
 3040  
      * @since 2.5
 3041  
      */
 3042  
     public static byte[] readFully(final InputStream input, final int length) throws IOException {
 3043  2
         final byte[] buffer = new byte[length];
 3044  2
         readFully(input, buffer, 0, buffer.length);
 3045  2
         return buffer;
 3046  
     }
 3047  
 
 3048  
     /**
 3049  
      * Reads the requested number of bytes or fail if there are not enough left.
 3050  
      * <p>
 3051  
      * This allows for the possibility that {@link ReadableByteChannel#read(ByteBuffer)} may
 3052  
      * not read as many bytes as requested (most likely because of reaching EOF).
 3053  
      *
 3054  
      * @param input the byte channel to read
 3055  
      * @param buffer byte buffer destination
 3056  
      *
 3057  
      * @throws IOException if there is a problem reading the file
 3058  
      * @throws EOFException if the number of bytes read was incorrect
 3059  
      * @since 2.5
 3060  
      */
 3061  
     public static void readFully(final ReadableByteChannel input, final ByteBuffer buffer) throws IOException {
 3062  10
         final int expected = buffer.remaining();
 3063  10
         final int actual = read(input, buffer);
 3064  10
         if (actual != expected) {
 3065  4
             throw new EOFException("Length to read: " + expected + " actual: " + actual);
 3066  
         }
 3067  6
     }
 3068  
     
 3069  
 }