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