001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.io;
018
019import java.io.BufferedInputStream;
020import java.io.BufferedOutputStream;
021import java.io.BufferedReader;
022import java.io.BufferedWriter;
023import java.io.ByteArrayInputStream;
024import java.io.CharArrayWriter;
025import java.io.Closeable;
026import java.io.EOFException;
027import java.io.File;
028import java.io.IOException;
029import java.io.InputStream;
030import java.io.InputStreamReader;
031import java.io.OutputStream;
032import java.io.OutputStreamWriter;
033import java.io.PrintWriter;
034import java.io.Reader;
035import java.io.Writer;
036import java.net.HttpURLConnection;
037import java.net.ServerSocket;
038import java.net.Socket;
039import java.net.URI;
040import java.net.URL;
041import java.net.URLConnection;
042import java.nio.ByteBuffer;
043import java.nio.channels.ReadableByteChannel;
044import java.nio.channels.Selector;
045import java.nio.charset.Charset;
046import java.util.ArrayList;
047import java.util.Collection;
048import java.util.List;
049
050import org.apache.commons.io.output.ByteArrayOutputStream;
051import org.apache.commons.io.output.StringBuilderWriter;
052
053/**
054 * General IO stream manipulation utilities.
055 * <p>
056 * This class provides static utility methods for input/output operations.
057 * <ul>
058 * <li><b>[Deprecated]</b> closeQuietly - these methods close a stream ignoring nulls and exceptions
059 * <li>toXxx/read - these methods read data from a stream
060 * <li>write - these methods write data to a stream
061 * <li>copy - these methods copy all the data from one stream to another
062 * <li>contentEquals - these methods compare the content of two streams
063 * </ul>
064 * <p>
065 * The byte-to-char methods and char-to-byte methods involve a conversion step.
066 * Two methods are provided in each case, one that uses the platform default
067 * encoding and the other which allows you to specify an encoding. You are
068 * encouraged to always specify an encoding because relying on the platform
069 * default can lead to unexpected results, for example when moving from
070 * development to production.
071 * <p>
072 * All the methods in this class that read a stream are buffered internally.
073 * This means that there is no cause to use a <code>BufferedInputStream</code>
074 * or <code>BufferedReader</code>. The default buffer size of 4K has been shown
075 * to be efficient in tests.
076 * <p>
077 * The various copy methods all delegate the actual copying to one of the following methods:
078 * <ul>
079 * <li>{@link #copyLarge(InputStream, OutputStream, byte[])}</li>
080 * <li>{@link #copyLarge(InputStream, OutputStream, long, long, byte[])}</li>
081 * <li>{@link #copyLarge(Reader, Writer, char[])}</li>
082 * <li>{@link #copyLarge(Reader, Writer, long, long, char[])}</li>
083 * </ul>
084 * For example, {@link #copy(InputStream, OutputStream)} calls {@link #copyLarge(InputStream, OutputStream)}
085 * which calls {@link #copy(InputStream, OutputStream, int)} which creates the buffer and calls
086 * {@link #copyLarge(InputStream, OutputStream, byte[])}.
087 * <p>
088 * Applications can re-use buffers by using the underlying methods directly.
089 * This may improve performance for applications that need to do a lot of copying.
090 * <p>
091 * Wherever possible, the methods in this class do <em>not</em> flush or close
092 * the stream. This is to avoid making non-portable assumptions about the
093 * streams' origin and further use. Thus the caller is still responsible for
094 * closing streams after use.
095 * <p>
096 * Origin of code: Excalibur.
097 *
098 */
099public 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, final 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, final 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, final 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, final 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, final 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, final 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, final 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                final 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                final 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}