View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.io;
18  
19  import java.io.BufferedInputStream;
20  import java.io.BufferedOutputStream;
21  import java.io.BufferedReader;
22  import java.io.BufferedWriter;
23  import java.io.ByteArrayInputStream;
24  import java.io.CharArrayWriter;
25  import java.io.Closeable;
26  import java.io.EOFException;
27  import java.io.File;
28  import java.io.IOException;
29  import java.io.InputStream;
30  import java.io.InputStreamReader;
31  import java.io.OutputStream;
32  import java.io.OutputStreamWriter;
33  import java.io.Reader;
34  import java.io.UncheckedIOException;
35  import java.io.Writer;
36  import java.net.HttpURLConnection;
37  import java.net.ServerSocket;
38  import java.net.Socket;
39  import java.net.URI;
40  import java.net.URL;
41  import java.net.URLConnection;
42  import java.nio.ByteBuffer;
43  import java.nio.CharBuffer;
44  import java.nio.channels.Channels;
45  import java.nio.channels.ReadableByteChannel;
46  import java.nio.channels.Selector;
47  import java.nio.charset.Charset;
48  import java.nio.charset.StandardCharsets;
49  import java.nio.file.Files;
50  import java.util.Arrays;
51  import java.util.Collection;
52  import java.util.Iterator;
53  import java.util.List;
54  import java.util.Objects;
55  import java.util.function.Consumer;
56  import java.util.function.Supplier;
57  import java.util.stream.Collectors;
58  import java.util.stream.Stream;
59  import java.util.zip.InflaterInputStream;
60  
61  import org.apache.commons.io.function.IOConsumer;
62  import org.apache.commons.io.function.IOSupplier;
63  import org.apache.commons.io.function.IOTriFunction;
64  import org.apache.commons.io.input.QueueInputStream;
65  import org.apache.commons.io.output.AppendableWriter;
66  import org.apache.commons.io.output.ByteArrayOutputStream;
67  import org.apache.commons.io.output.NullOutputStream;
68  import org.apache.commons.io.output.NullWriter;
69  import org.apache.commons.io.output.StringBuilderWriter;
70  import org.apache.commons.io.output.ThresholdingOutputStream;
71  import org.apache.commons.io.output.UnsynchronizedByteArrayOutputStream;
72  
73  /**
74   * General IO stream manipulation utilities.
75   * <p>
76   * This class provides static utility methods for input/output operations.
77   * </p>
78   * <ul>
79   * <li>closeQuietly - these methods close a stream ignoring nulls and exceptions
80   * <li>toXxx/read - these methods read data from a stream
81   * <li>write - these methods write data to a stream
82   * <li>copy - these methods copy all the data from one stream to another
83   * <li>contentEquals - these methods compare the content of two streams
84   * </ul>
85   * <p>
86   * The byte-to-char methods and char-to-byte methods involve a conversion step.
87   * Two methods are provided in each case, one that uses the platform default
88   * encoding and the other which allows you to specify an encoding. You are
89   * encouraged to always specify an encoding because relying on the platform
90   * default can lead to unexpected results, for example when moving from
91   * development to production.
92   * </p>
93   * <p>
94   * All the methods in this class that read a stream are buffered internally.
95   * This means that there is no cause to use a {@link BufferedInputStream}
96   * or {@link BufferedReader}. The default buffer size of 4K has been shown
97   * to be efficient in tests.
98   * </p>
99   * <p>
100  * The various copy methods all delegate the actual copying to one of the following methods:
101  * </p>
102  * <ul>
103  * <li>{@link #copyLarge(InputStream, OutputStream, byte[])}</li>
104  * <li>{@link #copyLarge(InputStream, OutputStream, long, long, byte[])}</li>
105  * <li>{@link #copyLarge(Reader, Writer, char[])}</li>
106  * <li>{@link #copyLarge(Reader, Writer, long, long, char[])}</li>
107  * </ul>
108  * For example, {@link #copy(InputStream, OutputStream)} calls {@link #copyLarge(InputStream, OutputStream)}
109  * which calls {@link #copy(InputStream, OutputStream, int)} which creates the buffer and calls
110  * {@link #copyLarge(InputStream, OutputStream, byte[])}.
111  * <p>
112  * Applications can re-use buffers by using the underlying methods directly.
113  * This may improve performance for applications that need to do a lot of copying.
114  * </p>
115  * <p>
116  * Wherever possible, the methods in this class do <em>not</em> flush or close
117  * the stream. This is to avoid making non-portable assumptions about the
118  * streams' origin and further use. Thus the caller is still responsible for
119  * closing streams after use.
120  * </p>
121  * <p>
122  * Provenance: Excalibur.
123  * </p>
124  */
125 public class IOUtils {
126     // NOTE: This class is focused on InputStream, OutputStream, Reader and
127     // Writer. Each method should take at least one of these as a parameter,
128     // or return one of them.
129 
130     /**
131      * CR char.
132      *
133      * @since 2.9.0
134      */
135     public static final int CR = '\r';
136 
137     /**
138      * The default buffer size ({@value}) to use in copy methods.
139      */
140     public static final int DEFAULT_BUFFER_SIZE = 8192;
141 
142     /**
143      * The system directory separator character.
144      */
145     public static final char DIR_SEPARATOR = File.separatorChar;
146 
147     /**
148      * The Unix directory separator character.
149      */
150     public static final char DIR_SEPARATOR_UNIX = '/';
151 
152     /**
153      * The Windows directory separator character.
154      */
155     public static final char DIR_SEPARATOR_WINDOWS = '\\';
156 
157     /**
158      * A singleton empty byte array.
159      *
160      *  @since 2.9.0
161      */
162     public static final byte[] EMPTY_BYTE_ARRAY = {};
163 
164     /**
165      * Represents the end-of-file (or stream).
166      * @since 2.5 (made public)
167      */
168     public static final int EOF = -1;
169 
170     /**
171      * LF char.
172      *
173      * @since 2.9.0
174      */
175     public static final int LF = '\n';
176 
177     /**
178      * The system line separator string.
179      *
180      * @deprecated Use {@link System#lineSeparator()}.
181      */
182     @Deprecated
183     public static final String LINE_SEPARATOR = System.lineSeparator();
184 
185     /**
186      * The Unix line separator string.
187      *
188      * @see StandardLineSeparator#LF
189      */
190     public static final String LINE_SEPARATOR_UNIX = StandardLineSeparator.LF.getString();
191 
192     /**
193      * The Windows line separator string.
194      *
195      * @see StandardLineSeparator#CRLF
196      */
197     public static final String LINE_SEPARATOR_WINDOWS = StandardLineSeparator.CRLF.getString();
198 
199     /**
200      * Internal byte array buffer, intended for both reading and writing.
201      */
202     private static final ThreadLocal<byte[]> SCRATCH_BYTE_BUFFER_RW = ThreadLocal.withInitial(IOUtils::byteArray);
203 
204     /**
205      * Internal byte array buffer, intended for write only operations.
206      */
207     private static final byte[] SCRATCH_BYTE_BUFFER_WO = byteArray();
208 
209     /**
210      * Internal char array buffer, intended for both reading and writing.
211      */
212     private static final ThreadLocal<char[]> SCRATCH_CHAR_BUFFER_RW = ThreadLocal.withInitial(IOUtils::charArray);
213 
214     /**
215      * Internal char array buffer, intended for write only operations.
216      */
217     private static final char[] SCRATCH_CHAR_BUFFER_WO = charArray();
218 
219     /**
220      * Returns the given InputStream if it is already a {@link BufferedInputStream}, otherwise creates a
221      * BufferedInputStream from the given InputStream.
222      *
223      * @param inputStream the InputStream to wrap or return (not null)
224      * @return the given InputStream or a new {@link BufferedInputStream} for the given InputStream
225      * @throws NullPointerException if the input parameter is null
226      * @since 2.5
227      */
228     @SuppressWarnings("resource") // parameter null check
229     public static BufferedInputStream buffer(final InputStream inputStream) {
230         // reject null early on rather than waiting for IO operation to fail
231         // not checked by BufferedInputStream
232         Objects.requireNonNull(inputStream, "inputStream");
233         return inputStream instanceof BufferedInputStream ?
234                 (BufferedInputStream) inputStream : new BufferedInputStream(inputStream);
235     }
236 
237     /**
238      * Returns the given InputStream if it is already a {@link BufferedInputStream}, otherwise creates a
239      * BufferedInputStream from the given InputStream.
240      *
241      * @param inputStream the InputStream to wrap or return (not null)
242      * @param size the buffer size, if a new BufferedInputStream is created.
243      * @return the given InputStream or a new {@link BufferedInputStream} for the given InputStream
244      * @throws NullPointerException if the input parameter is null
245      * @since 2.5
246      */
247     @SuppressWarnings("resource") // parameter null check
248     public static BufferedInputStream buffer(final InputStream inputStream, final int size) {
249         // reject null early on rather than waiting for IO operation to fail
250         // not checked by BufferedInputStream
251         Objects.requireNonNull(inputStream, "inputStream");
252         return inputStream instanceof BufferedInputStream ?
253                 (BufferedInputStream) inputStream : new BufferedInputStream(inputStream, size);
254     }
255 
256     /**
257      * Returns the given OutputStream if it is already a {@link BufferedOutputStream}, otherwise creates a
258      * BufferedOutputStream from the given OutputStream.
259      *
260      * @param outputStream the OutputStream to wrap or return (not null)
261      * @return the given OutputStream or a new {@link BufferedOutputStream} for the given OutputStream
262      * @throws NullPointerException if the input parameter is null
263      * @since 2.5
264      */
265     @SuppressWarnings("resource") // parameter null check
266     public static BufferedOutputStream buffer(final OutputStream outputStream) {
267         // reject null early on rather than waiting for IO operation to fail
268         // not checked by BufferedInputStream
269         Objects.requireNonNull(outputStream, "outputStream");
270         return outputStream instanceof BufferedOutputStream ?
271                 (BufferedOutputStream) outputStream : new BufferedOutputStream(outputStream);
272     }
273 
274     /**
275      * Returns the given OutputStream if it is already a {@link BufferedOutputStream}, otherwise creates a
276      * BufferedOutputStream from the given OutputStream.
277      *
278      * @param outputStream the OutputStream to wrap or return (not null)
279      * @param size the buffer size, if a new BufferedOutputStream is created.
280      * @return the given OutputStream or a new {@link BufferedOutputStream} for the given OutputStream
281      * @throws NullPointerException if the input parameter is null
282      * @since 2.5
283      */
284     @SuppressWarnings("resource") // parameter null check
285     public static BufferedOutputStream buffer(final OutputStream outputStream, final int size) {
286         // reject null early on rather than waiting for IO operation to fail
287         // not checked by BufferedInputStream
288         Objects.requireNonNull(outputStream, "outputStream");
289         return outputStream instanceof BufferedOutputStream ?
290                 (BufferedOutputStream) outputStream : new BufferedOutputStream(outputStream, size);
291     }
292 
293     /**
294      * Returns the given reader if it is already a {@link BufferedReader}, otherwise creates a BufferedReader from
295      * the given reader.
296      *
297      * @param reader the reader to wrap or return (not null)
298      * @return the given reader or a new {@link BufferedReader} for the given reader
299      * @throws NullPointerException if the input parameter is null
300      * @since 2.5
301      */
302     public static BufferedReader buffer(final Reader reader) {
303         return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader);
304     }
305 
306     /**
307      * Returns the given reader if it is already a {@link BufferedReader}, otherwise creates a BufferedReader from the
308      * given reader.
309      *
310      * @param reader the reader to wrap or return (not null)
311      * @param size the buffer size, if a new BufferedReader is created.
312      * @return the given reader or a new {@link BufferedReader} for the given reader
313      * @throws NullPointerException if the input parameter is null
314      * @since 2.5
315      */
316     public static BufferedReader buffer(final Reader reader, final int size) {
317         return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader, size);
318     }
319 
320     /**
321      * Returns the given Writer if it is already a {@link BufferedWriter}, otherwise creates a BufferedWriter from the
322      * given Writer.
323      *
324      * @param writer the Writer to wrap or return (not null)
325      * @return the given Writer or a new {@link BufferedWriter} for the given Writer
326      * @throws NullPointerException if the input parameter is null
327      * @since 2.5
328      */
329     public static BufferedWriter buffer(final Writer writer) {
330         return writer instanceof BufferedWriter ? (BufferedWriter) writer : new BufferedWriter(writer);
331     }
332 
333     /**
334      * Returns the given Writer if it is already a {@link BufferedWriter}, otherwise creates a BufferedWriter from the
335      * given Writer.
336      *
337      * @param writer the Writer to wrap or return (not null)
338      * @param size the buffer size, if a new BufferedWriter is created.
339      * @return the given Writer or a new {@link BufferedWriter} for the given Writer
340      * @throws NullPointerException if the input parameter is null
341      * @since 2.5
342      */
343     public static BufferedWriter buffer(final Writer writer, final int size) {
344         return writer instanceof BufferedWriter ? (BufferedWriter) writer : new BufferedWriter(writer, size);
345     }
346 
347     /**
348      * Returns a new byte array of size {@link #DEFAULT_BUFFER_SIZE}.
349      *
350      * @return a new byte array of size {@link #DEFAULT_BUFFER_SIZE}.
351      * @since 2.9.0
352      */
353     public static byte[] byteArray() {
354         return byteArray(DEFAULT_BUFFER_SIZE);
355     }
356 
357     /**
358      * Returns a new byte array of the given size.
359      *
360      * TODO Consider guarding or warning against large allocations...
361      *
362      * @param size array size.
363      * @return a new byte array of the given size.
364      * @throws NegativeArraySizeException if the size is negative.
365      * @since 2.9.0
366      */
367     public static byte[] byteArray(final int size) {
368         return new byte[size];
369     }
370 
371     /**
372      * Returns a new char array of size {@link #DEFAULT_BUFFER_SIZE}.
373      *
374      * @return a new char array of size {@link #DEFAULT_BUFFER_SIZE}.
375      * @since 2.9.0
376      */
377     private static char[] charArray() {
378         return charArray(DEFAULT_BUFFER_SIZE);
379     }
380 
381     /**
382      * Returns a new char array of the given size.
383      *
384      * TODO Consider guarding or warning against large allocations...
385      *
386      * @param size array size.
387      * @return a new char array of the given size.
388      * @since 2.9.0
389      */
390     private static char[] charArray(final int size) {
391         return new char[size];
392     }
393 
394     /**
395      * Clears any state.
396      * <ul>
397      * <li>Removes the current thread's value for thread-local variables.</li>
398      * <li>Sets static scratch arrays to 0s.</li>
399      * </ul>
400      * @see IO#clear()
401      */
402     static void clear() {
403         SCRATCH_BYTE_BUFFER_RW.remove();
404         SCRATCH_CHAR_BUFFER_RW.remove();
405         Arrays.fill(SCRATCH_BYTE_BUFFER_WO, (byte) 0);
406         Arrays.fill(SCRATCH_CHAR_BUFFER_WO, (char) 0);
407     }
408 
409     /**
410      * Closes the given {@link Closeable} as a null-safe operation.
411      *
412      * @param closeable The resource to close, may be null.
413      * @throws IOException if an I/O error occurs.
414      * @since 2.7
415      */
416     public static void close(final Closeable closeable) throws IOException {
417         if (closeable != null) {
418             closeable.close();
419         }
420     }
421 
422     /**
423      * Closes the given {@link Closeable}s as null-safe operations.
424      *
425      * @param closeables The resource(s) to close, may be null.
426      * @throws IOExceptionList if an I/O error occurs.
427      * @since 2.8.0
428      */
429     public static void close(final Closeable... closeables) throws IOExceptionList {
430         IOConsumer.forAll(IOUtils::close, closeables);
431     }
432 
433     /**
434      * Closes the given {@link Closeable} as a null-safe operation.
435      *
436      * @param closeable The resource to close, may be null.
437      * @param consumer Consume the IOException thrown by {@link Closeable#close()}.
438      * @throws IOException if an I/O error occurs.
439      * @since 2.7
440      */
441     public static void close(final Closeable closeable, final IOConsumer<IOException> consumer) throws IOException {
442         if (closeable != null) {
443             try {
444                 closeable.close();
445             } catch (final IOException e) {
446                 if (consumer != null) {
447                     consumer.accept(e);
448                 }
449             }
450         }
451     }
452 
453     /**
454      * Closes a URLConnection.
455      *
456      * @param conn the connection to close.
457      * @since 2.4
458      */
459     public static void close(final URLConnection conn) {
460         if (conn instanceof HttpURLConnection) {
461             ((HttpURLConnection) conn).disconnect();
462         }
463     }
464 
465     /**
466      * Avoids the need to type cast.
467      *
468      * @param closeable the object to close, may be null
469      */
470     private static void closeQ(final Closeable closeable) {
471         closeQuietly(closeable, null);
472     }
473 
474     /**
475      * Closes a {@link Closeable} unconditionally.
476      *
477      * <p>
478      * Equivalent to {@link Closeable#close()}, except any exceptions will be ignored. This is typically used in
479      * finally blocks.
480      * <p>
481      * Example code:
482      * </p>
483      * <pre>
484      * Closeable closeable = null;
485      * try {
486      *     closeable = new FileReader(&quot;foo.txt&quot;);
487      *     // process closeable
488      *     closeable.close();
489      * } catch (Exception e) {
490      *     // error handling
491      * } finally {
492      *     IOUtils.closeQuietly(closeable);
493      * }
494      * </pre>
495      * <p>
496      * Closing all streams:
497      * </p>
498      * <pre>
499      * try {
500      *     return IOUtils.copy(inputStream, outputStream);
501      * } finally {
502      *     IOUtils.closeQuietly(inputStream);
503      *     IOUtils.closeQuietly(outputStream);
504      * }
505      * </pre>
506      * <p>
507      * Also consider using a try-with-resources statement where appropriate.
508      * </p>
509      *
510      * @param closeable the objects to close, may be null or already closed
511      * @since 2.0
512      *
513      * @see Throwable#addSuppressed(Throwable)
514      */
515     public static void closeQuietly(final Closeable closeable) {
516         closeQuietly(closeable, null);
517     }
518 
519     /**
520      * Closes a {@link Closeable} unconditionally.
521      * <p>
522      * Equivalent to {@link Closeable#close()}, except any exceptions will be ignored.
523      * <p>
524      * This is typically used in finally blocks to ensure that the closeable is closed
525      * even if an Exception was thrown before the normal close statement was reached.
526      * <br>
527      * <b>It should not be used to replace the close statement(s)
528      * which should be present for the non-exceptional case.</b>
529      * <br>
530      * It is only intended to simplify tidying up where normal processing has already failed
531      * and reporting close failure as well is not necessary or useful.
532      * <p>
533      * Example code:
534      * </p>
535      * <pre>
536      * Closeable closeable = null;
537      * try {
538      *     closeable = new FileReader(&quot;foo.txt&quot;);
539      *     // processing using the closeable; may throw an Exception
540      *     closeable.close(); // Normal close - exceptions not ignored
541      * } catch (Exception e) {
542      *     // error handling
543      * } finally {
544      *     <b>IOUtils.closeQuietly(closeable); // In case normal close was skipped due to Exception</b>
545      * }
546      * </pre>
547      * <p>
548      * Closing all streams:
549      * <br>
550      * <pre>
551      * try {
552      *     return IOUtils.copy(inputStream, outputStream);
553      * } finally {
554      *     IOUtils.closeQuietly(inputStream, outputStream);
555      * }
556      * </pre>
557      * <p>
558      * Also consider using a try-with-resources statement where appropriate.
559      * </p>
560      * @param closeables the objects to close, may be null or already closed
561      * @see #closeQuietly(Closeable)
562      * @since 2.5
563      * @see Throwable#addSuppressed(Throwable)
564      */
565     public static void closeQuietly(final Closeable... closeables) {
566         if (closeables != null) {
567             closeQuietly(Arrays.stream(closeables));
568         }
569     }
570 
571     /**
572      * Closes the given {@link Closeable} as a null-safe operation while consuming IOException by the given {@code consumer}.
573      *
574      * @param closeable The resource to close, may be null.
575      * @param consumer Consumes the IOException thrown by {@link Closeable#close()}.
576      * @since 2.7
577      */
578     public static void closeQuietly(final Closeable closeable, final Consumer<IOException> consumer) {
579         if (closeable != null) {
580             try {
581                 closeable.close();
582             } catch (final IOException e) {
583                 if (consumer != null) {
584                     consumer.accept(e);
585                 }
586             }
587         }
588     }
589 
590     /**
591      * Closes an {@link InputStream} unconditionally.
592      * <p>
593      * Equivalent to {@link InputStream#close()}, except any exceptions will be ignored.
594      * This is typically used in finally blocks.
595      * </p>
596      * <p>
597      * Example code:
598      * </p>
599      * <pre>
600      *   byte[] data = new byte[1024];
601      *   InputStream in = null;
602      *   try {
603      *       in = new FileInputStream("foo.txt");
604      *       in.read(data);
605      *       in.close(); //close errors are handled
606      *   } catch (Exception e) {
607      *       // error handling
608      *   } finally {
609      *       IOUtils.closeQuietly(in);
610      *   }
611      * </pre>
612      * <p>
613      * Also consider using a try-with-resources statement where appropriate.
614      * </p>
615      *
616      * @param input the InputStream to close, may be null or already closed
617      * @see Throwable#addSuppressed(Throwable)
618      */
619     public static void closeQuietly(final InputStream input) {
620         closeQ(input);
621     }
622 
623     /**
624      * Closes an iterable of {@link Closeable} unconditionally.
625      * <p>
626      * Equivalent calling {@link Closeable#close()} on each element, except any exceptions will be ignored.
627      * </p>
628      *
629      * @param closeables the objects to close, may be null or already closed
630      * @see #closeQuietly(Closeable)
631      * @since 2.12.0
632      */
633     public static void closeQuietly(final Iterable<Closeable> closeables) {
634         if (closeables != null) {
635             closeables.forEach(IOUtils::closeQuietly);
636         }
637     }
638 
639     /**
640      * Closes an {@link OutputStream} unconditionally.
641      * <p>
642      * Equivalent to {@link OutputStream#close()}, except any exceptions will be ignored.
643      * This is typically used in finally blocks.
644      * </p>
645      * <p>
646      * Example code:
647      * </p>
648      * <pre>
649      * byte[] data = "Hello, World".getBytes();
650      *
651      * OutputStream out = null;
652      * try {
653      *     out = new FileOutputStream("foo.txt");
654      *     out.write(data);
655      *     out.close(); //close errors are handled
656      * } catch (IOException e) {
657      *     // error handling
658      * } finally {
659      *     IOUtils.closeQuietly(out);
660      * }
661      * </pre>
662      * <p>
663      * Also consider using a try-with-resources statement where appropriate.
664      * </p>
665      *
666      * @param output the OutputStream to close, may be null or already closed
667      * @see Throwable#addSuppressed(Throwable)
668      */
669     public static void closeQuietly(final OutputStream output) {
670         closeQ(output);
671     }
672 
673     /**
674      * Closes an {@link Reader} unconditionally.
675      * <p>
676      * Equivalent to {@link Reader#close()}, except any exceptions will be ignored.
677      * This is typically used in finally blocks.
678      * </p>
679      * <p>
680      * Example code:
681      * </p>
682      * <pre>
683      *   char[] data = new char[1024];
684      *   Reader in = null;
685      *   try {
686      *       in = new FileReader("foo.txt");
687      *       in.read(data);
688      *       in.close(); //close errors are handled
689      *   } catch (Exception e) {
690      *       // error handling
691      *   } finally {
692      *       IOUtils.closeQuietly(in);
693      *   }
694      * </pre>
695      * <p>
696      * Also consider using a try-with-resources statement where appropriate.
697      * </p>
698      *
699      * @param reader the Reader to close, may be null or already closed
700      * @see Throwable#addSuppressed(Throwable)
701      */
702     public static void closeQuietly(final Reader reader) {
703         closeQ(reader);
704     }
705 
706     /**
707      * Closes a {@link Selector} unconditionally.
708      * <p>
709      * Equivalent to {@link Selector#close()}, except any exceptions will be ignored.
710      * This is typically used in finally blocks.
711      * </p>
712      * <p>
713      * Example code:
714      * </p>
715      * <pre>
716      *   Selector selector = null;
717      *   try {
718      *       selector = Selector.open();
719      *       // process socket
720      *
721      *   } catch (Exception e) {
722      *       // error handling
723      *   } finally {
724      *       IOUtils.closeQuietly(selector);
725      *   }
726      * </pre>
727      * <p>
728      * Also consider using a try-with-resources statement where appropriate.
729      * </p>
730      *
731      * @param selector the Selector to close, may be null or already closed
732      * @since 2.2
733      * @see Throwable#addSuppressed(Throwable)
734      */
735     public static void closeQuietly(final Selector selector) {
736         closeQ(selector);
737     }
738 
739     /**
740      * Closes a {@link ServerSocket} unconditionally.
741      * <p>
742      * Equivalent to {@link ServerSocket#close()}, except any exceptions will be ignored.
743      * This is typically used in finally blocks.
744      * </p>
745      * <p>
746      * Example code:
747      * </p>
748      * <pre>
749      *   ServerSocket socket = null;
750      *   try {
751      *       socket = new ServerSocket();
752      *       // process socket
753      *       socket.close();
754      *   } catch (Exception e) {
755      *       // error handling
756      *   } finally {
757      *       IOUtils.closeQuietly(socket);
758      *   }
759      * </pre>
760      * <p>
761      * Also consider using a try-with-resources statement where appropriate.
762      * </p>
763      *
764      * @param serverSocket the ServerSocket to close, may be null or already closed
765      * @since 2.2
766      * @see Throwable#addSuppressed(Throwable)
767      */
768     public static void closeQuietly(final ServerSocket serverSocket) {
769         closeQ(serverSocket);
770     }
771 
772     /**
773      * Closes a {@link Socket} unconditionally.
774      * <p>
775      * Equivalent to {@link Socket#close()}, except any exceptions will be ignored.
776      * This is typically used in finally blocks.
777      * </p>
778      * <p>
779      * Example code:
780      * </p>
781      * <pre>
782      *   Socket socket = null;
783      *   try {
784      *       socket = new Socket("http://www.foo.com/", 80);
785      *       // process socket
786      *       socket.close();
787      *   } catch (Exception e) {
788      *       // error handling
789      *   } finally {
790      *       IOUtils.closeQuietly(socket);
791      *   }
792      * </pre>
793      * <p>
794      * Also consider using a try-with-resources statement where appropriate.
795      * </p>
796      *
797      * @param socket the Socket to close, may be null or already closed
798      * @since 2.0
799      * @see Throwable#addSuppressed(Throwable)
800      */
801     public static void closeQuietly(final Socket socket) {
802         closeQ(socket);
803     }
804 
805     /**
806      * Closes a stream of {@link Closeable} unconditionally.
807      * <p>
808      * Equivalent calling {@link Closeable#close()} on each element, except any exceptions will be ignored.
809      * </p>
810      *
811      * @param closeables the objects to close, may be null or already closed
812      * @see #closeQuietly(Closeable)
813      * @since 2.12.0
814      */
815     public static void closeQuietly(final Stream<Closeable> closeables) {
816         if (closeables != null) {
817             closeables.forEach(IOUtils::closeQuietly);
818         }
819     }
820 
821     /**
822      * Closes an {@link Writer} unconditionally.
823      * <p>
824      * Equivalent to {@link Writer#close()}, except any exceptions will be ignored.
825      * This is typically used in finally blocks.
826      * </p>
827      * <p>
828      * Example code:
829      * </p>
830      * <pre>
831      *   Writer out = null;
832      *   try {
833      *       out = new StringWriter();
834      *       out.write("Hello World");
835      *       out.close(); //close errors are handled
836      *   } catch (Exception e) {
837      *       // error handling
838      *   } finally {
839      *       IOUtils.closeQuietly(out);
840      *   }
841      * </pre>
842      * <p>
843      * Also consider using a try-with-resources statement where appropriate.
844      * </p>
845      *
846      * @param writer the Writer to close, may be null or already closed
847      * @see Throwable#addSuppressed(Throwable)
848      */
849     public static void closeQuietly(final Writer writer) {
850         closeQ(writer);
851     }
852 
853     /**
854      * Consumes bytes from a {@link InputStream} and ignores them.
855      * <p>
856      * The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}.
857      * </p>
858      *
859      * @param input the {@link InputStream} to read.
860      * @return the number of bytes copied. or {@code 0} if {@code input is null}.
861      * @throws NullPointerException if the InputStream is {@code null}.
862      * @throws IOException if an I/O error occurs.
863      * @since 2.8.0
864      */
865     public static long consume(final InputStream input) throws IOException {
866         return copyLarge(input, NullOutputStream.INSTANCE);
867     }
868 
869     /**
870      * Consumes characters from a {@link Reader} and ignores them.
871      * <p>
872      * The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}.
873      * </p>
874      *
875      * @param input the {@link Reader} to read.
876      * @return the number of bytes copied. or {@code 0} if {@code input is null}.
877      * @throws NullPointerException if the Reader is {@code null}.
878      * @throws IOException if an I/O error occurs.
879      * @since 2.12.0
880      */
881     public static long consume(final Reader input) throws IOException {
882         return copyLarge(input, NullWriter.INSTANCE);
883     }
884 
885     /**
886      * Compares the contents of two Streams to determine if they are equal or
887      * not.
888      * <p>
889      * This method buffers the input internally using
890      * {@link BufferedInputStream} if they are not already buffered.
891      * </p>
892      *
893      * @param input1 the first stream
894      * @param input2 the second stream
895      * @return true if the content of the streams are equal or they both don't
896      * exist, false otherwise
897      * @throws IOException          if an I/O error occurs
898      */
899     public static boolean contentEquals(final InputStream input1, final InputStream input2) throws IOException {
900         // Before making any changes, please test with
901         // org.apache.commons.io.jmh.IOUtilsContentEqualsInputStreamsBenchmark
902         if (input1 == input2) {
903             return true;
904         }
905         if (input1 == null || input2 == null) {
906             return false;
907         }
908 
909         // reuse one
910         final byte[] array1 = getScratchByteArray();
911         // allocate another
912         final byte[] array2 = byteArray();
913         int pos1;
914         int pos2;
915         int count1;
916         int count2;
917         while (true) {
918             pos1 = 0;
919             pos2 = 0;
920             for (int index = 0; index < DEFAULT_BUFFER_SIZE; index++) {
921                 if (pos1 == index) {
922                     do {
923                         count1 = input1.read(array1, pos1, DEFAULT_BUFFER_SIZE - pos1);
924                     } while (count1 == 0);
925                     if (count1 == EOF) {
926                         return pos2 == index && input2.read() == EOF;
927                     }
928                     pos1 += count1;
929                 }
930                 if (pos2 == index) {
931                     do {
932                         count2 = input2.read(array2, pos2, DEFAULT_BUFFER_SIZE - pos2);
933                     } while (count2 == 0);
934                     if (count2 == EOF) {
935                         return pos1 == index && input1.read() == EOF;
936                     }
937                     pos2 += count2;
938                 }
939                 if (array1[index] != array2[index]) {
940                     return false;
941                 }
942             }
943         }
944     }
945 
946     // TODO Consider making public
947     private static boolean contentEquals(final Iterator<?> iterator1, final Iterator<?> iterator2) {
948         while (iterator1.hasNext()) {
949             if (!iterator2.hasNext()) {
950                 return false;
951             }
952             if (!Objects.equals(iterator1.next(), iterator2.next())) {
953                 return false;
954             }
955         }
956         return !iterator2.hasNext();
957     }
958 
959     /**
960      * Compares the contents of two Readers to determine if they are equal or not.
961      * <p>
962      * This method buffers the input internally using {@link BufferedReader} if they are not already buffered.
963      * </p>
964      *
965      * @param input1 the first reader
966      * @param input2 the second reader
967      * @return true if the content of the readers are equal or they both don't exist, false otherwise
968      * @throws NullPointerException if either input is null
969      * @throws IOException if an I/O error occurs
970      * @since 1.1
971      */
972     public static boolean contentEquals(final Reader input1, final Reader input2) throws IOException {
973         if (input1 == input2) {
974             return true;
975         }
976         if (input1 == null || input2 == null) {
977             return false;
978         }
979 
980         // reuse one
981         final char[] array1 = getScratchCharArray();
982         // but allocate another
983         final char[] array2 = charArray();
984         int pos1;
985         int pos2;
986         int count1;
987         int count2;
988         while (true) {
989             pos1 = 0;
990             pos2 = 0;
991             for (int index = 0; index < DEFAULT_BUFFER_SIZE; index++) {
992                 if (pos1 == index) {
993                     do {
994                         count1 = input1.read(array1, pos1, DEFAULT_BUFFER_SIZE - pos1);
995                     } while (count1 == 0);
996                     if (count1 == EOF) {
997                         return pos2 == index && input2.read() == EOF;
998                     }
999                     pos1 += count1;
1000                 }
1001                 if (pos2 == index) {
1002                     do {
1003                         count2 = input2.read(array2, pos2, DEFAULT_BUFFER_SIZE - pos2);
1004                     } while (count2 == 0);
1005                     if (count2 == EOF) {
1006                         return pos1 == index && input1.read() == EOF;
1007                     }
1008                     pos2 += count2;
1009                 }
1010                 if (array1[index] != array2[index]) {
1011                     return false;
1012                 }
1013             }
1014         }
1015     }
1016 
1017     // TODO Consider making public
1018     private static boolean contentEquals(final Stream<?> stream1, final Stream<?> stream2) {
1019         if (stream1 == stream2) {
1020             return true;
1021         }
1022         if (stream1 == null || stream2 == null) {
1023             return false;
1024         }
1025         return contentEquals(stream1.iterator(), stream2.iterator());
1026     }
1027 
1028     // TODO Consider making public
1029     private static boolean contentEqualsIgnoreEOL(final BufferedReader reader1, final BufferedReader reader2) {
1030         if (reader1 == reader2) {
1031             return true;
1032         }
1033         if (reader1 == null || reader2 == null) {
1034             return false;
1035         }
1036         return contentEquals(reader1.lines(), reader2.lines());
1037     }
1038 
1039     /**
1040      * Compares the contents of two Readers to determine if they are equal or
1041      * not, ignoring EOL characters.
1042      * <p>
1043      * This method buffers the input internally using
1044      * {@link BufferedReader} if they are not already buffered.
1045      * </p>
1046      *
1047      * @param reader1 the first reader
1048      * @param reader2 the second reader
1049      * @return true if the content of the readers are equal (ignoring EOL differences),  false otherwise
1050      * @throws NullPointerException if either input is null
1051      * @throws UncheckedIOException if an I/O error occurs
1052      * @since 2.2
1053      */
1054     @SuppressWarnings("resource")
1055     public static boolean contentEqualsIgnoreEOL(final Reader reader1, final Reader reader2) throws UncheckedIOException {
1056         if (reader1 == reader2) {
1057             return true;
1058         }
1059         if (reader1 == null || reader2 == null) {
1060             return false;
1061         }
1062         return contentEqualsIgnoreEOL(toBufferedReader(reader1), toBufferedReader(reader2));
1063     }
1064 
1065     /**
1066      * Copies bytes from an {@link InputStream} to an {@link OutputStream}.
1067      * <p>
1068      * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
1069      * </p>
1070      * <p>
1071      * Large streams (over 2GB) will return a bytes copied value of {@code -1} after the copy has completed since
1072      * the correct number of bytes cannot be returned as an int. For large streams use the
1073      * {@link #copyLarge(InputStream, OutputStream)} method.
1074      * </p>
1075      *
1076      * @param inputStream the {@link InputStream} to read.
1077      * @param outputStream the {@link OutputStream} to write.
1078      * @return the number of bytes copied, or -1 if greater than {@link Integer#MAX_VALUE}.
1079      * @throws NullPointerException if the InputStream is {@code null}.
1080      * @throws NullPointerException if the OutputStream is {@code null}.
1081      * @throws IOException if an I/O error occurs.
1082      * @since 1.1
1083      */
1084     public static int copy(final InputStream inputStream, final OutputStream outputStream) throws IOException {
1085         final long count = copyLarge(inputStream, outputStream);
1086         return count > Integer.MAX_VALUE ? EOF : (int) count;
1087     }
1088 
1089     /**
1090      * Copies bytes from an {@link InputStream} to an {@link OutputStream} using an internal buffer of the
1091      * given size.
1092      * <p>
1093      * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
1094      * </p>
1095      *
1096      * @param inputStream the {@link InputStream} to read.
1097      * @param outputStream the {@link OutputStream} to write to
1098      * @param bufferSize the bufferSize used to copy from the input to the output
1099      * @return the number of bytes copied.
1100      * @throws NullPointerException if the InputStream is {@code null}.
1101      * @throws NullPointerException if the OutputStream is {@code null}.
1102      * @throws IOException if an I/O error occurs.
1103      * @since 2.5
1104      */
1105     public static long copy(final InputStream inputStream, final OutputStream outputStream, final int bufferSize)
1106             throws IOException {
1107         return copyLarge(inputStream, outputStream, IOUtils.byteArray(bufferSize));
1108     }
1109 
1110     /**
1111      * Copies bytes from an {@link InputStream} to chars on a
1112      * {@link Writer} using the default character encoding of the platform.
1113      * <p>
1114      * This method buffers the input internally, so there is no need to use a
1115      * {@link BufferedInputStream}.
1116      * </p>
1117      * <p>
1118      * This method uses {@link InputStreamReader}.
1119      * </p>
1120      *
1121      * @param input the {@link InputStream} to read
1122      * @param writer the {@link Writer} to write to
1123      * @throws NullPointerException if the input or output is null
1124      * @throws IOException          if an I/O error occurs
1125      * @since 1.1
1126      * @deprecated 2.5 use {@link #copy(InputStream, Writer, Charset)} instead
1127      */
1128     @Deprecated
1129     public static void copy(final InputStream input, final Writer writer)
1130             throws IOException {
1131         copy(input, writer, Charset.defaultCharset());
1132     }
1133 
1134     /**
1135      * Copies bytes from an {@link InputStream} to chars on a
1136      * {@link Writer} using the specified character encoding.
1137      * <p>
1138      * This method buffers the input internally, so there is no need to use a
1139      * {@link BufferedInputStream}.
1140      * </p>
1141      * <p>
1142      * This method uses {@link InputStreamReader}.
1143      * </p>
1144      *
1145      * @param input the {@link InputStream} to read
1146      * @param writer the {@link Writer} to write to
1147      * @param inputCharset the charset to use for the input stream, null means platform default
1148      * @throws NullPointerException if the input or output is null
1149      * @throws IOException          if an I/O error occurs
1150      * @since 2.3
1151      */
1152     public static void copy(final InputStream input, final Writer writer, final Charset inputCharset)
1153             throws IOException {
1154         final InputStreamReader reader = new InputStreamReader(input, Charsets.toCharset(inputCharset));
1155         copy(reader, writer);
1156     }
1157 
1158     /**
1159      * Copies bytes from an {@link InputStream} to chars on a
1160      * {@link Writer} using the specified character encoding.
1161      * <p>
1162      * This method buffers the input internally, so there is no need to use a
1163      * {@link BufferedInputStream}.
1164      * </p>
1165      * <p>
1166      * Character encoding names can be found at
1167      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
1168      * </p>
1169      * <p>
1170      * This method uses {@link InputStreamReader}.
1171      * </p>
1172      *
1173      * @param input the {@link InputStream} to read
1174      * @param writer the {@link Writer} to write to
1175      * @param inputCharsetName the name of the requested charset for the InputStream, null means platform default
1176      * @throws NullPointerException                         if the input or output is null
1177      * @throws IOException                                  if an I/O error occurs
1178      * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io
1179      *                                                      .UnsupportedEncodingException} in version 2.2 if the
1180      *                                                      encoding is not supported.
1181      * @since 1.1
1182      */
1183     public static void copy(final InputStream input, final Writer writer, final String inputCharsetName)
1184             throws IOException {
1185         copy(input, writer, Charsets.toCharset(inputCharsetName));
1186     }
1187 
1188     /**
1189      * Copies bytes from a {@link java.io.ByteArrayOutputStream} to a {@link QueueInputStream}.
1190      * <p>
1191      * Unlike using JDK {@link java.io.PipedInputStream} and {@link java.io.PipedOutputStream} for this, this
1192      * solution works safely in a single thread environment.
1193      * </p>
1194      * <p>
1195      * Example usage:
1196      * </p>
1197      *
1198      * <pre>
1199      * ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
1200      * outputStream.writeBytes("hello world".getBytes(StandardCharsets.UTF_8));
1201      *
1202      * InputStream inputStream = IOUtils.copy(outputStream);
1203      * </pre>
1204      *
1205      * @param outputStream the {@link java.io.ByteArrayOutputStream} to read.
1206      * @return the {@link QueueInputStream} filled with the content of the outputStream.
1207      * @throws NullPointerException if the {@link java.io.ByteArrayOutputStream} is {@code null}.
1208      * @throws IOException if an I/O error occurs.
1209      * @since 2.12
1210      */
1211     @SuppressWarnings("resource") // streams are closed by the caller.
1212     public static QueueInputStream copy(final java.io.ByteArrayOutputStream outputStream) throws IOException {
1213         Objects.requireNonNull(outputStream, "outputStream");
1214         final QueueInputStream in = new QueueInputStream();
1215         outputStream.writeTo(in.newQueueOutputStream());
1216         return in;
1217     }
1218 
1219     /**
1220      * Copies chars from a {@link Reader} to a {@link Appendable}.
1221      * <p>
1222      * This method buffers the input internally, so there is no need to use a
1223      * {@link BufferedReader}.
1224      * </p>
1225      * <p>
1226      * Large streams (over 2GB) will return a chars copied value of
1227      * {@code -1} after the copy has completed since the correct
1228      * number of chars cannot be returned as an int. For large streams
1229      * use the {@link #copyLarge(Reader, Writer)} method.
1230      * </p>
1231      *
1232      * @param reader the {@link Reader} to read
1233      * @param output the {@link Appendable} to write to
1234      * @return the number of characters copied, or -1 if &gt; Integer.MAX_VALUE
1235      * @throws NullPointerException if the input or output is null
1236      * @throws IOException          if an I/O error occurs
1237      * @since 2.7
1238      */
1239     public static long copy(final Reader reader, final Appendable output) throws IOException {
1240         return copy(reader, output, CharBuffer.allocate(DEFAULT_BUFFER_SIZE));
1241     }
1242 
1243     /**
1244      * Copies chars from a {@link Reader} to an {@link Appendable}.
1245      * <p>
1246      * This method uses the provided buffer, so there is no need to use a
1247      * {@link BufferedReader}.
1248      * </p>
1249      *
1250      * @param reader the {@link Reader} to read
1251      * @param output the {@link Appendable} to write to
1252      * @param buffer the buffer to be used for the copy
1253      * @return the number of characters copied
1254      * @throws NullPointerException if the input or output is null
1255      * @throws IOException          if an I/O error occurs
1256      * @since 2.7
1257      */
1258     public static long copy(final Reader reader, final Appendable output, final CharBuffer buffer) throws IOException {
1259         long count = 0;
1260         int n;
1261         while (EOF != (n = reader.read(buffer))) {
1262             buffer.flip();
1263             output.append(buffer, 0, n);
1264             count += n;
1265         }
1266         return count;
1267     }
1268 
1269     /**
1270      * Copies chars from a {@link Reader} to bytes on an
1271      * {@link OutputStream} using the default character encoding of the
1272      * platform, and calling flush.
1273      * <p>
1274      * This method buffers the input internally, so there is no need to use a
1275      * {@link BufferedReader}.
1276      * </p>
1277      * <p>
1278      * Due to the implementation of OutputStreamWriter, this method performs a
1279      * flush.
1280      * </p>
1281      * <p>
1282      * This method uses {@link OutputStreamWriter}.
1283      * </p>
1284      *
1285      * @param reader the {@link Reader} to read
1286      * @param output the {@link OutputStream} to write to
1287      * @throws NullPointerException if the input or output is null
1288      * @throws IOException          if an I/O error occurs
1289      * @since 1.1
1290      * @deprecated 2.5 use {@link #copy(Reader, OutputStream, Charset)} instead
1291      */
1292     @Deprecated
1293     public static void copy(final Reader reader, final OutputStream output)
1294             throws IOException {
1295         copy(reader, output, Charset.defaultCharset());
1296     }
1297 
1298     /**
1299      * Copies chars from a {@link Reader} to bytes on an
1300      * {@link OutputStream} using the specified character encoding, and
1301      * calling flush.
1302      * <p>
1303      * This method buffers the input internally, so there is no need to use a
1304      * {@link BufferedReader}.
1305      * </p>
1306      * <p>
1307      * Due to the implementation of OutputStreamWriter, this method performs a
1308      * flush.
1309      * </p>
1310      * <p>
1311      * This method uses {@link OutputStreamWriter}.
1312      * </p>
1313      *
1314      * @param reader the {@link Reader} to read
1315      * @param output the {@link OutputStream} to write to
1316      * @param outputCharset the charset to use for the OutputStream, null means platform default
1317      * @throws NullPointerException if the input or output is null
1318      * @throws IOException          if an I/O error occurs
1319      * @since 2.3
1320      */
1321     public static void copy(final Reader reader, final OutputStream output, final Charset outputCharset)
1322             throws IOException {
1323         final OutputStreamWriter writer = new OutputStreamWriter(output, Charsets.toCharset(outputCharset));
1324         copy(reader, writer);
1325         // XXX Unless anyone is planning on rewriting OutputStreamWriter,
1326         // we have to flush here.
1327         writer.flush();
1328     }
1329 
1330     /**
1331      * Copies chars from a {@link Reader} to bytes on an
1332      * {@link OutputStream} using the specified character encoding, and
1333      * calling flush.
1334      * <p>
1335      * This method buffers the input internally, so there is no need to use a
1336      * {@link BufferedReader}.
1337      * </p>
1338      * <p>
1339      * Character encoding names can be found at
1340      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
1341      * </p>
1342      * <p>
1343      * Due to the implementation of OutputStreamWriter, this method performs a
1344      * flush.
1345      * </p>
1346      * <p>
1347      * This method uses {@link OutputStreamWriter}.
1348      * </p>
1349      *
1350      * @param reader the {@link Reader} to read
1351      * @param output the {@link OutputStream} to write to
1352      * @param outputCharsetName the name of the requested charset for the OutputStream, null means platform default
1353      * @throws NullPointerException                         if the input or output is null
1354      * @throws IOException                                  if an I/O error occurs
1355      * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io
1356      *                                                      .UnsupportedEncodingException} in version 2.2 if the
1357      *                                                      encoding is not supported.
1358      * @since 1.1
1359      */
1360     public static void copy(final Reader reader, final OutputStream output, final String outputCharsetName)
1361             throws IOException {
1362         copy(reader, output, Charsets.toCharset(outputCharsetName));
1363     }
1364 
1365     /**
1366      * Copies chars from a {@link Reader} to a {@link Writer}.
1367      * <p>
1368      * This method buffers the input internally, so there is no need to use a
1369      * {@link BufferedReader}.
1370      * </p>
1371      * <p>
1372      * Large streams (over 2GB) will return a chars copied value of
1373      * {@code -1} after the copy has completed since the correct
1374      * number of chars cannot be returned as an int. For large streams
1375      * use the {@link #copyLarge(Reader, Writer)} method.
1376      * </p>
1377      *
1378      * @param reader the {@link Reader} to read.
1379      * @param writer the {@link Writer} to write.
1380      * @return the number of characters copied, or -1 if &gt; Integer.MAX_VALUE
1381      * @throws NullPointerException if the input or output is null
1382      * @throws IOException          if an I/O error occurs
1383      * @since 1.1
1384      */
1385     public static int copy(final Reader reader, final Writer writer) throws IOException {
1386         final long count = copyLarge(reader, writer);
1387         if (count > Integer.MAX_VALUE) {
1388             return EOF;
1389         }
1390         return (int) count;
1391     }
1392 
1393     /**
1394      * Copies bytes from a {@link URL} to an {@link OutputStream}.
1395      * <p>
1396      * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
1397      * </p>
1398      * <p>
1399      * The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}.
1400      * </p>
1401      *
1402      * @param url the {@link URL} to read.
1403      * @param file the {@link OutputStream} to write.
1404      * @return the number of bytes copied.
1405      * @throws NullPointerException if the URL is {@code null}.
1406      * @throws NullPointerException if the OutputStream is {@code null}.
1407      * @throws IOException if an I/O error occurs.
1408      * @since 2.9.0
1409      */
1410     public static long copy(final URL url, final File file) throws IOException {
1411         try (OutputStream outputStream = Files.newOutputStream(Objects.requireNonNull(file, "file").toPath())) {
1412             return copy(url, outputStream);
1413         }
1414     }
1415 
1416     /**
1417      * Copies bytes from a {@link URL} to an {@link OutputStream}.
1418      * <p>
1419      * This method buffers the input internally, so there is no need to use a {@link BufferedInputStream}.
1420      * </p>
1421      * <p>
1422      * The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}.
1423      * </p>
1424      *
1425      * @param url the {@link URL} to read.
1426      * @param outputStream the {@link OutputStream} to write.
1427      * @return the number of bytes copied.
1428      * @throws NullPointerException if the URL is {@code null}.
1429      * @throws NullPointerException if the OutputStream is {@code null}.
1430      * @throws IOException if an I/O error occurs.
1431      * @since 2.9.0
1432      */
1433     public static long copy(final URL url, final OutputStream outputStream) throws IOException {
1434         try (InputStream inputStream = Objects.requireNonNull(url, "url").openStream()) {
1435             return copyLarge(inputStream, outputStream);
1436         }
1437     }
1438 
1439     /**
1440      * Copies bytes from a large (over 2GB) {@link InputStream} to an
1441      * {@link OutputStream}.
1442      * <p>
1443      * This method buffers the input internally, so there is no need to use a
1444      * {@link BufferedInputStream}.
1445      * </p>
1446      * <p>
1447      * The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}.
1448      * </p>
1449      *
1450      * @param inputStream the {@link InputStream} to read.
1451      * @param outputStream the {@link OutputStream} to write.
1452      * @return the number of bytes copied.
1453      * @throws NullPointerException if the InputStream is {@code null}.
1454      * @throws NullPointerException if the OutputStream is {@code null}.
1455      * @throws IOException if an I/O error occurs.
1456      * @since 1.3
1457      */
1458     public static long copyLarge(final InputStream inputStream, final OutputStream outputStream)
1459             throws IOException {
1460         return copy(inputStream, outputStream, DEFAULT_BUFFER_SIZE);
1461     }
1462 
1463     /**
1464      * Copies bytes from a large (over 2GB) {@link InputStream} to an
1465      * {@link OutputStream}.
1466      * <p>
1467      * This method uses the provided buffer, so there is no need to use a
1468      * {@link BufferedInputStream}.
1469      * </p>
1470      *
1471      * @param inputStream the {@link InputStream} to read.
1472      * @param outputStream the {@link OutputStream} to write.
1473      * @param buffer the buffer to use for the copy
1474      * @return the number of bytes copied.
1475      * @throws NullPointerException if the InputStream is {@code null}.
1476      * @throws NullPointerException if the OutputStream is {@code null}.
1477      * @throws IOException if an I/O error occurs.
1478      * @since 2.2
1479      */
1480     @SuppressWarnings("resource") // streams are closed by the caller.
1481     public static long copyLarge(final InputStream inputStream, final OutputStream outputStream, final byte[] buffer)
1482         throws IOException {
1483         Objects.requireNonNull(inputStream, "inputStream");
1484         Objects.requireNonNull(outputStream, "outputStream");
1485         long count = 0;
1486         int n;
1487         while (EOF != (n = inputStream.read(buffer))) {
1488             outputStream.write(buffer, 0, n);
1489             count += n;
1490         }
1491         return count;
1492     }
1493 
1494     /**
1495      * Copies some or all bytes from a large (over 2GB) {@link InputStream} to an
1496      * {@link OutputStream}, optionally skipping input bytes.
1497      * <p>
1498      * This method buffers the input internally, so there is no need to use a
1499      * {@link BufferedInputStream}.
1500      * </p>
1501      * <p>
1502      * Note that the implementation uses {@link #skip(InputStream, long)}.
1503      * This means that the method may be considerably less efficient than using the actual skip implementation,
1504      * this is done to guarantee that the correct number of characters are skipped.
1505      * </p>
1506      * The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}.
1507      *
1508      * @param input the {@link InputStream} to read
1509      * @param output the {@link OutputStream} to write to
1510      * @param inputOffset : number of bytes to skip from input before copying
1511      * -ve values are ignored
1512      * @param length : number of bytes to copy. -ve means all
1513      * @return the number of bytes copied
1514      * @throws NullPointerException if the input or output is null
1515      * @throws IOException          if an I/O error occurs
1516      * @since 2.2
1517      */
1518     public static long copyLarge(final InputStream input, final OutputStream output, final long inputOffset,
1519                                  final long length) throws IOException {
1520         return copyLarge(input, output, inputOffset, length, getScratchByteArray());
1521     }
1522 
1523     /**
1524      * Copies some or all bytes from a large (over 2GB) {@link InputStream} to an
1525      * {@link OutputStream}, optionally skipping input bytes.
1526      * <p>
1527      * This method uses the provided buffer, so there is no need to use a
1528      * {@link BufferedInputStream}.
1529      * </p>
1530      * <p>
1531      * Note that the implementation uses {@link #skip(InputStream, long)}.
1532      * This means that the method may be considerably less efficient than using the actual skip implementation,
1533      * this is done to guarantee that the correct number of characters are skipped.
1534      * </p>
1535      *
1536      * @param input the {@link InputStream} to read
1537      * @param output the {@link OutputStream} to write to
1538      * @param inputOffset : number of bytes to skip from input before copying
1539      * -ve values are ignored
1540      * @param length : number of bytes to copy. -ve means all
1541      * @param buffer the buffer to use for the copy
1542      * @return the number of bytes copied
1543      * @throws NullPointerException if the input or output is null
1544      * @throws IOException          if an I/O error occurs
1545      * @since 2.2
1546      */
1547     public static long copyLarge(final InputStream input, final OutputStream output,
1548                                  final long inputOffset, final long length, final byte[] buffer) throws IOException {
1549         if (inputOffset > 0) {
1550             skipFully(input, inputOffset);
1551         }
1552         if (length == 0) {
1553             return 0;
1554         }
1555         final int bufferLength = buffer.length;
1556         int bytesToRead = bufferLength;
1557         if (length > 0 && length < bufferLength) {
1558             bytesToRead = (int) length;
1559         }
1560         int read;
1561         long totalRead = 0;
1562         while (bytesToRead > 0 && EOF != (read = input.read(buffer, 0, bytesToRead))) {
1563             output.write(buffer, 0, read);
1564             totalRead += read;
1565             if (length > 0) { // only adjust length if not reading to the end
1566                 // Note the cast must work because buffer.length is an integer
1567                 bytesToRead = (int) Math.min(length - totalRead, bufferLength);
1568             }
1569         }
1570         return totalRead;
1571     }
1572 
1573     /**
1574      * Copies chars from a large (over 2GB) {@link Reader} to a {@link Writer}.
1575      * <p>
1576      * This method buffers the input internally, so there is no need to use a
1577      * {@link BufferedReader}.
1578      * </p>
1579      * <p>
1580      * The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}.
1581      * </p>
1582      *
1583      * @param reader the {@link Reader} to source.
1584      * @param writer the {@link Writer} to target.
1585      * @return the number of characters copied
1586      * @throws NullPointerException if the input or output is null
1587      * @throws IOException          if an I/O error occurs
1588      * @since 1.3
1589      */
1590     public static long copyLarge(final Reader reader, final Writer writer) throws IOException {
1591         return copyLarge(reader, writer, getScratchCharArray());
1592     }
1593 
1594     /**
1595      * Copies chars from a large (over 2GB) {@link Reader} to a {@link Writer}.
1596      * <p>
1597      * This method uses the provided buffer, so there is no need to use a
1598      * {@link BufferedReader}.
1599      * </p>
1600      *
1601      * @param reader the {@link Reader} to source.
1602      * @param writer the {@link Writer} to target.
1603      * @param buffer the buffer to be used for the copy
1604      * @return the number of characters copied
1605      * @throws NullPointerException if the input or output is null
1606      * @throws IOException          if an I/O error occurs
1607      * @since 2.2
1608      */
1609     public static long copyLarge(final Reader reader, final Writer writer, final char[] buffer) throws IOException {
1610         long count = 0;
1611         int n;
1612         while (EOF != (n = reader.read(buffer))) {
1613             writer.write(buffer, 0, n);
1614             count += n;
1615         }
1616         return count;
1617     }
1618 
1619     /**
1620      * Copies some or all chars from a large (over 2GB) {@link InputStream} to an
1621      * {@link OutputStream}, optionally skipping input chars.
1622      * <p>
1623      * This method buffers the input internally, so there is no need to use a
1624      * {@link BufferedReader}.
1625      * </p>
1626      * <p>
1627      * The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}.
1628      * </p>
1629      *
1630      * @param reader the {@link Reader} to read
1631      * @param writer the {@link Writer} to write to
1632      * @param inputOffset : number of chars to skip from input before copying
1633      * -ve values are ignored
1634      * @param length : number of chars to copy. -ve means all
1635      * @return the number of chars copied
1636      * @throws NullPointerException if the input or output is null
1637      * @throws IOException          if an I/O error occurs
1638      * @since 2.2
1639      */
1640     public static long copyLarge(final Reader reader, final Writer writer, final long inputOffset, final long length)
1641             throws IOException {
1642         return copyLarge(reader, writer, inputOffset, length, getScratchCharArray());
1643     }
1644 
1645     /**
1646      * Copies some or all chars from a large (over 2GB) {@link InputStream} to an
1647      * {@link OutputStream}, optionally skipping input chars.
1648      * <p>
1649      * This method uses the provided buffer, so there is no need to use a
1650      * {@link BufferedReader}.
1651      * </p>
1652      *
1653      * @param reader the {@link Reader} to read
1654      * @param writer the {@link Writer} to write to
1655      * @param inputOffset : number of chars to skip from input before copying
1656      * -ve values are ignored
1657      * @param length : number of chars to copy. -ve means all
1658      * @param buffer the buffer to be used for the copy
1659      * @return the number of chars copied
1660      * @throws NullPointerException if the input or output is null
1661      * @throws IOException          if an I/O error occurs
1662      * @since 2.2
1663      */
1664     public static long copyLarge(final Reader reader, final Writer writer, final long inputOffset, final long length,
1665                                  final char[] buffer)
1666             throws IOException {
1667         if (inputOffset > 0) {
1668             skipFully(reader, inputOffset);
1669         }
1670         if (length == 0) {
1671             return 0;
1672         }
1673         int bytesToRead = buffer.length;
1674         if (length > 0 && length < buffer.length) {
1675             bytesToRead = (int) length;
1676         }
1677         int read;
1678         long totalRead = 0;
1679         while (bytesToRead > 0 && EOF != (read = reader.read(buffer, 0, bytesToRead))) {
1680             writer.write(buffer, 0, read);
1681             totalRead += read;
1682             if (length > 0) { // only adjust length if not reading to the end
1683                 // Note the cast must work because buffer.length is an integer
1684                 bytesToRead = (int) Math.min(length - totalRead, buffer.length);
1685             }
1686         }
1687         return totalRead;
1688     }
1689 
1690     /**
1691      * Fills the given array with 0s.
1692      *
1693      * @param arr The array to fill.
1694      * @return The given array.
1695      */
1696     private static byte[] fill0(final byte[] arr) {
1697         Arrays.fill(arr, (byte) 0);
1698         return arr;
1699     }
1700 
1701     /**
1702      * Fills the given array with 0s.
1703      *
1704      * @param arr The array to fill.
1705      * @return The given array.
1706      */
1707     private static char[] fill0(final char[] arr) {
1708         Arrays.fill(arr, (char) 0);
1709         return arr;
1710     }
1711 
1712     /**
1713      * Gets the internal byte array buffer, intended for both reading and writing.
1714      *
1715      * @return the internal byte array buffer, intended for both reading and writing.
1716      */
1717     static byte[] getScratchByteArray() {
1718         return fill0(SCRATCH_BYTE_BUFFER_RW.get());
1719     }
1720 
1721     /**
1722      * Gets the internal byte array intended for write only operations.
1723      *
1724      * @return the internal byte array intended for write only operations.
1725      */
1726     static byte[] getScratchByteArrayWriteOnly() {
1727         return fill0(SCRATCH_BYTE_BUFFER_WO);
1728     }
1729 
1730     /**
1731      * Gets the char byte array buffer, intended for both reading and writing.
1732      *
1733      * @return the char byte array buffer, intended for both reading and writing.
1734      */
1735     static char[] getScratchCharArray() {
1736         return fill0(SCRATCH_CHAR_BUFFER_RW.get());
1737     }
1738 
1739     /**
1740      * Gets the internal char array intended for write only operations.
1741      *
1742      * @return the internal char array intended for write only operations.
1743      */
1744     static char[] getScratchCharArrayWriteOnly() {
1745         return fill0(SCRATCH_CHAR_BUFFER_WO);
1746     }
1747 
1748     /**
1749      * Returns the length of the given array in a null-safe manner.
1750      *
1751      * @param array an array or null
1752      * @return the array length -- or 0 if the given array is null.
1753      * @since 2.7
1754      */
1755     public static int length(final byte[] array) {
1756         return array == null ? 0 : array.length;
1757     }
1758 
1759     /**
1760      * Returns the length of the given array in a null-safe manner.
1761      *
1762      * @param array an array or null
1763      * @return the array length -- or 0 if the given array is null.
1764      * @since 2.7
1765      */
1766     public static int length(final char[] array) {
1767         return array == null ? 0 : array.length;
1768     }
1769 
1770     /**
1771      * Returns the length of the given CharSequence in a null-safe manner.
1772      *
1773      * @param csq a CharSequence or null
1774      * @return the CharSequence length -- or 0 if the given CharSequence is null.
1775      * @since 2.7
1776      */
1777     public static int length(final CharSequence csq) {
1778         return csq == null ? 0 : csq.length();
1779     }
1780 
1781     /**
1782      * Returns the length of the given array in a null-safe manner.
1783      *
1784      * @param array an array or null
1785      * @return the array length -- or 0 if the given array is null.
1786      * @since 2.7
1787      */
1788     public static int length(final Object[] array) {
1789         return array == null ? 0 : array.length;
1790     }
1791 
1792     /**
1793      * Returns an Iterator for the lines in an {@link InputStream}, using
1794      * the character encoding specified (or default encoding if null).
1795      * <p>
1796      * {@link LineIterator} holds a reference to the open
1797      * {@link InputStream} specified here. When you have finished with
1798      * the iterator you should close the stream to free internal resources.
1799      * This can be done by using a try-with-resources block, closing the stream directly, or by calling
1800      * {@link LineIterator#close()}.
1801      * </p>
1802      * <p>
1803      * The recommended usage pattern is:
1804      * </p>
1805      * <pre>
1806      * try {
1807      *   LineIterator it = IOUtils.lineIterator(stream, charset);
1808      *   while (it.hasNext()) {
1809      *     String line = it.nextLine();
1810      *     /// do something with line
1811      *   }
1812      * } finally {
1813      *   IOUtils.closeQuietly(stream);
1814      * }
1815      * </pre>
1816      *
1817      * @param input the {@link InputStream} to read, not null
1818      * @param charset the charset to use, null means platform default
1819      * @return an Iterator of the lines in the reader, never null
1820      * @throws IllegalArgumentException if the input is null
1821      * @since 2.3
1822      */
1823     public static LineIterator lineIterator(final InputStream input, final Charset charset) {
1824         return new LineIterator(new InputStreamReader(input, Charsets.toCharset(charset)));
1825     }
1826 
1827     /**
1828      * Returns an Iterator for the lines in an {@link InputStream}, using
1829      * the character encoding specified (or default encoding if null).
1830      * <p>
1831      * {@link LineIterator} holds a reference to the open
1832      * {@link InputStream} specified here. When you have finished with
1833      * the iterator you should close the stream to free internal resources.
1834      * This can be done by using a try-with-resources block, closing the stream directly, or by calling
1835      * {@link LineIterator#close()}.
1836      * </p>
1837      * <p>
1838      * The recommended usage pattern is:
1839      * </p>
1840      * <pre>
1841      * try {
1842      *   LineIterator it = IOUtils.lineIterator(stream, StandardCharsets.UTF_8.name());
1843      *   while (it.hasNext()) {
1844      *     String line = it.nextLine();
1845      *     /// do something with line
1846      *   }
1847      * } finally {
1848      *   IOUtils.closeQuietly(stream);
1849      * }
1850      * </pre>
1851      *
1852      * @param input the {@link InputStream} to read, not null
1853      * @param charsetName the encoding to use, null means platform default
1854      * @return an Iterator of the lines in the reader, never null
1855      * @throws IllegalArgumentException                     if the input is null
1856      * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io
1857      *                                                      .UnsupportedEncodingException} in version 2.2 if the
1858      *                                                      encoding is not supported.
1859      * @since 1.2
1860      */
1861     public static LineIterator lineIterator(final InputStream input, final String charsetName) {
1862         return lineIterator(input, Charsets.toCharset(charsetName));
1863     }
1864 
1865     /**
1866      * Returns an Iterator for the lines in a {@link Reader}.
1867      * <p>
1868      * {@link LineIterator} holds a reference to the open
1869      * {@link Reader} specified here. When you have finished with the
1870      * iterator you should close the reader to free internal resources.
1871      * This can be done by using a try-with-resources block, closing the reader directly, or by calling
1872      * {@link LineIterator#close()}.
1873      * </p>
1874      * <p>
1875      * The recommended usage pattern is:
1876      * </p>
1877      * <pre>
1878      * try {
1879      *   LineIterator it = IOUtils.lineIterator(reader);
1880      *   while (it.hasNext()) {
1881      *     String line = it.nextLine();
1882      *     /// do something with line
1883      *   }
1884      * } finally {
1885      *   IOUtils.closeQuietly(reader);
1886      * }
1887      * </pre>
1888      *
1889      * @param reader the {@link Reader} to read, not null
1890      * @return an Iterator of the lines in the reader, never null
1891      * @throws NullPointerException if the reader is null
1892      * @since 1.2
1893      */
1894     public static LineIterator lineIterator(final Reader reader) {
1895         return new LineIterator(reader);
1896     }
1897 
1898     /**
1899      * Reads bytes from an input stream.
1900      * This implementation guarantees that it will read as many bytes
1901      * as possible before giving up; this may not always be the case for
1902      * subclasses of {@link InputStream}.
1903      *
1904      * @param input where to read input from
1905      * @param buffer destination
1906      * @return actual length read; may be less than requested if EOF was reached
1907      * @throws IOException if a read error occurs
1908      * @since 2.2
1909      */
1910     public static int read(final InputStream input, final byte[] buffer) throws IOException {
1911         return read(input, buffer, 0, buffer.length);
1912     }
1913 
1914     /**
1915      * Reads bytes from an input stream.
1916      * This implementation guarantees that it will read as many bytes
1917      * as possible before giving up; this may not always be the case for
1918      * subclasses of {@link InputStream}.
1919      *
1920      * @param input where to read input
1921      * @param buffer destination
1922      * @param offset initial offset into buffer
1923      * @param length length to read, must be &gt;= 0
1924      * @return actual length read; may be less than requested if EOF was reached
1925      * @throws IllegalArgumentException if length is negative
1926      * @throws IOException              if a read error occurs
1927      * @since 2.2
1928      */
1929     public static int read(final InputStream input, final byte[] buffer, final int offset, final int length)
1930             throws IOException {
1931         if (length == 0) {
1932             return 0;
1933         }
1934         return read(input::read, buffer, offset, length);
1935     }
1936 
1937     /**
1938      * Reads bytes from an input. This implementation guarantees that it will read as many bytes as possible before giving up; this may not always be the case
1939      * for subclasses of {@link InputStream}.
1940      *
1941      * @param input  How to read input
1942      * @param buffer destination
1943      * @param offset initial offset into buffer
1944      * @param length length to read, must be &gt;= 0
1945      * @return actual length read; may be less than requested if EOF was reached
1946      * @throws IllegalArgumentException if length is negative
1947      * @throws IOException              if a read error occurs
1948      * @since 2.2
1949      */
1950     static int read(final IOTriFunction<byte[], Integer, Integer, Integer> input, final byte[] buffer, final int offset, final int length)
1951             throws IOException {
1952         if (length < 0) {
1953             throw new IllegalArgumentException("Length must not be negative: " + length);
1954         }
1955         int remaining = length;
1956         while (remaining > 0) {
1957             final int location = length - remaining;
1958             final int count = input.apply(buffer, offset + location, remaining);
1959             if (EOF == count) {
1960                 break;
1961             }
1962             remaining -= count;
1963         }
1964         return length - remaining;
1965     }
1966 
1967     /**
1968      * Reads bytes from a ReadableByteChannel.
1969      * <p>
1970      * This implementation guarantees that it will read as many bytes
1971      * as possible before giving up; this may not always be the case for
1972      * subclasses of {@link ReadableByteChannel}.
1973      * </p>
1974      *
1975      * @param input the byte channel to read
1976      * @param buffer byte buffer destination
1977      * @return the actual length read; may be less than requested if EOF was reached
1978      * @throws IOException if a read error occurs
1979      * @since 2.5
1980      */
1981     public static int read(final ReadableByteChannel input, final ByteBuffer buffer) throws IOException {
1982         final int length = buffer.remaining();
1983         while (buffer.remaining() > 0) {
1984             final int count = input.read(buffer);
1985             if (EOF == count) { // EOF
1986                 break;
1987             }
1988         }
1989         return length - buffer.remaining();
1990     }
1991 
1992     /**
1993      * Reads characters from an input character stream.
1994      * This implementation guarantees that it will read as many characters
1995      * as possible before giving up; this may not always be the case for
1996      * subclasses of {@link Reader}.
1997      *
1998      * @param reader where to read input from
1999      * @param buffer destination
2000      * @return actual length read; may be less than requested if EOF was reached
2001      * @throws IOException if a read error occurs
2002      * @since 2.2
2003      */
2004     public static int read(final Reader reader, final char[] buffer) throws IOException {
2005         return read(reader, buffer, 0, buffer.length);
2006     }
2007 
2008     /**
2009      * Reads characters from an input character stream.
2010      * This implementation guarantees that it will read as many characters
2011      * as possible before giving up; this may not always be the case for
2012      * subclasses of {@link Reader}.
2013      *
2014      * @param reader where to read input from
2015      * @param buffer destination
2016      * @param offset initial offset into buffer
2017      * @param length length to read, must be &gt;= 0
2018      * @return actual length read; may be less than requested if EOF was reached
2019      * @throws IllegalArgumentException if length is negative
2020      * @throws IOException              if a read error occurs
2021      * @since 2.2
2022      */
2023     public static int read(final Reader reader, final char[] buffer, final int offset, final int length)
2024             throws IOException {
2025         if (length < 0) {
2026             throw new IllegalArgumentException("Length must not be negative: " + length);
2027         }
2028         int remaining = length;
2029         while (remaining > 0) {
2030             final int location = length - remaining;
2031             final int count = reader.read(buffer, offset + location, remaining);
2032             if (EOF == count) { // EOF
2033                 break;
2034             }
2035             remaining -= count;
2036         }
2037         return length - remaining;
2038     }
2039 
2040     /**
2041      * Reads the requested number of bytes or fail if there are not enough left.
2042      * <p>
2043      * This allows for the possibility that {@link InputStream#read(byte[], int, int)} may
2044      * not read as many bytes as requested (most likely because of reaching EOF).
2045      * </p>
2046      *
2047      * @param input where to read input from
2048      * @param buffer destination
2049      *
2050      * @throws IOException              if there is a problem reading the file
2051      * @throws IllegalArgumentException if length is negative
2052      * @throws EOFException             if the number of bytes read was incorrect
2053      * @since 2.2
2054      */
2055     public static void readFully(final InputStream input, final byte[] buffer) throws IOException {
2056         readFully(input, buffer, 0, buffer.length);
2057     }
2058 
2059     /**
2060      * Reads the requested number of bytes or fail if there are not enough left.
2061      * <p>
2062      * This allows for the possibility that {@link InputStream#read(byte[], int, int)} may
2063      * not read as many bytes as requested (most likely because of reaching EOF).
2064      * </p>
2065      *
2066      * @param input where to read input from
2067      * @param buffer destination
2068      * @param offset initial offset into buffer
2069      * @param length length to read, must be &gt;= 0
2070      *
2071      * @throws IOException              if there is a problem reading the file
2072      * @throws IllegalArgumentException if length is negative
2073      * @throws EOFException             if the number of bytes read was incorrect
2074      * @since 2.2
2075      */
2076     public static void readFully(final InputStream input, final byte[] buffer, final int offset, final int length)
2077             throws IOException {
2078         final int actual = read(input, buffer, offset, length);
2079         if (actual != length) {
2080             throw new EOFException("Length to read: " + length + " actual: " + actual);
2081         }
2082     }
2083 
2084     /**
2085      * Reads the requested number of bytes or fail if there are not enough left.
2086      * <p>
2087      * This allows for the possibility that {@link InputStream#read(byte[], int, int)} may
2088      * not read as many bytes as requested (most likely because of reaching EOF).
2089      * </p>
2090      *
2091      * @param input where to read input from
2092      * @param length length to read, must be &gt;= 0
2093      * @return the bytes read from input
2094      * @throws IOException              if there is a problem reading the file
2095      * @throws IllegalArgumentException if length is negative
2096      * @throws EOFException             if the number of bytes read was incorrect
2097      * @since 2.5
2098      */
2099     public static byte[] readFully(final InputStream input, final int length) throws IOException {
2100         final byte[] buffer = byteArray(length);
2101         readFully(input, buffer, 0, buffer.length);
2102         return buffer;
2103     }
2104 
2105     /**
2106      * Reads the requested number of bytes or fail if there are not enough left.
2107      * <p>
2108      * This allows for the possibility that {@link ReadableByteChannel#read(ByteBuffer)} may
2109      * not read as many bytes as requested (most likely because of reaching EOF).
2110      * </p>
2111      *
2112      * @param input the byte channel to read
2113      * @param buffer byte buffer destination
2114      * @throws IOException  if there is a problem reading the file
2115      * @throws EOFException if the number of bytes read was incorrect
2116      * @since 2.5
2117      */
2118     public static void readFully(final ReadableByteChannel input, final ByteBuffer buffer) throws IOException {
2119         final int expected = buffer.remaining();
2120         final int actual = read(input, buffer);
2121         if (actual != expected) {
2122             throw new EOFException("Length to read: " + expected + " actual: " + actual);
2123         }
2124     }
2125 
2126     /**
2127      * Reads the requested number of characters or fail if there are not enough left.
2128      * <p>
2129      * This allows for the possibility that {@link Reader#read(char[], int, int)} may
2130      * not read as many characters as requested (most likely because of reaching EOF).
2131      * </p>
2132      *
2133      * @param reader where to read input from
2134      * @param buffer destination
2135      * @throws IOException              if there is a problem reading the file
2136      * @throws IllegalArgumentException if length is negative
2137      * @throws EOFException             if the number of characters read was incorrect
2138      * @since 2.2
2139      */
2140     public static void readFully(final Reader reader, final char[] buffer) throws IOException {
2141         readFully(reader, buffer, 0, buffer.length);
2142     }
2143 
2144     /**
2145      * Reads the requested number of characters or fail if there are not enough left.
2146      * <p>
2147      * This allows for the possibility that {@link Reader#read(char[], int, int)} may
2148      * not read as many characters as requested (most likely because of reaching EOF).
2149      * </p>
2150      *
2151      * @param reader where to read input from
2152      * @param buffer destination
2153      * @param offset initial offset into buffer
2154      * @param length length to read, must be &gt;= 0
2155      * @throws IOException              if there is a problem reading the file
2156      * @throws IllegalArgumentException if length is negative
2157      * @throws EOFException             if the number of characters read was incorrect
2158      * @since 2.2
2159      */
2160     public static void readFully(final Reader reader, final char[] buffer, final int offset, final int length)
2161             throws IOException {
2162         final int actual = read(reader, buffer, offset, length);
2163         if (actual != length) {
2164             throw new EOFException("Length to read: " + length + " actual: " + actual);
2165         }
2166     }
2167 
2168     /**
2169      * Gets the contents of an {@link InputStream} as a list of Strings,
2170      * one entry per line, using the default character encoding of the platform.
2171      * <p>
2172      * This method buffers the input internally, so there is no need to use a
2173      * {@link BufferedInputStream}.
2174      * </p>
2175      *
2176      * @param input the {@link InputStream} to read, not null
2177      * @return the list of Strings, never null
2178      * @throws NullPointerException if the input is null
2179      * @throws UncheckedIOException if an I/O error occurs
2180      * @since 1.1
2181      * @deprecated 2.5 use {@link #readLines(InputStream, Charset)} instead
2182      */
2183     @Deprecated
2184     public static List<String> readLines(final InputStream input) throws UncheckedIOException {
2185         return readLines(input, Charset.defaultCharset());
2186     }
2187 
2188     /**
2189      * Gets the contents of an {@link InputStream} as a list of Strings,
2190      * one entry per line, using the specified character encoding.
2191      * <p>
2192      * This method buffers the input internally, so there is no need to use a
2193      * {@link BufferedInputStream}.
2194      * </p>
2195      *
2196      * @param input the {@link InputStream} to read, not null
2197      * @param charset the charset to use, null means platform default
2198      * @return the list of Strings, never null
2199      * @throws NullPointerException if the input is null
2200      * @throws UncheckedIOException if an I/O error occurs
2201      * @since 2.3
2202      */
2203     public static List<String> readLines(final InputStream input, final Charset charset) throws UncheckedIOException {
2204         return readLines(new InputStreamReader(input, Charsets.toCharset(charset)));
2205     }
2206 
2207     /**
2208      * Gets the contents of an {@link InputStream} as a list of Strings,
2209      * one entry per line, using the specified character encoding.
2210      * <p>
2211      * Character encoding names can be found at
2212      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
2213      * </p>
2214      * <p>
2215      * This method buffers the input internally, so there is no need to use a
2216      * {@link BufferedInputStream}.
2217      * </p>
2218      *
2219      * @param input the {@link InputStream} to read, not null
2220      * @param charsetName the name of the requested charset, null means platform default
2221      * @return the list of Strings, never null
2222      * @throws NullPointerException                         if the input is null
2223      * @throws UncheckedIOException                         if an I/O error occurs
2224      * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io
2225      *                                                      .UnsupportedEncodingException} in version 2.2 if the
2226      *                                                      encoding is not supported.
2227      * @since 1.1
2228      */
2229     public static List<String> readLines(final InputStream input, final String charsetName) throws UncheckedIOException {
2230         return readLines(input, Charsets.toCharset(charsetName));
2231     }
2232 
2233     /**
2234      * Gets the contents of a {@link Reader} as a list of Strings,
2235      * one entry per line.
2236      * <p>
2237      * This method buffers the input internally, so there is no need to use a
2238      * {@link BufferedReader}.
2239      * </p>
2240      *
2241      * @param reader the {@link Reader} to read, not null
2242      * @return the list of Strings, never null
2243      * @throws NullPointerException if the input is null
2244      * @throws UncheckedIOException if an I/O error occurs
2245      * @since 1.1
2246      */
2247     @SuppressWarnings("resource") // reader wraps input and is the responsibility of the caller.
2248     public static List<String> readLines(final Reader reader) throws UncheckedIOException {
2249         return toBufferedReader(reader).lines().collect(Collectors.toList());
2250     }
2251 
2252     /**
2253      * Gets the contents of a resource as a byte array.
2254      * <p>
2255      * Delegates to {@link #resourceToByteArray(String, ClassLoader) resourceToByteArray(String, null)}.
2256      * </p>
2257      *
2258      * @param name The resource name.
2259      * @return the requested byte array
2260      * @throws IOException if an I/O error occurs or the resource is not found.
2261      * @see #resourceToByteArray(String, ClassLoader)
2262      * @since 2.6
2263      */
2264     public static byte[] resourceToByteArray(final String name) throws IOException {
2265         return resourceToByteArray(name, null);
2266     }
2267 
2268     /**
2269      * Gets the contents of a resource as a byte array.
2270      * <p>
2271      * Delegates to {@link #resourceToURL(String, ClassLoader)}.
2272      * </p>
2273      *
2274      * @param name The resource name.
2275      * @param classLoader the class loader that the resolution of the resource is delegated to
2276      * @return the requested byte array
2277      * @throws IOException if an I/O error occurs or the resource is not found.
2278      * @see #resourceToURL(String, ClassLoader)
2279      * @since 2.6
2280      */
2281     public static byte[] resourceToByteArray(final String name, final ClassLoader classLoader) throws IOException {
2282         return toByteArray(resourceToURL(name, classLoader));
2283     }
2284 
2285     /**
2286      * Gets the contents of a resource as a String using the specified character encoding.
2287      * <p>
2288      * Delegates to {@link #resourceToString(String, Charset, ClassLoader) resourceToString(String, Charset, null)}.
2289      * </p>
2290      *
2291      * @param name The resource name.
2292      * @param charset the charset to use, null means platform default
2293      * @return the requested String
2294      * @throws IOException if an I/O error occurs or the resource is not found.
2295      * @see #resourceToString(String, Charset, ClassLoader)
2296      * @since 2.6
2297      */
2298     public static String resourceToString(final String name, final Charset charset) throws IOException {
2299         return resourceToString(name, charset, null);
2300     }
2301 
2302     /**
2303      * Gets the contents of a resource as a String using the specified character encoding.
2304      * <p>
2305      * Delegates to {@link #resourceToURL(String, ClassLoader)}.
2306      * </p>
2307      *
2308      * @param name The resource name.
2309      * @param charset the Charset to use, null means platform default
2310      * @param classLoader the class loader that the resolution of the resource is delegated to
2311      * @return the requested String
2312      * @throws IOException if an I/O error occurs.
2313      * @see #resourceToURL(String, ClassLoader)
2314      * @since 2.6
2315      */
2316     public static String resourceToString(final String name, final Charset charset, final ClassLoader classLoader) throws IOException {
2317         return toString(resourceToURL(name, classLoader), charset);
2318     }
2319 
2320     /**
2321      * Gets a URL pointing to the given resource.
2322      * <p>
2323      * Delegates to {@link #resourceToURL(String, ClassLoader) resourceToURL(String, null)}.
2324      * </p>
2325      *
2326      * @param name The resource name.
2327      * @return A URL object for reading the resource.
2328      * @throws IOException if the resource is not found.
2329      * @since 2.6
2330      */
2331     public static URL resourceToURL(final String name) throws IOException {
2332         return resourceToURL(name, null);
2333     }
2334 
2335     /**
2336      * Gets a URL pointing to the given resource.
2337      * <p>
2338      * If the {@code classLoader} is not null, call {@link ClassLoader#getResource(String)}, otherwise call
2339      * {@link Class#getResource(String) IOUtils.class.getResource(name)}.
2340      * </p>
2341      *
2342      * @param name The resource name.
2343      * @param classLoader Delegate to this class loader if not null
2344      * @return A URL object for reading the resource.
2345      * @throws IOException if the resource is not found.
2346      * @since 2.6
2347      */
2348     public static URL resourceToURL(final String name, final ClassLoader classLoader) throws IOException {
2349         // What about the thread context class loader?
2350         // What about the system class loader?
2351         final URL resource = classLoader == null ? IOUtils.class.getResource(name) : classLoader.getResource(name);
2352         if (resource == null) {
2353             throw new IOException("Resource not found: " + name);
2354         }
2355         return resource;
2356     }
2357 
2358     /**
2359      * Skips bytes from an input byte stream.
2360      * This implementation guarantees that it will read as many bytes
2361      * as possible before giving up; this may not always be the case for
2362      * skip() implementations in subclasses of {@link InputStream}.
2363      * <p>
2364      * Note that the implementation uses {@link InputStream#read(byte[], int, int)} rather
2365      * than delegating to {@link InputStream#skip(long)}.
2366      * This means that the method may be considerably less efficient than using the actual skip implementation,
2367      * this is done to guarantee that the correct number of bytes are skipped.
2368      * </p>
2369      *
2370      * @param input byte stream to skip
2371      * @param toSkip number of bytes to skip.
2372      * @return number of bytes actually skipped.
2373      * @throws IOException              if there is a problem reading the file
2374      * @throws IllegalArgumentException if toSkip is negative
2375      * @see InputStream#skip(long)
2376      * @see <a href="https://issues.apache.org/jira/browse/IO-203">IO-203 - Add skipFully() method for InputStreams</a>
2377      * @since 2.0
2378      */
2379     public static long skip(final InputStream input, final long toSkip) throws IOException {
2380         return skip(input, toSkip, IOUtils::getScratchByteArrayWriteOnly);
2381     }
2382 
2383     /**
2384      * Skips bytes from an input byte stream.
2385      * <p>
2386      * Intended for special cases when customization of the temporary buffer is needed because, for example, a nested input stream has requirements for the
2387      * bytes read. For example, when using {@link InflaterInputStream}s from multiple threads.
2388      * </p>
2389      * <p>
2390      * This implementation guarantees that it will read as many bytes as possible before giving up; this may not always be the case for skip() implementations
2391      * in subclasses of {@link InputStream}.
2392      * </p>
2393      * <p>
2394      * Note that the implementation uses {@link InputStream#read(byte[], int, int)} rather than delegating to {@link InputStream#skip(long)}. This means that
2395      * the method may be considerably less efficient than using the actual skip implementation, this is done to guarantee that the correct number of bytes are
2396      * skipped.
2397      * </p>
2398      *
2399      * @param input              byte stream to skip
2400      * @param toSkip             number of bytes to skip.
2401      * @param skipBufferSupplier Supplies the buffer to use for reading.
2402      * @return number of bytes actually skipped.
2403      * @throws IOException              if there is a problem reading the file
2404      * @throws IllegalArgumentException if toSkip is negative
2405      * @see InputStream#skip(long)
2406      * @see <a href="https://issues.apache.org/jira/browse/IO-203">IO-203 - Add skipFully() method for InputStreams</a>
2407      * @since 2.14.0
2408      */
2409     public static long skip(final InputStream input, final long toSkip, final Supplier<byte[]> skipBufferSupplier) throws IOException {
2410         if (toSkip < 0) {
2411             throw new IllegalArgumentException("Skip count must be non-negative, actual: " + toSkip);
2412         }
2413         //
2414         // No need to synchronize access to SCRATCH_BYTE_BUFFER_WO: We don't care if the buffer is written multiple
2415         // times or in parallel since the data is ignored. We reuse the same buffer, if the buffer size were variable or read-write,
2416         // we would need to synch or use a thread local to ensure some other thread safety.
2417         //
2418         long remain = toSkip;
2419         while (remain > 0) {
2420             final byte[] skipBuffer = skipBufferSupplier.get();
2421             // See https://issues.apache.org/jira/browse/IO-203 for why we use read() rather than delegating to skip()
2422             final long n = input.read(skipBuffer, 0, (int) Math.min(remain, skipBuffer.length));
2423             if (n < 0) { // EOF
2424                 break;
2425             }
2426             remain -= n;
2427         }
2428         return toSkip - remain;
2429     }
2430 
2431     /**
2432      * Skips bytes from a ReadableByteChannel.
2433      * This implementation guarantees that it will read as many bytes
2434      * as possible before giving up.
2435      *
2436      * @param input ReadableByteChannel to skip
2437      * @param toSkip number of bytes to skip.
2438      * @return number of bytes actually skipped.
2439      * @throws IOException              if there is a problem reading the ReadableByteChannel
2440      * @throws IllegalArgumentException if toSkip is negative
2441      * @since 2.5
2442      */
2443     public static long skip(final ReadableByteChannel input, final long toSkip) throws IOException {
2444         if (toSkip < 0) {
2445             throw new IllegalArgumentException("Skip count must be non-negative, actual: " + toSkip);
2446         }
2447         final ByteBuffer skipByteBuffer = ByteBuffer.allocate((int) Math.min(toSkip, DEFAULT_BUFFER_SIZE));
2448         long remain = toSkip;
2449         while (remain > 0) {
2450             skipByteBuffer.position(0);
2451             skipByteBuffer.limit((int) Math.min(remain, DEFAULT_BUFFER_SIZE));
2452             final int n = input.read(skipByteBuffer);
2453             if (n == EOF) {
2454                 break;
2455             }
2456             remain -= n;
2457         }
2458         return toSkip - remain;
2459     }
2460 
2461     /**
2462      * Skips characters from an input character stream.
2463      * This implementation guarantees that it will read as many characters
2464      * as possible before giving up; this may not always be the case for
2465      * skip() implementations in subclasses of {@link Reader}.
2466      * <p>
2467      * Note that the implementation uses {@link Reader#read(char[], int, int)} rather
2468      * than delegating to {@link Reader#skip(long)}.
2469      * This means that the method may be considerably less efficient than using the actual skip implementation,
2470      * this is done to guarantee that the correct number of characters are skipped.
2471      * </p>
2472      *
2473      * @param reader character stream to skip
2474      * @param toSkip number of characters to skip.
2475      * @return number of characters actually skipped.
2476      * @throws IOException              if there is a problem reading the file
2477      * @throws IllegalArgumentException if toSkip is negative
2478      * @see Reader#skip(long)
2479      * @see <a href="https://issues.apache.org/jira/browse/IO-203">IO-203 - Add skipFully() method for InputStreams</a>
2480      * @since 2.0
2481      */
2482     public static long skip(final Reader reader, final long toSkip) throws IOException {
2483         if (toSkip < 0) {
2484             throw new IllegalArgumentException("Skip count must be non-negative, actual: " + toSkip);
2485         }
2486         long remain = toSkip;
2487         while (remain > 0) {
2488             // See https://issues.apache.org/jira/browse/IO-203 for why we use read() rather than delegating to skip()
2489             final char[] charArray = getScratchCharArrayWriteOnly();
2490             final long n = reader.read(charArray, 0, (int) Math.min(remain, charArray.length));
2491             if (n < 0) { // EOF
2492                 break;
2493             }
2494             remain -= n;
2495         }
2496         return toSkip - remain;
2497     }
2498 
2499     /**
2500      * Skips the requested number of bytes or fail if there are not enough left.
2501      * <p>
2502      * This allows for the possibility that {@link InputStream#skip(long)} may
2503      * not skip as many bytes as requested (most likely because of reaching EOF).
2504      * </p>
2505      * <p>
2506      * Note that the implementation uses {@link #skip(InputStream, long)}.
2507      * This means that the method may be considerably less efficient than using the actual skip implementation,
2508      * this is done to guarantee that the correct number of characters are skipped.
2509      * </p>
2510      *
2511      * @param input stream to skip
2512      * @param toSkip the number of bytes to skip
2513      * @throws IOException              if there is a problem reading the file
2514      * @throws IllegalArgumentException if toSkip is negative
2515      * @throws EOFException             if the number of bytes skipped was incorrect
2516      * @see InputStream#skip(long)
2517      * @since 2.0
2518      */
2519     public static void skipFully(final InputStream input, final long toSkip) throws IOException {
2520         final long skipped = skip(input, toSkip, IOUtils::getScratchByteArrayWriteOnly);
2521         if (skipped != toSkip) {
2522             throw new EOFException("Bytes to skip: " + toSkip + " actual: " + skipped);
2523         }
2524     }
2525 
2526     /**
2527      * Skips the requested number of bytes or fail if there are not enough left.
2528      * <p>
2529      * Intended for special cases when customization of the temporary buffer is needed because, for example, a nested input stream has requirements for the
2530      * bytes read. For example, when using {@link InflaterInputStream}s from multiple threads.
2531      * </p>
2532      * <p>
2533      * This allows for the possibility that {@link InputStream#skip(long)} may not skip as many bytes as requested (most likely because of reaching EOF).
2534      * </p>
2535      * <p>
2536      * Note that the implementation uses {@link #skip(InputStream, long)}. This means that the method may be considerably less efficient than using the actual
2537      * skip implementation, this is done to guarantee that the correct number of characters are skipped.
2538      * </p>
2539      *
2540      * @param input              stream to skip
2541      * @param toSkip             the number of bytes to skip
2542      * @param skipBufferSupplier Supplies the buffer to use for reading.
2543      * @throws IOException              if there is a problem reading the file
2544      * @throws IllegalArgumentException if toSkip is negative
2545      * @throws EOFException             if the number of bytes skipped was incorrect
2546      * @see InputStream#skip(long)
2547      * @since 2.14.0
2548      */
2549     public static void skipFully(final InputStream input, final long toSkip, final Supplier<byte[]> skipBufferSupplier) throws IOException {
2550         if (toSkip < 0) {
2551             throw new IllegalArgumentException("Bytes to skip must not be negative: " + toSkip);
2552         }
2553         final long skipped = skip(input, toSkip, skipBufferSupplier);
2554         if (skipped != toSkip) {
2555             throw new EOFException("Bytes to skip: " + toSkip + " actual: " + skipped);
2556         }
2557     }
2558 
2559     /**
2560      * Skips the requested number of bytes or fail if there are not enough left.
2561      *
2562      * @param input ReadableByteChannel to skip
2563      * @param toSkip the number of bytes to skip
2564      * @throws IOException              if there is a problem reading the ReadableByteChannel
2565      * @throws IllegalArgumentException if toSkip is negative
2566      * @throws EOFException             if the number of bytes skipped was incorrect
2567      * @since 2.5
2568      */
2569     public static void skipFully(final ReadableByteChannel input, final long toSkip) throws IOException {
2570         if (toSkip < 0) {
2571             throw new IllegalArgumentException("Bytes to skip must not be negative: " + toSkip);
2572         }
2573         final long skipped = skip(input, toSkip);
2574         if (skipped != toSkip) {
2575             throw new EOFException("Bytes to skip: " + toSkip + " actual: " + skipped);
2576         }
2577     }
2578 
2579     /**
2580      * Skips the requested number of characters or fail if there are not enough left.
2581      * <p>
2582      * This allows for the possibility that {@link Reader#skip(long)} may
2583      * not skip as many characters as requested (most likely because of reaching EOF).
2584      * </p>
2585      * <p>
2586      * Note that the implementation uses {@link #skip(Reader, long)}.
2587      * This means that the method may be considerably less efficient than using the actual skip implementation,
2588      * this is done to guarantee that the correct number of characters are skipped.
2589      * </p>
2590      *
2591      * @param reader stream to skip
2592      * @param toSkip the number of characters to skip
2593      * @throws IOException              if there is a problem reading the file
2594      * @throws IllegalArgumentException if toSkip is negative
2595      * @throws EOFException             if the number of characters skipped was incorrect
2596      * @see Reader#skip(long)
2597      * @since 2.0
2598      */
2599     public static void skipFully(final Reader reader, final long toSkip) throws IOException {
2600         final long skipped = skip(reader, toSkip);
2601         if (skipped != toSkip) {
2602             throw new EOFException("Chars to skip: " + toSkip + " actual: " + skipped);
2603         }
2604     }
2605 
2606     /**
2607      * Fetches entire contents of an {@link InputStream} and represent
2608      * same data as result InputStream.
2609      * <p>
2610      * This method is useful where,
2611      * </p>
2612      * <ul>
2613      * <li>Source InputStream is slow.</li>
2614      * <li>It has network resources associated, so we cannot keep it open for
2615      * long time.</li>
2616      * <li>It has network timeout associated.</li>
2617      * </ul>
2618      * <p>
2619      * It can be used in favor of {@link #toByteArray(InputStream)}, since it
2620      * avoids unnecessary allocation and copy of byte[].<br>
2621      * This method buffers the input internally, so there is no need to use a
2622      * {@link BufferedInputStream}.
2623      * </p>
2624      *
2625      * @param input Stream to be fully buffered.
2626      * @return A fully buffered stream.
2627      * @throws IOException if an I/O error occurs.
2628      * @since 2.0
2629      */
2630     public static InputStream toBufferedInputStream(final InputStream input) throws IOException {
2631         return ByteArrayOutputStream.toBufferedInputStream(input);
2632     }
2633 
2634     /**
2635      * Fetches entire contents of an {@link InputStream} and represent
2636      * same data as result InputStream.
2637      * <p>
2638      * This method is useful where,
2639      * </p>
2640      * <ul>
2641      * <li>Source InputStream is slow.</li>
2642      * <li>It has network resources associated, so we cannot keep it open for
2643      * long time.</li>
2644      * <li>It has network timeout associated.</li>
2645      * </ul>
2646      * <p>
2647      * It can be used in favor of {@link #toByteArray(InputStream)}, since it
2648      * avoids unnecessary allocation and copy of byte[].<br>
2649      * This method buffers the input internally, so there is no need to use a
2650      * {@link BufferedInputStream}.
2651      * </p>
2652      *
2653      * @param input Stream to be fully buffered.
2654      * @param size the initial buffer size
2655      * @return A fully buffered stream.
2656      * @throws IOException if an I/O error occurs.
2657      * @since 2.5
2658      */
2659     public static InputStream toBufferedInputStream(final InputStream input, final int size) throws IOException {
2660         return ByteArrayOutputStream.toBufferedInputStream(input, size);
2661     }
2662 
2663     /**
2664      * Returns the given reader if it is a {@link BufferedReader}, otherwise creates a BufferedReader from the given
2665      * reader.
2666      *
2667      * @param reader the reader to wrap or return (not null)
2668      * @return the given reader or a new {@link BufferedReader} for the given reader
2669      * @throws NullPointerException if the input parameter is null
2670      * @see #buffer(Reader)
2671      * @since 2.2
2672      */
2673     public static BufferedReader toBufferedReader(final Reader reader) {
2674         return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader);
2675     }
2676 
2677     /**
2678      * Returns the given reader if it is a {@link BufferedReader}, otherwise creates a BufferedReader from the given
2679      * reader.
2680      *
2681      * @param reader the reader to wrap or return (not null)
2682      * @param size the buffer size, if a new BufferedReader is created.
2683      * @return the given reader or a new {@link BufferedReader} for the given reader
2684      * @throws NullPointerException if the input parameter is null
2685      * @see #buffer(Reader)
2686      * @since 2.5
2687      */
2688     public static BufferedReader toBufferedReader(final Reader reader, final int size) {
2689         return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader, size);
2690     }
2691 
2692     /**
2693      * Gets the contents of an {@link InputStream} as a {@code byte[]}.
2694      * <p>
2695      * This method buffers the input internally, so there is no need to use a
2696      * {@link BufferedInputStream}.
2697      * </p>
2698      *
2699      * @param inputStream the {@link InputStream} to read.
2700      * @return the requested byte array.
2701      * @throws NullPointerException if the InputStream is {@code null}.
2702      * @throws IOException if an I/O error occurs or reading more than {@link Integer#MAX_VALUE} occurs.
2703      */
2704     public static byte[] toByteArray(final InputStream inputStream) throws IOException {
2705         // We use a ThresholdingOutputStream to avoid reading AND writing more than Integer.MAX_VALUE.
2706         try (UnsynchronizedByteArrayOutputStream ubaOutput = UnsynchronizedByteArrayOutputStream.builder().get();
2707             ThresholdingOutputStream thresholdOutput = new ThresholdingOutputStream(Integer.MAX_VALUE, os -> {
2708                 throw new IllegalArgumentException(String.format("Cannot read more than %,d into a byte array", Integer.MAX_VALUE));
2709             }, os -> ubaOutput)) {
2710             copy(inputStream, thresholdOutput);
2711             return ubaOutput.toByteArray();
2712         }
2713     }
2714 
2715     /**
2716      * Gets the contents of an {@link InputStream} as a {@code byte[]}. Use this method instead of
2717      * {@link #toByteArray(InputStream)} when {@link InputStream} size is known.
2718      *
2719      * @param input the {@link InputStream} to read.
2720      * @param size the size of {@link InputStream} to read, where 0 &lt; {@code size} &lt;= length of input stream.
2721      * @return byte [] of length {@code size}.
2722      * @throws IOException if an I/O error occurs or {@link InputStream} length is smaller than parameter {@code size}.
2723      * @throws IllegalArgumentException if {@code size} is less than zero.
2724      * @since 2.1
2725      */
2726     public static byte[] toByteArray(final InputStream input, final int size) throws IOException {
2727         if (size == 0) {
2728             return EMPTY_BYTE_ARRAY;
2729         }
2730         return toByteArray(Objects.requireNonNull(input, "input")::read, size);
2731     }
2732 
2733     /**
2734      * Gets contents of an {@link InputStream} as a {@code byte[]}.
2735      * Use this method instead of {@link #toByteArray(InputStream)}
2736      * when {@link InputStream} size is known.
2737      * <b>NOTE:</b> the method checks that the length can safely be cast to an int without truncation
2738      * before using {@link IOUtils#toByteArray(InputStream, int)} to read into the byte array.
2739      * (Arrays can have no more than Integer.MAX_VALUE entries anyway)
2740      *
2741      * @param input the {@link InputStream} to read
2742      * @param size the size of {@link InputStream} to read, where 0 &lt; {@code size} &lt;= min(Integer.MAX_VALUE, length of input stream).
2743      * @return byte [] the requested byte array, of length {@code size}
2744      * @throws IOException              if an I/O error occurs or {@link InputStream} length is less than {@code size}
2745      * @throws IllegalArgumentException if size is less than zero or size is greater than Integer.MAX_VALUE
2746      * @see IOUtils#toByteArray(InputStream, int)
2747      * @since 2.1
2748      */
2749     public static byte[] toByteArray(final InputStream input, final long size) throws IOException {
2750         if (size > Integer.MAX_VALUE) {
2751             throw new IllegalArgumentException("Size cannot be greater than Integer max value: " + size);
2752         }
2753         return toByteArray(input, (int) size);
2754     }
2755 
2756     /**
2757      * Gets the contents of an input as a {@code byte[]}.
2758      *
2759      * @param input the input to read.
2760      * @param size the size of the input to read, where 0 &lt; {@code size} &lt;= length of input.
2761      * @return byte [] of length {@code size}.
2762      * @throws IOException if an I/O error occurs or input length is smaller than parameter {@code size}.
2763      * @throws IllegalArgumentException if {@code size} is less than zero.
2764      */
2765     static byte[] toByteArray(final IOTriFunction<byte[], Integer, Integer, Integer> input, final int size) throws IOException {
2766 
2767         if (size < 0) {
2768             throw new IllegalArgumentException("Size must be equal or greater than zero: " + size);
2769         }
2770 
2771         if (size == 0) {
2772             return EMPTY_BYTE_ARRAY;
2773         }
2774 
2775         final byte[] data = byteArray(size);
2776         int offset = 0;
2777         int read;
2778 
2779         while (offset < size && (read = input.apply(data, offset, size - offset)) != EOF) {
2780             offset += read;
2781         }
2782 
2783         if (offset != size) {
2784             throw new IOException("Unexpected read size, current: " + offset + ", expected: " + size);
2785         }
2786 
2787         return data;
2788     }
2789 
2790     /**
2791      * Gets the contents of a {@link Reader} as a {@code byte[]}
2792      * using the default character encoding of the platform.
2793      * <p>
2794      * This method buffers the input internally, so there is no need to use a
2795      * {@link BufferedReader}.
2796      * </p>
2797      *
2798      * @param reader the {@link Reader} to read
2799      * @return the requested byte array
2800      * @throws NullPointerException if the input is null
2801      * @throws IOException          if an I/O error occurs
2802      * @deprecated 2.5 use {@link #toByteArray(Reader, Charset)} instead
2803      */
2804     @Deprecated
2805     public static byte[] toByteArray(final Reader reader) throws IOException {
2806         return toByteArray(reader, Charset.defaultCharset());
2807     }
2808 
2809     /**
2810      * Gets the contents of a {@link Reader} as a {@code byte[]}
2811      * using the specified character encoding.
2812      * <p>
2813      * This method buffers the input internally, so there is no need to use a
2814      * {@link BufferedReader}.
2815      * </p>
2816      *
2817      * @param reader the {@link Reader} to read
2818      * @param charset the charset to use, null means platform default
2819      * @return the requested byte array
2820      * @throws NullPointerException if the input is null
2821      * @throws IOException          if an I/O error occurs
2822      * @since 2.3
2823      */
2824     public static byte[] toByteArray(final Reader reader, final Charset charset) throws IOException {
2825         try (ByteArrayOutputStream output = new ByteArrayOutputStream()) {
2826             copy(reader, output, charset);
2827             return output.toByteArray();
2828         }
2829     }
2830 
2831     /**
2832      * Gets the contents of a {@link Reader} as a {@code byte[]}
2833      * using the specified character encoding.
2834      * <p>
2835      * Character encoding names can be found at
2836      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
2837      * </p>
2838      * <p>
2839      * This method buffers the input internally, so there is no need to use a
2840      * {@link BufferedReader}.
2841      * </p>
2842      *
2843      * @param reader the {@link Reader} to read
2844      * @param charsetName the name of the requested charset, null means platform default
2845      * @return the requested byte array
2846      * @throws NullPointerException                         if the input is null
2847      * @throws IOException                                  if an I/O error occurs
2848      * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io
2849      *                                                      .UnsupportedEncodingException} in version 2.2 if the
2850      *                                                      encoding is not supported.
2851      * @since 1.1
2852      */
2853     public static byte[] toByteArray(final Reader reader, final String charsetName) throws IOException {
2854         return toByteArray(reader, Charsets.toCharset(charsetName));
2855     }
2856 
2857     /**
2858      * Gets the contents of a {@link String} as a {@code byte[]}
2859      * using the default character encoding of the platform.
2860      * <p>
2861      * This is the same as {@link String#getBytes()}.
2862      * </p>
2863      *
2864      * @param input the {@link String} to convert
2865      * @return the requested byte array
2866      * @throws NullPointerException if the input is null
2867      * @deprecated 2.5 Use {@link String#getBytes()} instead
2868      */
2869     @Deprecated
2870     public static byte[] toByteArray(final String input) {
2871         // make explicit the use of the default charset
2872         return input.getBytes(Charset.defaultCharset());
2873     }
2874 
2875     /**
2876      * Gets the contents of a {@link URI} as a {@code byte[]}.
2877      *
2878      * @param uri the {@link URI} to read
2879      * @return the requested byte array
2880      * @throws NullPointerException if the uri is null
2881      * @throws IOException          if an I/O exception occurs
2882      * @since 2.4
2883      */
2884     public static byte[] toByteArray(final URI uri) throws IOException {
2885         return toByteArray(uri.toURL());
2886     }
2887 
2888     /**
2889      * Gets the contents of a {@link URL} as a {@code byte[]}.
2890      *
2891      * @param url the {@link URL} to read
2892      * @return the requested byte array
2893      * @throws NullPointerException if the input is null
2894      * @throws IOException          if an I/O exception occurs
2895      * @since 2.4
2896      */
2897     public static byte[] toByteArray(final URL url) throws IOException {
2898         try (CloseableURLConnection urlConnection = CloseableURLConnection.open(url)) {
2899             return toByteArray(urlConnection);
2900         }
2901     }
2902 
2903     /**
2904      * Gets the contents of a {@link URLConnection} as a {@code byte[]}.
2905      *
2906      * @param urlConnection the {@link URLConnection} to read.
2907      * @return the requested byte array.
2908      * @throws NullPointerException if the urlConn is null.
2909      * @throws IOException if an I/O exception occurs.
2910      * @since 2.4
2911      */
2912     public static byte[] toByteArray(final URLConnection urlConnection) throws IOException {
2913         try (InputStream inputStream = urlConnection.getInputStream()) {
2914             return toByteArray(inputStream);
2915         }
2916     }
2917 
2918     /**
2919      * Gets the contents of an {@link InputStream} as a character array
2920      * using the default character encoding of the platform.
2921      * <p>
2922      * This method buffers the input internally, so there is no need to use a
2923      * {@link BufferedInputStream}.
2924      * </p>
2925      *
2926      * @param inputStream the {@link InputStream} to read
2927      * @return the requested character array
2928      * @throws NullPointerException if the input is null
2929      * @throws IOException          if an I/O error occurs
2930      * @since 1.1
2931      * @deprecated 2.5 use {@link #toCharArray(InputStream, Charset)} instead
2932      */
2933     @Deprecated
2934     public static char[] toCharArray(final InputStream inputStream) throws IOException {
2935         return toCharArray(inputStream, Charset.defaultCharset());
2936     }
2937 
2938     /**
2939      * Gets the contents of an {@link InputStream} as a character array
2940      * using the specified character encoding.
2941      * <p>
2942      * This method buffers the input internally, so there is no need to use a
2943      * {@link BufferedInputStream}.
2944      * </p>
2945      *
2946      * @param inputStream the {@link InputStream} to read
2947      * @param charset the charset to use, null means platform default
2948      * @return the requested character array
2949      * @throws NullPointerException if the input is null
2950      * @throws IOException          if an I/O error occurs
2951      * @since 2.3
2952      */
2953     public static char[] toCharArray(final InputStream inputStream, final Charset charset)
2954             throws IOException {
2955         final CharArrayWriter writer = new CharArrayWriter();
2956         copy(inputStream, writer, charset);
2957         return writer.toCharArray();
2958     }
2959 
2960     /**
2961      * Gets the contents of an {@link InputStream} as a character array
2962      * using the specified character encoding.
2963      * <p>
2964      * Character encoding names can be found at
2965      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
2966      * </p>
2967      * <p>
2968      * This method buffers the input internally, so there is no need to use a
2969      * {@link BufferedInputStream}.
2970      * </p>
2971      *
2972      * @param inputStream the {@link InputStream} to read
2973      * @param charsetName the name of the requested charset, null means platform default
2974      * @return the requested character array
2975      * @throws NullPointerException                         if the input is null
2976      * @throws IOException                                  if an I/O error occurs
2977      * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io
2978      *                                                      .UnsupportedEncodingException} in version 2.2 if the
2979      *                                                      encoding is not supported.
2980      * @since 1.1
2981      */
2982     public static char[] toCharArray(final InputStream inputStream, final String charsetName) throws IOException {
2983         return toCharArray(inputStream, Charsets.toCharset(charsetName));
2984     }
2985 
2986     /**
2987      * Gets the contents of a {@link Reader} as a character array.
2988      * <p>
2989      * This method buffers the input internally, so there is no need to use a
2990      * {@link BufferedReader}.
2991      * </p>
2992      *
2993      * @param reader the {@link Reader} to read
2994      * @return the requested character array
2995      * @throws NullPointerException if the input is null
2996      * @throws IOException          if an I/O error occurs
2997      * @since 1.1
2998      */
2999     public static char[] toCharArray(final Reader reader) throws IOException {
3000         final CharArrayWriter sw = new CharArrayWriter();
3001         copy(reader, sw);
3002         return sw.toCharArray();
3003     }
3004 
3005     /**
3006      * Converts the specified CharSequence to an input stream, encoded as bytes
3007      * using the default character encoding of the platform.
3008      *
3009      * @param input the CharSequence to convert
3010      * @return an input stream
3011      * @since 2.0
3012      * @deprecated 2.5 use {@link #toInputStream(CharSequence, Charset)} instead
3013      */
3014     @Deprecated
3015     public static InputStream toInputStream(final CharSequence input) {
3016         return toInputStream(input, Charset.defaultCharset());
3017     }
3018 
3019     /**
3020      * Converts the specified CharSequence to an input stream, encoded as bytes
3021      * using the specified character encoding.
3022      *
3023      * @param input the CharSequence to convert
3024      * @param charset the charset to use, null means platform default
3025      * @return an input stream
3026      * @since 2.3
3027      */
3028     public static InputStream toInputStream(final CharSequence input, final Charset charset) {
3029         return toInputStream(input.toString(), charset);
3030     }
3031 
3032     /**
3033      * Converts the specified CharSequence to an input stream, encoded as bytes
3034      * using the specified character encoding.
3035      * <p>
3036      * Character encoding names can be found at
3037      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
3038      * </p>
3039      *
3040      * @param input the CharSequence to convert
3041      * @param charsetName the name of the requested charset, null means platform default
3042      * @return an input stream
3043      * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io
3044      *                                                      .UnsupportedEncodingException} in version 2.2 if the
3045      *                                                      encoding is not supported.
3046      * @since 2.0
3047      */
3048     public static InputStream toInputStream(final CharSequence input, final String charsetName) {
3049         return toInputStream(input, Charsets.toCharset(charsetName));
3050     }
3051 
3052     /**
3053      * Converts the specified string to an input stream, encoded as bytes
3054      * using the default character encoding of the platform.
3055      *
3056      * @param input the string to convert
3057      * @return an input stream
3058      * @since 1.1
3059      * @deprecated 2.5 use {@link #toInputStream(String, Charset)} instead
3060      */
3061     @Deprecated
3062     public static InputStream toInputStream(final String input) {
3063         return toInputStream(input, Charset.defaultCharset());
3064     }
3065 
3066     /**
3067      * Converts the specified string to an input stream, encoded as bytes
3068      * using the specified character encoding.
3069      *
3070      * @param input the string to convert
3071      * @param charset the charset to use, null means platform default
3072      * @return an input stream
3073      * @since 2.3
3074      */
3075     public static InputStream toInputStream(final String input, final Charset charset) {
3076         return new ByteArrayInputStream(input.getBytes(Charsets.toCharset(charset)));
3077     }
3078 
3079     /**
3080      * Converts the specified string to an input stream, encoded as bytes
3081      * using the specified character encoding.
3082      * <p>
3083      * Character encoding names can be found at
3084      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
3085      * </p>
3086      *
3087      * @param input the string to convert
3088      * @param charsetName the name of the requested charset, null means platform default
3089      * @return an input stream
3090      * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io
3091      *                                                      .UnsupportedEncodingException} in version 2.2 if the
3092      *                                                      encoding is not supported.
3093      * @since 1.1
3094      */
3095     public static InputStream toInputStream(final String input, final String charsetName) {
3096         return new ByteArrayInputStream(input.getBytes(Charsets.toCharset(charsetName)));
3097     }
3098 
3099     /**
3100      * Gets the contents of a {@code byte[]} as a String
3101      * using the default character encoding of the platform.
3102      *
3103      * @param input the byte array to read
3104      * @return the requested String
3105      * @throws NullPointerException if the input is null
3106      * @deprecated 2.5 Use {@link String#String(byte[])} instead
3107      */
3108     @Deprecated
3109     public static String toString(final byte[] input) {
3110         // make explicit the use of the default charset
3111         return new String(input, Charset.defaultCharset());
3112     }
3113 
3114     /**
3115      * Gets the contents of a {@code byte[]} as a String
3116      * using the specified character encoding.
3117      * <p>
3118      * Character encoding names can be found at
3119      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
3120      * </p>
3121      *
3122      * @param input the byte array to read
3123      * @param charsetName the name of the requested charset, null means platform default
3124      * @return the requested String
3125      * @throws NullPointerException if the input is null
3126      */
3127     public static String toString(final byte[] input, final String charsetName) {
3128         return new String(input, Charsets.toCharset(charsetName));
3129     }
3130 
3131     /**
3132      * Gets the contents of an {@link InputStream} as a String
3133      * using the default character encoding of the platform.
3134      * <p>
3135      * This method buffers the input internally, so there is no need to use a
3136      * {@link BufferedInputStream}.
3137      * </p>
3138      *
3139      * @param input the {@link InputStream} to read
3140      * @return the requested String
3141      * @throws NullPointerException if the input is null
3142      * @throws IOException          if an I/O error occurs
3143      * @deprecated 2.5 use {@link #toString(InputStream, Charset)} instead
3144      */
3145     @Deprecated
3146     public static String toString(final InputStream input) throws IOException {
3147         return toString(input, Charset.defaultCharset());
3148     }
3149 
3150     /**
3151      * Gets the contents of an {@link InputStream} as a String
3152      * using the specified character encoding.
3153      * <p>
3154      * This method buffers the input internally, so there is no need to use a
3155      * {@link BufferedInputStream}.
3156      * </p>
3157      *
3158      * @param input the {@link InputStream} to read
3159      * @param charset the charset to use, null means platform default
3160      * @return the requested String
3161      * @throws NullPointerException if the input is null
3162      * @throws IOException          if an I/O error occurs
3163      * @since 2.3
3164      */
3165     public static String toString(final InputStream input, final Charset charset) throws IOException {
3166         try (StringBuilderWriter sw = new StringBuilderWriter()) {
3167             copy(input, sw, charset);
3168             return sw.toString();
3169         }
3170     }
3171 
3172     /**
3173      * Gets the contents of an {@link InputStream} as a String
3174      * using the specified character encoding.
3175      * <p>
3176      * Character encoding names can be found at
3177      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
3178      * </p>
3179      * <p>
3180      * This method buffers the input internally, so there is no need to use a
3181      * {@link BufferedInputStream}.
3182      * </p>
3183      *
3184      * @param input the {@link InputStream} to read
3185      * @param charsetName the name of the requested charset, null means platform default
3186      * @return the requested String
3187      * @throws NullPointerException                         if the input is null
3188      * @throws IOException                                  if an I/O error occurs
3189      * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io
3190      *                                                      .UnsupportedEncodingException} in version 2.2 if the
3191      *                                                      encoding is not supported.
3192      */
3193     public static String toString(final InputStream input, final String charsetName)
3194             throws IOException {
3195         return toString(input, Charsets.toCharset(charsetName));
3196     }
3197 
3198     /**
3199      * Gets the contents of an {@link InputStream} from a supplier as a String
3200      * using the specified character encoding.
3201      * <p>
3202      * This method buffers the input internally, so there is no need to use a
3203      * {@link BufferedInputStream}.
3204      * </p>
3205      *
3206      * @param input supplies the {@link InputStream} to read
3207      * @param charset the charset to use, null means platform default
3208      * @return the requested String
3209      * @throws NullPointerException if the input is null
3210      * @throws IOException          if an I/O error occurs
3211      * @since 2.12.0
3212      */
3213     public static String toString(final IOSupplier<InputStream> input, final Charset charset) throws IOException {
3214         return toString(input, charset, () -> {
3215             throw new NullPointerException("input");
3216         });
3217     }
3218 
3219     /**
3220      * Gets the contents of an {@link InputStream} from a supplier as a String
3221      * using the specified character encoding.
3222      * <p>
3223      * This method buffers the input internally, so there is no need to use a
3224      * {@link BufferedInputStream}.
3225      * </p>
3226      *
3227      * @param input supplies the {@link InputStream} to read
3228      * @param charset the charset to use, null means platform default
3229      * @param defaultString the default return value if the supplier or its value is null.
3230      * @return the requested String
3231      * @throws NullPointerException if the input is null
3232      * @throws IOException          if an I/O error occurs
3233      * @since 2.12.0
3234      */
3235     public static String toString(final IOSupplier<InputStream> input, final Charset charset, final IOSupplier<String> defaultString) throws IOException {
3236         if (input == null) {
3237             return defaultString.get();
3238         }
3239         try (InputStream inputStream = input.get()) {
3240             return inputStream != null ? toString(inputStream, charset) : defaultString.get();
3241         }
3242     }
3243 
3244     /**
3245      * Gets the contents of a {@link Reader} as a String.
3246      * <p>
3247      * This method buffers the input internally, so there is no need to use a
3248      * {@link BufferedReader}.
3249      * </p>
3250      *
3251      * @param reader the {@link Reader} to read
3252      * @return the requested String
3253      * @throws NullPointerException if the input is null
3254      * @throws IOException          if an I/O error occurs
3255      */
3256     public static String toString(final Reader reader) throws IOException {
3257         try (StringBuilderWriter sw = new StringBuilderWriter()) {
3258             copy(reader, sw);
3259             return sw.toString();
3260         }
3261     }
3262 
3263     /**
3264      * Gets the contents at the given URI.
3265      *
3266      * @param uri The URI source.
3267      * @return The contents of the URL as a String.
3268      * @throws IOException if an I/O exception occurs.
3269      * @since 2.1
3270      * @deprecated 2.5 use {@link #toString(URI, Charset)} instead
3271      */
3272     @Deprecated
3273     public static String toString(final URI uri) throws IOException {
3274         return toString(uri, Charset.defaultCharset());
3275     }
3276 
3277     /**
3278      * Gets the contents at the given URI.
3279      *
3280      * @param uri The URI source.
3281      * @param encoding The encoding name for the URL contents.
3282      * @return The contents of the URL as a String.
3283      * @throws IOException if an I/O exception occurs.
3284      * @since 2.3.
3285      */
3286     public static String toString(final URI uri, final Charset encoding) throws IOException {
3287         return toString(uri.toURL(), Charsets.toCharset(encoding));
3288     }
3289 
3290     /**
3291      * Gets the contents at the given URI.
3292      *
3293      * @param uri The URI source.
3294      * @param charsetName The encoding name for the URL contents.
3295      * @return The contents of the URL as a String.
3296      * @throws IOException                                  if an I/O exception occurs.
3297      * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io
3298      *                                                      .UnsupportedEncodingException} in version 2.2 if the
3299      *                                                      encoding is not supported.
3300      * @since 2.1
3301      */
3302     public static String toString(final URI uri, final String charsetName) throws IOException {
3303         return toString(uri, Charsets.toCharset(charsetName));
3304     }
3305 
3306     /**
3307      * Gets the contents at the given URL.
3308      *
3309      * @param url The URL source.
3310      * @return The contents of the URL as a String.
3311      * @throws IOException if an I/O exception occurs.
3312      * @since 2.1
3313      * @deprecated 2.5 use {@link #toString(URL, Charset)} instead
3314      */
3315     @Deprecated
3316     public static String toString(final URL url) throws IOException {
3317         return toString(url, Charset.defaultCharset());
3318     }
3319 
3320     /**
3321      * Gets the contents at the given URL.
3322      *
3323      * @param url The URL source.
3324      * @param encoding The encoding name for the URL contents.
3325      * @return The contents of the URL as a String.
3326      * @throws IOException if an I/O exception occurs.
3327      * @since 2.3
3328      */
3329     public static String toString(final URL url, final Charset encoding) throws IOException {
3330         return toString(url::openStream, encoding);
3331     }
3332 
3333     /**
3334      * Gets the contents at the given URL.
3335      *
3336      * @param url The URL source.
3337      * @param charsetName The encoding name for the URL contents.
3338      * @return The contents of the URL as a String.
3339      * @throws IOException                                  if an I/O exception occurs.
3340      * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io
3341      *                                                      .UnsupportedEncodingException} in version 2.2 if the
3342      *                                                      encoding is not supported.
3343      * @since 2.1
3344      */
3345     public static String toString(final URL url, final String charsetName) throws IOException {
3346         return toString(url, Charsets.toCharset(charsetName));
3347     }
3348 
3349     /**
3350      * Writes bytes from a {@code byte[]} to an {@link OutputStream}.
3351      *
3352      * @param data the byte array to write, do not modify during output,
3353      * null ignored
3354      * @param output the {@link OutputStream} to write to
3355      * @throws NullPointerException if output is null
3356      * @throws IOException          if an I/O error occurs
3357      * @since 1.1
3358      */
3359     public static void write(final byte[] data, final OutputStream output)
3360             throws IOException {
3361         if (data != null) {
3362             output.write(data);
3363         }
3364     }
3365 
3366     /**
3367      * Writes bytes from a {@code byte[]} to chars on a {@link Writer}
3368      * using the default character encoding of the platform.
3369      * <p>
3370      * This method uses {@link String#String(byte[])}.
3371      * </p>
3372      *
3373      * @param data the byte array to write, do not modify during output,
3374      * null ignored
3375      * @param writer the {@link Writer} to write to
3376      * @throws NullPointerException if output is null
3377      * @throws IOException          if an I/O error occurs
3378      * @since 1.1
3379      * @deprecated 2.5 use {@link #write(byte[], Writer, Charset)} instead
3380      */
3381     @Deprecated
3382     public static void write(final byte[] data, final Writer writer) throws IOException {
3383         write(data, writer, Charset.defaultCharset());
3384     }
3385 
3386     /**
3387      * Writes bytes from a {@code byte[]} to chars on a {@link Writer}
3388      * using the specified character encoding.
3389      * <p>
3390      * This method uses {@link String#String(byte[], String)}.
3391      * </p>
3392      *
3393      * @param data the byte array to write, do not modify during output,
3394      * null ignored
3395      * @param writer the {@link Writer} to write to
3396      * @param charset the charset to use, null means platform default
3397      * @throws NullPointerException if output is null
3398      * @throws IOException          if an I/O error occurs
3399      * @since 2.3
3400      */
3401     public static void write(final byte[] data, final Writer writer, final Charset charset) throws IOException {
3402         if (data != null) {
3403             writer.write(new String(data, Charsets.toCharset(charset)));
3404         }
3405     }
3406 
3407     /**
3408      * Writes bytes from a {@code byte[]} to chars on a {@link Writer}
3409      * using the specified character encoding.
3410      * <p>
3411      * Character encoding names can be found at
3412      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
3413      * </p>
3414      * <p>
3415      * This method uses {@link String#String(byte[], String)}.
3416      * </p>
3417      *
3418      * @param data the byte array to write, do not modify during output,
3419      * null ignored
3420      * @param writer the {@link Writer} to write to
3421      * @param charsetName the name of the requested charset, null means platform default
3422      * @throws NullPointerException                         if output is null
3423      * @throws IOException                                  if an I/O error occurs
3424      * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io
3425      *                                                      .UnsupportedEncodingException} in version 2.2 if the
3426      *                                                      encoding is not supported.
3427      * @since 1.1
3428      */
3429     public static void write(final byte[] data, final Writer writer, final String charsetName) throws IOException {
3430         write(data, writer, Charsets.toCharset(charsetName));
3431     }
3432 
3433     /**
3434      * Writes chars from a {@code char[]} to bytes on an
3435      * {@link OutputStream}.
3436      * <p>
3437      * This method uses {@link String#String(char[])} and
3438      * {@link String#getBytes()}.
3439      * </p>
3440      *
3441      * @param data the char array to write, do not modify during output,
3442      * null ignored
3443      * @param output the {@link OutputStream} to write to
3444      * @throws NullPointerException if output is null
3445      * @throws IOException          if an I/O error occurs
3446      * @since 1.1
3447      * @deprecated 2.5 use {@link #write(char[], OutputStream, Charset)} instead
3448      */
3449     @Deprecated
3450     public static void write(final char[] data, final OutputStream output)
3451             throws IOException {
3452         write(data, output, Charset.defaultCharset());
3453     }
3454 
3455     /**
3456      * Writes chars from a {@code char[]} to bytes on an
3457      * {@link OutputStream} using the specified character encoding.
3458      * <p>
3459      * This method uses {@link String#String(char[])} and
3460      * {@link String#getBytes(String)}.
3461      * </p>
3462      *
3463      * @param data the char array to write, do not modify during output,
3464      * null ignored
3465      * @param output the {@link OutputStream} to write to
3466      * @param charset the charset to use, null means platform default
3467      * @throws NullPointerException if output is null
3468      * @throws IOException          if an I/O error occurs
3469      * @since 2.3
3470      */
3471     public static void write(final char[] data, final OutputStream output, final Charset charset) throws IOException {
3472         if (data != null) {
3473             write(new String(data), output, charset);
3474         }
3475     }
3476 
3477     /**
3478      * Writes chars from a {@code char[]} to bytes on an
3479      * {@link OutputStream} using the specified character encoding.
3480      * <p>
3481      * Character encoding names can be found at
3482      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
3483      * </p>
3484      * <p>
3485      * This method uses {@link String#String(char[])} and
3486      * {@link String#getBytes(String)}.
3487      * </p>
3488      *
3489      * @param data the char array to write, do not modify during output,
3490      * null ignored
3491      * @param output the {@link OutputStream} to write to
3492      * @param charsetName the name of the requested charset, null means platform default
3493      * @throws NullPointerException                         if output is null
3494      * @throws IOException                                  if an I/O error occurs
3495      * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io
3496      * .UnsupportedEncodingException} in version 2.2 if the encoding is not supported.
3497      * @since 1.1
3498      */
3499     public static void write(final char[] data, final OutputStream output, final String charsetName)
3500             throws IOException {
3501         write(data, output, Charsets.toCharset(charsetName));
3502     }
3503 
3504     /**
3505      * Writes chars from a {@code char[]} to a {@link Writer}
3506      *
3507      * @param data the char array to write, do not modify during output,
3508      * null ignored
3509      * @param writer the {@link Writer} to write to
3510      * @throws NullPointerException if output is null
3511      * @throws IOException          if an I/O error occurs
3512      * @since 1.1
3513      */
3514     public static void write(final char[] data, final Writer writer) throws IOException {
3515         if (data != null) {
3516             writer.write(data);
3517         }
3518     }
3519 
3520     /**
3521      * Writes chars from a {@link CharSequence} to bytes on an
3522      * {@link OutputStream} using the default character encoding of the
3523      * platform.
3524      * <p>
3525      * This method uses {@link String#getBytes()}.
3526      * </p>
3527      *
3528      * @param data the {@link CharSequence} to write, null ignored
3529      * @param output the {@link OutputStream} to write to
3530      * @throws NullPointerException if output is null
3531      * @throws IOException          if an I/O error occurs
3532      * @since 2.0
3533      * @deprecated 2.5 use {@link #write(CharSequence, OutputStream, Charset)} instead
3534      */
3535     @Deprecated
3536     public static void write(final CharSequence data, final OutputStream output)
3537             throws IOException {
3538         write(data, output, Charset.defaultCharset());
3539     }
3540 
3541     /**
3542      * Writes chars from a {@link CharSequence} to bytes on an
3543      * {@link OutputStream} using the specified character encoding.
3544      * <p>
3545      * This method uses {@link String#getBytes(String)}.
3546      * </p>
3547      *
3548      * @param data the {@link CharSequence} to write, null ignored
3549      * @param output the {@link OutputStream} to write to
3550      * @param charset the charset to use, null means platform default
3551      * @throws NullPointerException if output is null
3552      * @throws IOException          if an I/O error occurs
3553      * @since 2.3
3554      */
3555     public static void write(final CharSequence data, final OutputStream output, final Charset charset)
3556             throws IOException {
3557         if (data != null) {
3558             write(data.toString(), output, charset);
3559         }
3560     }
3561 
3562     /**
3563      * Writes chars from a {@link CharSequence} to bytes on an
3564      * {@link OutputStream} using the specified character encoding.
3565      * <p>
3566      * Character encoding names can be found at
3567      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
3568      * </p>
3569      * <p>
3570      * This method uses {@link String#getBytes(String)}.
3571      * </p>
3572      *
3573      * @param data the {@link CharSequence} to write, null ignored
3574      * @param output the {@link OutputStream} to write to
3575      * @param charsetName the name of the requested charset, null means platform default
3576      * @throws NullPointerException        if output is null
3577      * @throws IOException                 if an I/O error occurs
3578      * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io
3579      * .UnsupportedEncodingException} in version 2.2 if the encoding is not supported.
3580      * @since 2.0
3581      */
3582     public static void write(final CharSequence data, final OutputStream output, final String charsetName)
3583             throws IOException {
3584         write(data, output, Charsets.toCharset(charsetName));
3585     }
3586 
3587 
3588     /**
3589      * Writes chars from a {@link CharSequence} to a {@link Writer}.
3590      *
3591      * @param data the {@link CharSequence} to write, null ignored
3592      * @param writer the {@link Writer} to write to
3593      * @throws NullPointerException if output is null
3594      * @throws IOException          if an I/O error occurs
3595      * @since 2.0
3596      */
3597     public static void write(final CharSequence data, final Writer writer) throws IOException {
3598         if (data != null) {
3599             write(data.toString(), writer);
3600         }
3601     }
3602 
3603     /**
3604      * Writes chars from a {@link String} to bytes on an
3605      * {@link OutputStream} using the default character encoding of the
3606      * platform.
3607      * <p>
3608      * This method uses {@link String#getBytes()}.
3609      * </p>
3610      *
3611      * @param data the {@link String} to write, null ignored
3612      * @param output the {@link OutputStream} to write to
3613      * @throws NullPointerException if output is null
3614      * @throws IOException          if an I/O error occurs
3615      * @since 1.1
3616      * @deprecated 2.5 use {@link #write(String, OutputStream, Charset)} instead
3617      */
3618     @Deprecated
3619     public static void write(final String data, final OutputStream output)
3620             throws IOException {
3621         write(data, output, Charset.defaultCharset());
3622     }
3623 
3624     /**
3625      * Writes chars from a {@link String} to bytes on an
3626      * {@link OutputStream} using the specified character encoding.
3627      * <p>
3628      * This method uses {@link String#getBytes(String)}.
3629      * </p>
3630      *
3631      * @param data the {@link String} to write, null ignored
3632      * @param output the {@link OutputStream} to write to
3633      * @param charset the charset to use, null means platform default
3634      * @throws NullPointerException if output is null
3635      * @throws IOException          if an I/O error occurs
3636      * @since 2.3
3637      */
3638     @SuppressWarnings("resource")
3639     public static void write(final String data, final OutputStream output, final Charset charset) throws IOException {
3640         if (data != null) {
3641             // Use Charset#encode(String), since calling String#getBytes(Charset) might result in
3642             // NegativeArraySizeException or OutOfMemoryError.
3643             // The underlying OutputStream should not be closed, so the channel is not closed.
3644             Channels.newChannel(output).write(Charsets.toCharset(charset).encode(data));
3645         }
3646     }
3647 
3648     /**
3649      * Writes chars from a {@link String} to bytes on an
3650      * {@link OutputStream} using the specified character encoding.
3651      * <p>
3652      * Character encoding names can be found at
3653      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
3654      * </p>
3655      * <p>
3656      * This method uses {@link String#getBytes(String)}.
3657      * </p>
3658      *
3659      * @param data the {@link String} to write, null ignored
3660      * @param output the {@link OutputStream} to write to
3661      * @param charsetName the name of the requested charset, null means platform default
3662      * @throws NullPointerException        if output is null
3663      * @throws IOException                 if an I/O error occurs
3664      * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io
3665      * .UnsupportedEncodingException} in version 2.2 if the encoding is not supported.
3666      * @since 1.1
3667      */
3668     public static void write(final String data, final OutputStream output, final String charsetName)
3669             throws IOException {
3670         write(data, output, Charsets.toCharset(charsetName));
3671     }
3672 
3673     /**
3674      * Writes chars from a {@link String} to a {@link Writer}.
3675      *
3676      * @param data the {@link String} to write, null ignored
3677      * @param writer the {@link Writer} to write to
3678      * @throws NullPointerException if output is null
3679      * @throws IOException          if an I/O error occurs
3680      * @since 1.1
3681      */
3682     public static void write(final String data, final Writer writer) throws IOException {
3683         if (data != null) {
3684             writer.write(data);
3685         }
3686     }
3687 
3688     /**
3689      * Writes chars from a {@link StringBuffer} to bytes on an
3690      * {@link OutputStream} using the default character encoding of the
3691      * platform.
3692      * <p>
3693      * This method uses {@link String#getBytes()}.
3694      * </p>
3695      *
3696      * @param data the {@link StringBuffer} to write, null ignored
3697      * @param output the {@link OutputStream} to write to
3698      * @throws NullPointerException if output is null
3699      * @throws IOException          if an I/O error occurs
3700      * @since 1.1
3701      * @deprecated Use {@link #write(CharSequence, OutputStream)}
3702      */
3703     @Deprecated
3704     public static void write(final StringBuffer data, final OutputStream output) //NOSONAR
3705             throws IOException {
3706         write(data, output, (String) null);
3707     }
3708 
3709     /**
3710      * Writes chars from a {@link StringBuffer} to bytes on an
3711      * {@link OutputStream} using the specified character encoding.
3712      * <p>
3713      * Character encoding names can be found at
3714      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
3715      * </p>
3716      * <p>
3717      * This method uses {@link String#getBytes(String)}.
3718      * </p>
3719      *
3720      * @param data the {@link StringBuffer} to write, null ignored
3721      * @param output the {@link OutputStream} to write to
3722      * @param charsetName the name of the requested charset, null means platform default
3723      * @throws NullPointerException        if output is null
3724      * @throws IOException                 if an I/O error occurs
3725      * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io
3726      * .UnsupportedEncodingException} in version 2.2 if the encoding is not supported.
3727      * @since 1.1
3728      * @deprecated Use {@link #write(CharSequence, OutputStream, String)}.
3729      */
3730     @Deprecated
3731     public static void write(final StringBuffer data, final OutputStream output, final String charsetName) //NOSONAR
3732         throws IOException {
3733         if (data != null) {
3734             write(data.toString(), output, Charsets.toCharset(charsetName));
3735         }
3736     }
3737 
3738     /**
3739      * Writes chars from a {@link StringBuffer} to a {@link Writer}.
3740      *
3741      * @param data the {@link StringBuffer} to write, null ignored
3742      * @param writer the {@link Writer} to write to
3743      * @throws NullPointerException if output is null
3744      * @throws IOException          if an I/O error occurs
3745      * @since 1.1
3746      * @deprecated Use {@link #write(CharSequence, Writer)}
3747      */
3748     @Deprecated
3749     public static void write(final StringBuffer data, final Writer writer) //NOSONAR
3750             throws IOException {
3751         if (data != null) {
3752             writer.write(data.toString());
3753         }
3754     }
3755 
3756     /**
3757      * Writes bytes from a {@code byte[]} to an {@link OutputStream} using chunked writes.
3758      * This is intended for writing very large byte arrays which might otherwise cause excessive
3759      * memory usage if the native code has to allocate a copy.
3760      *
3761      * @param data the byte array to write, do not modify during output,
3762      * null ignored
3763      * @param output the {@link OutputStream} to write to
3764      * @throws NullPointerException if output is null
3765      * @throws IOException          if an I/O error occurs
3766      * @since 2.5
3767      */
3768     public static void writeChunked(final byte[] data, final OutputStream output)
3769             throws IOException {
3770         if (data != null) {
3771             int bytes = data.length;
3772             int offset = 0;
3773             while (bytes > 0) {
3774                 final int chunk = Math.min(bytes, DEFAULT_BUFFER_SIZE);
3775                 output.write(data, offset, chunk);
3776                 bytes -= chunk;
3777                 offset += chunk;
3778             }
3779         }
3780     }
3781 
3782     /**
3783      * Writes chars from a {@code char[]} to a {@link Writer} using chunked writes.
3784      * This is intended for writing very large byte arrays which might otherwise cause excessive
3785      * memory usage if the native code has to allocate a copy.
3786      *
3787      * @param data the char array to write, do not modify during output,
3788      * null ignored
3789      * @param writer the {@link Writer} to write to
3790      * @throws NullPointerException if output is null
3791      * @throws IOException          if an I/O error occurs
3792      * @since 2.5
3793      */
3794     public static void writeChunked(final char[] data, final Writer writer) throws IOException {
3795         if (data != null) {
3796             int bytes = data.length;
3797             int offset = 0;
3798             while (bytes > 0) {
3799                 final int chunk = Math.min(bytes, DEFAULT_BUFFER_SIZE);
3800                 writer.write(data, offset, chunk);
3801                 bytes -= chunk;
3802                 offset += chunk;
3803             }
3804         }
3805     }
3806 
3807     /**
3808      * Writes the {@link #toString()} value of each item in a collection to
3809      * an {@link OutputStream} line by line, using the default character
3810      * encoding of the platform and the specified line ending.
3811      *
3812      * @param lines the lines to write, null entries produce blank lines
3813      * @param lineEnding the line separator to use, null is system default
3814      * @param output the {@link OutputStream} to write to, not null, not closed
3815      * @throws NullPointerException if the output is null
3816      * @throws IOException          if an I/O error occurs
3817      * @since 1.1
3818      * @deprecated 2.5 use {@link #writeLines(Collection, String, OutputStream, Charset)} instead
3819      */
3820     @Deprecated
3821     public static void writeLines(final Collection<?> lines, final String lineEnding,
3822                                   final OutputStream output) throws IOException {
3823         writeLines(lines, lineEnding, output, Charset.defaultCharset());
3824     }
3825 
3826     /**
3827      * Writes the {@link #toString()} value of each item in a collection to
3828      * an {@link OutputStream} line by line, using the specified character
3829      * encoding and the specified line ending.
3830      * <p>
3831      * UTF-16 is written big-endian with no byte order mark.
3832      * For little endian, use UTF-16LE. For a BOM, write it to the stream
3833      * before calling this method.
3834      * </p>
3835      *
3836      * @param lines the lines to write, null entries produce blank lines
3837      * @param lineEnding the line separator to use, null is system default
3838      * @param output the {@link OutputStream} to write to, not null, not closed
3839      * @param charset the charset to use, null means platform default
3840      * @throws NullPointerException if output is null
3841      * @throws IOException          if an I/O error occurs
3842      * @since 2.3
3843      */
3844     public static void writeLines(final Collection<?> lines, String lineEnding, final OutputStream output,
3845             Charset charset) throws IOException {
3846         if (lines == null) {
3847             return;
3848         }
3849         if (lineEnding == null) {
3850             lineEnding = System.lineSeparator();
3851         }
3852         if (StandardCharsets.UTF_16.equals(charset)) {
3853             // don't write a BOM
3854             charset = StandardCharsets.UTF_16BE;
3855         }
3856         final byte[] eolBytes = lineEnding.getBytes(charset);
3857         for (final Object line : lines) {
3858             if (line != null) {
3859                 write(line.toString(), output, charset);
3860             }
3861             output.write(eolBytes);
3862         }
3863     }
3864 
3865     /**
3866      * Writes the {@link #toString()} value of each item in a collection to
3867      * an {@link OutputStream} line by line, using the specified character
3868      * encoding and the specified line ending.
3869      * <p>
3870      * Character encoding names can be found at
3871      * <a href="http://www.iana.org/assignments/character-sets">IANA</a>.
3872      * </p>
3873      *
3874      * @param lines the lines to write, null entries produce blank lines
3875      * @param lineEnding the line separator to use, null is system default
3876      * @param output the {@link OutputStream} to write to, not null, not closed
3877      * @param charsetName the name of the requested charset, null means platform default
3878      * @throws NullPointerException                         if the output is null
3879      * @throws IOException                                  if an I/O error occurs
3880      * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io
3881      *                                                      .UnsupportedEncodingException} in version 2.2 if the
3882      *                                                      encoding is not supported.
3883      * @since 1.1
3884      */
3885     public static void writeLines(final Collection<?> lines, final String lineEnding,
3886                                   final OutputStream output, final String charsetName) throws IOException {
3887         writeLines(lines, lineEnding, output, Charsets.toCharset(charsetName));
3888     }
3889 
3890     /**
3891      * Writes the {@link #toString()} value of each item in a collection to
3892      * a {@link Writer} line by line, using the specified line ending.
3893      *
3894      * @param lines the lines to write, null entries produce blank lines
3895      * @param lineEnding the line separator to use, null is system default
3896      * @param writer the {@link Writer} to write to, not null, not closed
3897      * @throws NullPointerException if the input is null
3898      * @throws IOException          if an I/O error occurs
3899      * @since 1.1
3900      */
3901     public static void writeLines(final Collection<?> lines, String lineEnding,
3902                                   final Writer writer) throws IOException {
3903         if (lines == null) {
3904             return;
3905         }
3906         if (lineEnding == null) {
3907             lineEnding = System.lineSeparator();
3908         }
3909         for (final Object line : lines) {
3910             if (line != null) {
3911                 writer.write(line.toString());
3912             }
3913             writer.write(lineEnding);
3914         }
3915     }
3916 
3917     /**
3918      * Returns the given Appendable if it is already a {@link Writer}, otherwise creates a Writer wrapper around the
3919      * given Appendable.
3920      *
3921      * @param appendable the Appendable to wrap or return (not null)
3922      * @return  the given Appendable or a Writer wrapper around the given Appendable
3923      * @throws NullPointerException if the input parameter is null
3924      * @since 2.7
3925      */
3926     public static Writer writer(final Appendable appendable) {
3927         Objects.requireNonNull(appendable, "appendable");
3928         if (appendable instanceof Writer) {
3929             return (Writer) appendable;
3930         }
3931         if (appendable instanceof StringBuilder) {
3932             return new StringBuilderWriter((StringBuilder) appendable);
3933         }
3934         return new AppendableWriter<>(appendable);
3935     }
3936 
3937     /**
3938      * Instances should NOT be constructed in standard programming.
3939      * @deprecated Will be private in 3.0.
3940      */
3941     @Deprecated
3942     public IOUtils() { //NOSONAR
3943     }
3944 
3945 }