All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.groupbyinc.common.apache.commons.io.IOUtils Maven / Gradle / Ivy

The newest version!
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.io;

import java.io.BufferedInputStream;
import java.io.BufferedOutputStream;
import java.io.BufferedReader;
import java.io.BufferedWriter;
import java.io.ByteArrayInputStream;
import java.io.CharArrayWriter;
import java.io.Closeable;
import java.io.EOFException;
import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.io.PrintWriter;
import java.io.Reader;
import java.io.Writer;
import java.net.HttpURLConnection;
import java.net.ServerSocket;
import java.net.Socket;
import java.net.URI;
import java.net.URL;
import java.net.URLConnection;
import java.nio.ByteBuffer;
import java.nio.channels.ReadableByteChannel;
import java.nio.channels.Selector;
import java.nio.charset.Charset;
import java.util.ArrayList;
import java.util.Collection;
import java.util.List;

import org.apache.commons.io.output.ByteArrayOutputStream;
import org.apache.commons.io.output.StringBuilderWriter;

/**
 * General IO stream manipulation utilities.
 * 

* This class provides static utility methods for input/output operations. *

    *
  • [Deprecated] closeQuietly - these methods close a stream ignoring nulls and exceptions *
  • toXxx/read - these methods read data from a stream *
  • write - these methods write data to a stream *
  • copy - these methods copy all the data from one stream to another *
  • contentEquals - these methods compare the content of two streams *
*

* The byte-to-char methods and char-to-byte methods involve a conversion step. * Two methods are provided in each case, one that uses the platform default * encoding and the other which allows you to specify an encoding. You are * encouraged to always specify an encoding because relying on the platform * default can lead to unexpected results, for example when moving from * development to production. *

* All the methods in this class that read a stream are buffered internally. * This means that there is no cause to use a BufferedInputStream * or BufferedReader. The default buffer size of 4K has been shown * to be efficient in tests. *

* The various copy methods all delegate the actual copying to one of the following methods: *

    *
  • {@link #copyLarge(InputStream, OutputStream, byte[])}
  • *
  • {@link #copyLarge(InputStream, OutputStream, long, long, byte[])}
  • *
  • {@link #copyLarge(Reader, Writer, char[])}
  • *
  • {@link #copyLarge(Reader, Writer, long, long, char[])}
  • *
* For example, {@link #copy(InputStream, OutputStream)} calls {@link #copyLarge(InputStream, OutputStream)} * which calls {@link #copy(InputStream, OutputStream, int)} which creates the buffer and calls * {@link #copyLarge(InputStream, OutputStream, byte[])}. *

* Applications can re-use buffers by using the underlying methods directly. * This may improve performance for applications that need to do a lot of copying. *

* Wherever possible, the methods in this class do not flush or close * the stream. This is to avoid making non-portable assumptions about the * streams' origin and further use. Thus the caller is still responsible for * closing streams after use. *

* Origin of code: Excalibur. * */ public class IOUtils { // NOTE: This class is focused on InputStream, OutputStream, Reader and // Writer. Each method should take at least one of these as a parameter, // or return one of them. /** * Represents the end-of-file (or stream). * @since 2.5 (made public) */ public static final int EOF = -1; /** * The Unix directory separator character. */ public static final char DIR_SEPARATOR_UNIX = '/'; /** * The Windows directory separator character. */ public static final char DIR_SEPARATOR_WINDOWS = '\\'; /** * The system directory separator character. */ public static final char DIR_SEPARATOR = File.separatorChar; /** * The Unix line separator string. */ public static final String LINE_SEPARATOR_UNIX = "\n"; /** * The Windows line separator string. */ public static final String LINE_SEPARATOR_WINDOWS = "\r\n"; /** * The system line separator string. */ public static final String LINE_SEPARATOR; static { // avoid security issues try (final StringBuilderWriter buf = new StringBuilderWriter(4); final PrintWriter out = new PrintWriter(buf)) { out.println(); LINE_SEPARATOR = buf.toString(); } } /** * The default buffer size ({@value}) to use for * {@link #copyLarge(InputStream, OutputStream)} * and * {@link #copyLarge(Reader, Writer)} */ private static final int DEFAULT_BUFFER_SIZE = 1024 * 4; /** * The default buffer size to use for the skip() methods. */ private static final int SKIP_BUFFER_SIZE = 2048; // Allocated in the relevant skip method if necessary. /* * These buffers are static and are shared between threads. * This is possible because the buffers are write-only - the contents are never read. * * N.B. there is no need to synchronize when creating these because: * - we don't care if the buffer is created multiple times (the data is ignored) * - we always use the same size buffer, so if it it is recreated it will still be OK * (if the buffer size were variable, we would need to synch. to ensure some other thread * did not create a smaller one) */ private static char[] SKIP_CHAR_BUFFER; private static byte[] SKIP_BYTE_BUFFER; /** * Instances should NOT be constructed in standard programming. */ public IOUtils() { super(); } //----------------------------------------------------------------------- /** * Closes a URLConnection. * * @param conn the connection to close. * @since 2.4 */ public static void close(final URLConnection conn) { if (conn instanceof HttpURLConnection) { ((HttpURLConnection) conn).disconnect(); } } /** * Closes an Reader unconditionally. *

* Equivalent to {@link Reader#close()}, except any exceptions will be ignored. * This is typically used in finally blocks. *

* Example code: *

     *   char[] data = new char[1024];
     *   Reader in = null;
     *   try {
     *       in = new FileReader("foo.txt");
     *       in.read(data);
     *       in.close(); //close errors are handled
     *   } catch (Exception e) {
     *       // error handling
     *   } finally {
     *       IOUtils.closeQuietly(in);
     *   }
     * 
* * @param input the Reader to close, may be null or already closed * * @deprecated As of 2.6 removed without replacement. Please use the try-with-resources statement or handle * suppressed exceptions manually. * @see Throwable#addSuppressed(java.lang.Throwable) */ @Deprecated public static void closeQuietly(final Reader input) { closeQuietly((Closeable) input); } /** * Closes an Writer unconditionally. *

* Equivalent to {@link Writer#close()}, except any exceptions will be ignored. * This is typically used in finally blocks. *

* Example code: *

     *   Writer out = null;
     *   try {
     *       out = new StringWriter();
     *       out.write("Hello World");
     *       out.close(); //close errors are handled
     *   } catch (Exception e) {
     *       // error handling
     *   } finally {
     *       IOUtils.closeQuietly(out);
     *   }
     * 
* * @param output the Writer to close, may be null or already closed * * @deprecated As of 2.6 removed without replacement. Please use the try-with-resources statement or handle * suppressed exceptions manually. * @see Throwable#addSuppressed(java.lang.Throwable) */ @Deprecated public static void closeQuietly(final Writer output) { closeQuietly((Closeable) output); } /** * Closes an InputStream unconditionally. *

* Equivalent to {@link InputStream#close()}, except any exceptions will be ignored. * This is typically used in finally blocks. *

* Example code: *

     *   byte[] data = new byte[1024];
     *   InputStream in = null;
     *   try {
     *       in = new FileInputStream("foo.txt");
     *       in.read(data);
     *       in.close(); //close errors are handled
     *   } catch (Exception e) {
     *       // error handling
     *   } finally {
     *       IOUtils.closeQuietly(in);
     *   }
     * 
* * @param input the InputStream to close, may be null or already closed * * @deprecated As of 2.6 removed without replacement. Please use the try-with-resources statement or handle * suppressed exceptions manually. * @see Throwable#addSuppressed(java.lang.Throwable) */ @Deprecated public static void closeQuietly(final InputStream input) { closeQuietly((Closeable) input); } /** * Closes an OutputStream unconditionally. *

* Equivalent to {@link OutputStream#close()}, except any exceptions will be ignored. * This is typically used in finally blocks. *

* Example code: *

     * byte[] data = "Hello, World".getBytes();
     *
     * OutputStream out = null;
     * try {
     *     out = new FileOutputStream("foo.txt");
     *     out.write(data);
     *     out.close(); //close errors are handled
     * } catch (IOException e) {
     *     // error handling
     * } finally {
     *     IOUtils.closeQuietly(out);
     * }
     * 
* * @param output the OutputStream to close, may be null or already closed * * @deprecated As of 2.6 removed without replacement. Please use the try-with-resources statement or handle * suppressed exceptions manually. * @see Throwable#addSuppressed(java.lang.Throwable) */ @Deprecated public static void closeQuietly(final OutputStream output) { closeQuietly((Closeable) output); } /** * Closes a Closeable unconditionally. *

* Equivalent to {@link Closeable#close()}, except any exceptions will be ignored. This is typically used in * finally blocks. *

* Example code: *

*
     * Closeable closeable = null;
     * try {
     *     closeable = new FileReader("foo.txt");
     *     // process closeable
     *     closeable.close();
     * } catch (Exception e) {
     *     // error handling
     * } finally {
     *     IOUtils.closeQuietly(closeable);
     * }
     * 
*

* Closing all streams: *

*
     * try {
     *     return IOUtils.copy(inputStream, outputStream);
     * } finally {
     *     IOUtils.closeQuietly(inputStream);
     *     IOUtils.closeQuietly(outputStream);
     * }
     * 
* * @param closeable the objects to close, may be null or already closed * @since 2.0 * * @deprecated As of 2.6 removed without replacement. Please use the try-with-resources statement or handle * suppressed exceptions manually. * @see Throwable#addSuppressed(java.lang.Throwable) */ @Deprecated public static void closeQuietly(final Closeable closeable) { try { if (closeable != null) { closeable.close(); } } catch (final IOException ioe) { // ignore } } /** * Closes a Closeable unconditionally. *

* Equivalent to {@link Closeable#close()}, except any exceptions will be ignored. *

* This is typically used in finally blocks to ensure that the closeable is closed * even if an Exception was thrown before the normal close statement was reached. *
* It should not be used to replace the close statement(s) * which should be present for the non-exceptional case. *
* It is only intended to simplify tidying up where normal processing has already failed * and reporting close failure as well is not necessary or useful. *

* Example code: *

*
     * Closeable closeable = null;
     * try {
     *     closeable = new FileReader("foo.txt");
     *     // processing using the closeable; may throw an Exception
     *     closeable.close(); // Normal close - exceptions not ignored
     * } catch (Exception e) {
     *     // error handling
     * } finally {
     *     IOUtils.closeQuietly(closeable); // In case normal close was skipped due to Exception
     * }
     * 
*

* Closing all streams: *
*

     * try {
     *     return IOUtils.copy(inputStream, outputStream);
     * } finally {
     *     IOUtils.closeQuietly(inputStream, outputStream);
     * }
     * 
* * @param closeables the objects to close, may be null or already closed * @see #closeQuietly(Closeable) * @since 2.5 * * @deprecated As of 2.6 removed without replacement. Please use the try-with-resources statement or handle * suppressed exceptions manually. * @see Throwable#addSuppressed(java.lang.Throwable) */ @Deprecated public static void closeQuietly(final Closeable... closeables) { if (closeables == null) { return; } for (final Closeable closeable : closeables) { closeQuietly(closeable); } } /** * Closes a Socket unconditionally. *

* Equivalent to {@link Socket#close()}, except any exceptions will be ignored. * This is typically used in finally blocks. *

* Example code: *

     *   Socket socket = null;
     *   try {
     *       socket = new Socket("http://www.foo.com/", 80);
     *       // process socket
     *       socket.close();
     *   } catch (Exception e) {
     *       // error handling
     *   } finally {
     *       IOUtils.closeQuietly(socket);
     *   }
     * 
* * @param sock the Socket to close, may be null or already closed * @since 2.0 * * @deprecated As of 2.6 removed without replacement. Please use the try-with-resources statement or handle * suppressed exceptions manually. * @see Throwable#addSuppressed(java.lang.Throwable) */ @Deprecated public static void closeQuietly(final Socket sock) { if (sock != null) { try { sock.close(); } catch (final IOException ioe) { // ignored } } } /** * Closes a Selector unconditionally. *

* Equivalent to {@link Selector#close()}, except any exceptions will be ignored. * This is typically used in finally blocks. *

* Example code: *

     *   Selector selector = null;
     *   try {
     *       selector = Selector.open();
     *       // process socket
     *
     *   } catch (Exception e) {
     *       // error handling
     *   } finally {
     *       IOUtils.closeQuietly(selector);
     *   }
     * 
* * @param selector the Selector to close, may be null or already closed * @since 2.2 * * @deprecated As of 2.6 removed without replacement. Please use the try-with-resources statement or handle * suppressed exceptions manually. * @see Throwable#addSuppressed(java.lang.Throwable) */ @Deprecated public static void closeQuietly(final Selector selector) { if (selector != null) { try { selector.close(); } catch (final IOException ioe) { // ignored } } } /** * Closes a ServerSocket unconditionally. *

* Equivalent to {@link ServerSocket#close()}, except any exceptions will be ignored. * This is typically used in finally blocks. *

* Example code: *

     *   ServerSocket socket = null;
     *   try {
     *       socket = new ServerSocket();
     *       // process socket
     *       socket.close();
     *   } catch (Exception e) {
     *       // error handling
     *   } finally {
     *       IOUtils.closeQuietly(socket);
     *   }
     * 
* * @param sock the ServerSocket to close, may be null or already closed * @since 2.2 * * @deprecated As of 2.6 removed without replacement. Please use the try-with-resources statement or handle * suppressed exceptions manually. * @see Throwable#addSuppressed(java.lang.Throwable) */ @Deprecated public static void closeQuietly(final ServerSocket sock) { if (sock != null) { try { sock.close(); } catch (final IOException ioe) { // ignored } } } /** * Fetches entire contents of an InputStream and represent * same data as result InputStream. *

* This method is useful where, *

    *
  • Source InputStream is slow.
  • *
  • It has network resources associated, so we cannot keep it open for * long time.
  • *
  • It has network timeout associated.
  • *
* It can be used in favor of {@link #toByteArray(InputStream)}, since it * avoids unnecessary allocation and copy of byte[].
* This method buffers the input internally, so there is no need to use a * BufferedInputStream. * * @param input Stream to be fully buffered. * @return A fully buffered stream. * @throws IOException if an I/O error occurs * @since 2.0 */ public static InputStream toBufferedInputStream(final InputStream input) throws IOException { return ByteArrayOutputStream.toBufferedInputStream(input); } /** * Fetches entire contents of an InputStream and represent * same data as result InputStream. *

* This method is useful where, *

    *
  • Source InputStream is slow.
  • *
  • It has network resources associated, so we cannot keep it open for * long time.
  • *
  • It has network timeout associated.
  • *
* It can be used in favor of {@link #toByteArray(InputStream)}, since it * avoids unnecessary allocation and copy of byte[].
* This method buffers the input internally, so there is no need to use a * BufferedInputStream. * * @param input Stream to be fully buffered. * @param size the initial buffer size * @return A fully buffered stream. * @throws IOException if an I/O error occurs * @since 2.5 */ public static InputStream toBufferedInputStream(final InputStream input, final int size) throws IOException { return ByteArrayOutputStream.toBufferedInputStream(input, size); } /** * Returns the given reader if it is a {@link BufferedReader}, otherwise creates a BufferedReader from the given * reader. * * @param reader the reader to wrap or return (not null) * @return the given reader or a new {@link BufferedReader} for the given reader * @throws NullPointerException if the input parameter is null * @see #buffer(Reader) * @since 2.2 */ public static BufferedReader toBufferedReader(final Reader reader) { return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader); } /** * Returns the given reader if it is a {@link BufferedReader}, otherwise creates a BufferedReader from the given * reader. * * @param reader the reader to wrap or return (not null) * @param size the buffer size, if a new BufferedReader is created. * @return the given reader or a new {@link BufferedReader} for the given reader * @throws NullPointerException if the input parameter is null * @see #buffer(Reader) * @since 2.5 */ public static BufferedReader toBufferedReader(final Reader reader, final int size) { return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader, size); } /** * Returns the given reader if it is already a {@link BufferedReader}, otherwise creates a BufferedReader from * the given reader. * * @param reader the reader to wrap or return (not null) * @return the given reader or a new {@link BufferedReader} for the given reader * @throws NullPointerException if the input parameter is null * @since 2.5 */ public static BufferedReader buffer(final Reader reader) { return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader); } /** * Returns the given reader if it is already a {@link BufferedReader}, otherwise creates a BufferedReader from the * given reader. * * @param reader the reader to wrap or return (not null) * @param size the buffer size, if a new BufferedReader is created. * @return the given reader or a new {@link BufferedReader} for the given reader * @throws NullPointerException if the input parameter is null * @since 2.5 */ public static BufferedReader buffer(final Reader reader, final int size) { return reader instanceof BufferedReader ? (BufferedReader) reader : new BufferedReader(reader, size); } /** * Returns the given Writer if it is already a {@link BufferedWriter}, otherwise creates a BufferedWriter from the * given Writer. * * @param writer the Writer to wrap or return (not null) * @return the given Writer or a new {@link BufferedWriter} for the given Writer * @throws NullPointerException if the input parameter is null * @since 2.5 */ public static BufferedWriter buffer(final Writer writer) { return writer instanceof BufferedWriter ? (BufferedWriter) writer : new BufferedWriter(writer); } /** * Returns the given Writer if it is already a {@link BufferedWriter}, otherwise creates a BufferedWriter from the * given Writer. * * @param writer the Writer to wrap or return (not null) * @param size the buffer size, if a new BufferedWriter is created. * @return the given Writer or a new {@link BufferedWriter} for the given Writer * @throws NullPointerException if the input parameter is null * @since 2.5 */ public static BufferedWriter buffer(final Writer writer, final int size) { return writer instanceof BufferedWriter ? (BufferedWriter) writer : new BufferedWriter(writer, size); } /** * Returns the given OutputStream if it is already a {@link BufferedOutputStream}, otherwise creates a * BufferedOutputStream from the given OutputStream. * * @param outputStream the OutputStream to wrap or return (not null) * @return the given OutputStream or a new {@link BufferedOutputStream} for the given OutputStream * @throws NullPointerException if the input parameter is null * @since 2.5 */ public static BufferedOutputStream buffer(final OutputStream outputStream) { // reject null early on rather than waiting for IO operation to fail if (outputStream == null) { // not checked by BufferedOutputStream throw new NullPointerException(); } return outputStream instanceof BufferedOutputStream ? (BufferedOutputStream) outputStream : new BufferedOutputStream(outputStream); } /** * Returns the given OutputStream if it is already a {@link BufferedOutputStream}, otherwise creates a * BufferedOutputStream from the given OutputStream. * * @param outputStream the OutputStream to wrap or return (not null) * @param size the buffer size, if a new BufferedOutputStream is created. * @return the given OutputStream or a new {@link BufferedOutputStream} for the given OutputStream * @throws NullPointerException if the input parameter is null * @since 2.5 */ public static BufferedOutputStream buffer(final OutputStream outputStream, final int size) { // reject null early on rather than waiting for IO operation to fail if (outputStream == null) { // not checked by BufferedOutputStream throw new NullPointerException(); } return outputStream instanceof BufferedOutputStream ? (BufferedOutputStream) outputStream : new BufferedOutputStream(outputStream, size); } /** * Returns the given InputStream if it is already a {@link BufferedInputStream}, otherwise creates a * BufferedInputStream from the given InputStream. * * @param inputStream the InputStream to wrap or return (not null) * @return the given InputStream or a new {@link BufferedInputStream} for the given InputStream * @throws NullPointerException if the input parameter is null * @since 2.5 */ public static BufferedInputStream buffer(final InputStream inputStream) { // reject null early on rather than waiting for IO operation to fail if (inputStream == null) { // not checked by BufferedInputStream throw new NullPointerException(); } return inputStream instanceof BufferedInputStream ? (BufferedInputStream) inputStream : new BufferedInputStream(inputStream); } /** * Returns the given InputStream if it is already a {@link BufferedInputStream}, otherwise creates a * BufferedInputStream from the given InputStream. * * @param inputStream the InputStream to wrap or return (not null) * @param size the buffer size, if a new BufferedInputStream is created. * @return the given InputStream or a new {@link BufferedInputStream} for the given InputStream * @throws NullPointerException if the input parameter is null * @since 2.5 */ public static BufferedInputStream buffer(final InputStream inputStream, final int size) { // reject null early on rather than waiting for IO operation to fail if (inputStream == null) { // not checked by BufferedInputStream throw new NullPointerException(); } return inputStream instanceof BufferedInputStream ? (BufferedInputStream) inputStream : new BufferedInputStream(inputStream, size); } // read toByteArray //----------------------------------------------------------------------- /** * Gets the contents of an InputStream as a byte[]. *

* This method buffers the input internally, so there is no need to use a * BufferedInputStream. * * @param input the InputStream to read from * @return the requested byte array * @throws NullPointerException if the input is null * @throws IOException if an I/O error occurs */ public static byte[] toByteArray(final InputStream input) throws IOException { try (final ByteArrayOutputStream output = new ByteArrayOutputStream()) { copy(input, output); return output.toByteArray(); } } /** * Gets contents of an InputStream as a byte[]. * Use this method instead of toByteArray(InputStream) * when InputStream size is known. * NOTE: the method checks that the length can safely be cast to an int without truncation * before using {@link IOUtils#toByteArray(java.io.InputStream, int)} to read into the byte array. * (Arrays can have no more than Integer.MAX_VALUE entries anyway) * * @param input the InputStream to read from * @param size the size of InputStream * @return the requested byte array * @throws IOException if an I/O error occurs or InputStream size differ from parameter * size * @throws IllegalArgumentException if size is less than zero or size is greater than Integer.MAX_VALUE * @see IOUtils#toByteArray(java.io.InputStream, int) * @since 2.1 */ public static byte[] toByteArray(final InputStream input, final long size) throws IOException { if (size > Integer.MAX_VALUE) { throw new IllegalArgumentException("Size cannot be greater than Integer max value: " + size); } return toByteArray(input, (int) size); } /** * Gets the contents of an InputStream as a byte[]. * Use this method instead of toByteArray(InputStream) * when InputStream size is known * * @param input the InputStream to read from * @param size the size of InputStream * @return the requested byte array * @throws IOException if an I/O error occurs or InputStream size differ from parameter * size * @throws IllegalArgumentException if size is less than zero * @since 2.1 */ public static byte[] toByteArray(final InputStream input, final int size) throws IOException { if (size < 0) { throw new IllegalArgumentException("Size must be equal or greater than zero: " + size); } if (size == 0) { return new byte[0]; } final byte[] data = new byte[size]; int offset = 0; int read; while (offset < size && (read = input.read(data, offset, size - offset)) != EOF) { offset += read; } if (offset != size) { throw new IOException("Unexpected read size. current: " + offset + ", expected: " + size); } return data; } /** * Gets the contents of a Reader as a byte[] * using the default character encoding of the platform. *

* This method buffers the input internally, so there is no need to use a * BufferedReader. * * @param input the Reader to read from * @return the requested byte array * @throws NullPointerException if the input is null * @throws IOException if an I/O error occurs * @deprecated 2.5 use {@link #toByteArray(Reader, Charset)} instead */ @Deprecated public static byte[] toByteArray(final Reader input) throws IOException { return toByteArray(input, Charset.defaultCharset()); } /** * Gets the contents of a Reader as a byte[] * using the specified character encoding. *

* This method buffers the input internally, so there is no need to use a * BufferedReader. * * @param input the Reader to read from * @param encoding the encoding to use, null means platform default * @return the requested byte array * @throws NullPointerException if the input is null * @throws IOException if an I/O error occurs * @since 2.3 */ public static byte[] toByteArray(final Reader input, final Charset encoding) throws IOException { try (final ByteArrayOutputStream output = new ByteArrayOutputStream()) { copy(input, output, encoding); return output.toByteArray(); } } /** * Gets the contents of a Reader as a byte[] * using the specified character encoding. *

* Character encoding names can be found at * IANA. *

* This method buffers the input internally, so there is no need to use a * BufferedReader. * * @param input the Reader to read from * @param encoding the encoding to use, null means platform default * @return the requested byte array * @throws NullPointerException if the input is null * @throws IOException if an I/O error occurs * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io * .UnsupportedEncodingException} in version 2.2 if the * encoding is not supported. * @since 1.1 */ public static byte[] toByteArray(final Reader input, final String encoding) throws IOException { return toByteArray(input, Charsets.toCharset(encoding)); } /** * Gets the contents of a String as a byte[] * using the default character encoding of the platform. *

* This is the same as {@link String#getBytes()}. * * @param input the String to convert * @return the requested byte array * @throws NullPointerException if the input is null * @throws IOException if an I/O error occurs (never occurs) * @deprecated 2.5 Use {@link String#getBytes()} instead */ @Deprecated public static byte[] toByteArray(final String input) throws IOException { // make explicit the use of the default charset return input.getBytes(Charset.defaultCharset()); } /** * Gets the contents of a URI as a byte[]. * * @param uri the URI to read * @return the requested byte array * @throws NullPointerException if the uri is null * @throws IOException if an I/O exception occurs * @since 2.4 */ public static byte[] toByteArray(final URI uri) throws IOException { return IOUtils.toByteArray(uri.toURL()); } /** * Gets the contents of a URL as a byte[]. * * @param url the URL to read * @return the requested byte array * @throws NullPointerException if the input is null * @throws IOException if an I/O exception occurs * @since 2.4 */ public static byte[] toByteArray(final URL url) throws IOException { final URLConnection conn = url.openConnection(); try { return IOUtils.toByteArray(conn); } finally { close(conn); } } /** * Gets the contents of a URLConnection as a byte[]. * * @param urlConn the URLConnection to read * @return the requested byte array * @throws NullPointerException if the urlConn is null * @throws IOException if an I/O exception occurs * @since 2.4 */ public static byte[] toByteArray(final URLConnection urlConn) throws IOException { try (InputStream inputStream = urlConn.getInputStream()) { return IOUtils.toByteArray(inputStream); } } // read char[] //----------------------------------------------------------------------- /** * Gets the contents of an InputStream as a character array * using the default character encoding of the platform. *

* This method buffers the input internally, so there is no need to use a * BufferedInputStream. * * @param is the InputStream to read from * @return the requested character array * @throws NullPointerException if the input is null * @throws IOException if an I/O error occurs * @since 1.1 * @deprecated 2.5 use {@link #toCharArray(InputStream, Charset)} instead */ @Deprecated public static char[] toCharArray(final InputStream is) throws IOException { return toCharArray(is, Charset.defaultCharset()); } /** * Gets the contents of an InputStream as a character array * using the specified character encoding. *

* This method buffers the input internally, so there is no need to use a * BufferedInputStream. * * @param is the InputStream to read from * @param encoding the encoding to use, null means platform default * @return the requested character array * @throws NullPointerException if the input is null * @throws IOException if an I/O error occurs * @since 2.3 */ public static char[] toCharArray(final InputStream is, final Charset encoding) throws IOException { final CharArrayWriter output = new CharArrayWriter(); copy(is, output, encoding); return output.toCharArray(); } /** * Gets the contents of an InputStream as a character array * using the specified character encoding. *

* Character encoding names can be found at * IANA. *

* This method buffers the input internally, so there is no need to use a * BufferedInputStream. * * @param is the InputStream to read from * @param encoding the encoding to use, null means platform default * @return the requested character array * @throws NullPointerException if the input is null * @throws IOException if an I/O error occurs * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io * .UnsupportedEncodingException} in version 2.2 if the * encoding is not supported. * @since 1.1 */ public static char[] toCharArray(final InputStream is, final String encoding) throws IOException { return toCharArray(is, Charsets.toCharset(encoding)); } /** * Gets the contents of a Reader as a character array. *

* This method buffers the input internally, so there is no need to use a * BufferedReader. * * @param input the Reader to read from * @return the requested character array * @throws NullPointerException if the input is null * @throws IOException if an I/O error occurs * @since 1.1 */ public static char[] toCharArray(final Reader input) throws IOException { final CharArrayWriter sw = new CharArrayWriter(); copy(input, sw); return sw.toCharArray(); } // read toString //----------------------------------------------------------------------- /** * Gets the contents of an InputStream as a String * using the default character encoding of the platform. *

* This method buffers the input internally, so there is no need to use a * BufferedInputStream. * * @param input the InputStream to read from * @return the requested String * @throws NullPointerException if the input is null * @throws IOException if an I/O error occurs * @deprecated 2.5 use {@link #toString(InputStream, Charset)} instead */ @Deprecated public static String toString(final InputStream input) throws IOException { return toString(input, Charset.defaultCharset()); } /** * Gets the contents of an InputStream as a String * using the specified character encoding. *

* This method buffers the input internally, so there is no need to use a * BufferedInputStream. *

* * @param input the InputStream to read from * @param encoding the encoding to use, null means platform default * @return the requested String * @throws NullPointerException if the input is null * @throws IOException if an I/O error occurs * @since 2.3 */ public static String toString(final InputStream input, final Charset encoding) throws IOException { try (final StringBuilderWriter sw = new StringBuilderWriter()) { copy(input, sw, encoding); return sw.toString(); } } /** * Gets the contents of an InputStream as a String * using the specified character encoding. *

* Character encoding names can be found at * IANA. *

* This method buffers the input internally, so there is no need to use a * BufferedInputStream. * * @param input the InputStream to read from * @param encoding the encoding to use, null means platform default * @return the requested String * @throws NullPointerException if the input is null * @throws IOException if an I/O error occurs * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io * .UnsupportedEncodingException} in version 2.2 if the * encoding is not supported. */ public static String toString(final InputStream input, final String encoding) throws IOException { return toString(input, Charsets.toCharset(encoding)); } /** * Gets the contents of a Reader as a String. *

* This method buffers the input internally, so there is no need to use a * BufferedReader. * * @param input the Reader to read from * @return the requested String * @throws NullPointerException if the input is null * @throws IOException if an I/O error occurs */ public static String toString(final Reader input) throws IOException { try (final StringBuilderWriter sw = new StringBuilderWriter()) { copy(input, sw); return sw.toString(); } } /** * Gets the contents at the given URI. * * @param uri The URI source. * @return The contents of the URL as a String. * @throws IOException if an I/O exception occurs. * @since 2.1 * @deprecated 2.5 use {@link #toString(URI, Charset)} instead */ @Deprecated public static String toString(final URI uri) throws IOException { return toString(uri, Charset.defaultCharset()); } /** * Gets the contents at the given URI. * * @param uri The URI source. * @param encoding The encoding name for the URL contents. * @return The contents of the URL as a String. * @throws IOException if an I/O exception occurs. * @since 2.3. */ public static String toString(final URI uri, final Charset encoding) throws IOException { return toString(uri.toURL(), Charsets.toCharset(encoding)); } /** * Gets the contents at the given URI. * * @param uri The URI source. * @param encoding The encoding name for the URL contents. * @return The contents of the URL as a String. * @throws IOException if an I/O exception occurs. * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io * .UnsupportedEncodingException} in version 2.2 if the * encoding is not supported. * @since 2.1 */ public static String toString(final URI uri, final String encoding) throws IOException { return toString(uri, Charsets.toCharset(encoding)); } /** * Gets the contents at the given URL. * * @param url The URL source. * @return The contents of the URL as a String. * @throws IOException if an I/O exception occurs. * @since 2.1 * @deprecated 2.5 use {@link #toString(URL, Charset)} instead */ @Deprecated public static String toString(final URL url) throws IOException { return toString(url, Charset.defaultCharset()); } /** * Gets the contents at the given URL. * * @param url The URL source. * @param encoding The encoding name for the URL contents. * @return The contents of the URL as a String. * @throws IOException if an I/O exception occurs. * @since 2.3 */ public static String toString(final URL url, final Charset encoding) throws IOException { try (InputStream inputStream = url.openStream()) { return toString(inputStream, encoding); } } /** * Gets the contents at the given URL. * * @param url The URL source. * @param encoding The encoding name for the URL contents. * @return The contents of the URL as a String. * @throws IOException if an I/O exception occurs. * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io * .UnsupportedEncodingException} in version 2.2 if the * encoding is not supported. * @since 2.1 */ public static String toString(final URL url, final String encoding) throws IOException { return toString(url, Charsets.toCharset(encoding)); } /** * Gets the contents of a byte[] as a String * using the default character encoding of the platform. * * @param input the byte array to read from * @return the requested String * @throws NullPointerException if the input is null * @throws IOException if an I/O error occurs (never occurs) * @deprecated 2.5 Use {@link String#String(byte[])} instead */ @Deprecated public static String toString(final byte[] input) throws IOException { // make explicit the use of the default charset return new String(input, Charset.defaultCharset()); } /** * Gets the contents of a byte[] as a String * using the specified character encoding. *

* Character encoding names can be found at * IANA. * * @param input the byte array to read from * @param encoding the encoding to use, null means platform default * @return the requested String * @throws NullPointerException if the input is null * @throws IOException if an I/O error occurs (never occurs) */ public static String toString(final byte[] input, final String encoding) throws IOException { return new String(input, Charsets.toCharset(encoding)); } // resources //----------------------------------------------------------------------- /** * Gets the contents of a classpath resource as a String using the * specified character encoding. * *

* It is expected the given name to be absolute. The * behavior is not well-defined otherwise. *

* * @param name name of the desired resource * @param encoding the encoding to use, null means platform default * @return the requested String * @throws IOException if an I/O error occurs * * @since 2.6 */ public static String resourceToString(final String name, final Charset encoding) throws IOException { return resourceToString(name, encoding, null); } /** * Gets the contents of a classpath resource as a String using the * specified character encoding. * *

* It is expected the given name to be absolute. The * behavior is not well-defined otherwise. *

* * @param name name of the desired resource * @param encoding the encoding to use, null means platform default * @param classLoader the class loader that the resolution of the resource is delegated to * @return the requested String * @throws IOException if an I/O error occurs * * @since 2.6 */ public static String resourceToString(final String name, final Charset encoding, final ClassLoader classLoader) throws IOException { return toString(resourceToURL(name, classLoader), encoding); } /** * Gets the contents of a classpath resource as a byte array. * *

* It is expected the given name to be absolute. The * behavior is not well-defined otherwise. *

* * @param name name of the desired resource * @return the requested byte array * @throws IOException if an I/O error occurs * * @since 2.6 */ public static byte[] resourceToByteArray(final String name) throws IOException { return resourceToByteArray(name, null); } /** * Gets the contents of a classpath resource as a byte array. * *

* It is expected the given name to be absolute. The * behavior is not well-defined otherwise. *

* * @param name name of the desired resource * @param classLoader the class loader that the resolution of the resource is delegated to * @return the requested byte array * @throws IOException if an I/O error occurs * * @since 2.6 */ public static byte[] resourceToByteArray(final String name, final ClassLoader classLoader) throws IOException { return toByteArray(resourceToURL(name, classLoader)); } /** * Gets a URL pointing to the given classpath resource. * *

* It is expected the given name to be absolute. The * behavior is not well-defined otherwise. *

* * @param name name of the desired resource * @return the requested URL * @throws IOException if an I/O error occurs * * @since 2.6 */ public static URL resourceToURL(final String name) throws IOException { return resourceToURL(name, null); } /** * Gets a URL pointing to the given classpath resource. * *

* It is expected the given name to be absolute. The * behavior is not well-defined otherwise. *

* * @param name name of the desired resource * @param classLoader the class loader that the resolution of the resource is delegated to * @return the requested URL * @throws IOException if an I/O error occurs * * @since 2.6 */ public static URL resourceToURL(final String name, final ClassLoader classLoader) throws IOException { // What about the thread context class loader? // What about the system class loader? final URL resource = classLoader == null ? IOUtils.class.getResource(name) : classLoader.getResource(name); if (resource == null) { throw new IOException("Resource not found: " + name); } return resource; } // readLines //----------------------------------------------------------------------- /** * Gets the contents of an InputStream as a list of Strings, * one entry per line, using the default character encoding of the platform. *

* This method buffers the input internally, so there is no need to use a * BufferedInputStream. * * @param input the InputStream to read from, not null * @return the list of Strings, never null * @throws NullPointerException if the input is null * @throws IOException if an I/O error occurs * @since 1.1 * @deprecated 2.5 use {@link #readLines(InputStream, Charset)} instead */ @Deprecated public static List readLines(final InputStream input) throws IOException { return readLines(input, Charset.defaultCharset()); } /** * Gets the contents of an InputStream as a list of Strings, * one entry per line, using the specified character encoding. *

* This method buffers the input internally, so there is no need to use a * BufferedInputStream. * * @param input the InputStream to read from, not null * @param encoding the encoding to use, null means platform default * @return the list of Strings, never null * @throws NullPointerException if the input is null * @throws IOException if an I/O error occurs * @since 2.3 */ public static List readLines(final InputStream input, final Charset encoding) throws IOException { final InputStreamReader reader = new InputStreamReader(input, Charsets.toCharset(encoding)); return readLines(reader); } /** * Gets the contents of an InputStream as a list of Strings, * one entry per line, using the specified character encoding. *

* Character encoding names can be found at * IANA. *

* This method buffers the input internally, so there is no need to use a * BufferedInputStream. * * @param input the InputStream to read from, not null * @param encoding the encoding to use, null means platform default * @return the list of Strings, never null * @throws NullPointerException if the input is null * @throws IOException if an I/O error occurs * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io * .UnsupportedEncodingException} in version 2.2 if the * encoding is not supported. * @since 1.1 */ public static List readLines(final InputStream input, final String encoding) throws IOException { return readLines(input, Charsets.toCharset(encoding)); } /** * Gets the contents of a Reader as a list of Strings, * one entry per line. *

* This method buffers the input internally, so there is no need to use a * BufferedReader. * * @param input the Reader to read from, not null * @return the list of Strings, never null * @throws NullPointerException if the input is null * @throws IOException if an I/O error occurs * @since 1.1 */ public static List readLines(final Reader input) throws IOException { final BufferedReader reader = toBufferedReader(input); final List list = new ArrayList<>(); String line = reader.readLine(); while (line != null) { list.add(line); line = reader.readLine(); } return list; } // lineIterator //----------------------------------------------------------------------- /** * Returns an Iterator for the lines in a Reader. *

* LineIterator holds a reference to the open * Reader specified here. When you have finished with the * iterator you should close the reader to free internal resources. * This can be done by closing the reader directly, or by calling * {@link LineIterator#close()} or {@link LineIterator#closeQuietly(LineIterator)}. *

* The recommended usage pattern is: *

     * try {
     *   LineIterator it = IOUtils.lineIterator(reader);
     *   while (it.hasNext()) {
     *     String line = it.nextLine();
     *     /// do something with line
     *   }
     * } finally {
     *   IOUtils.closeQuietly(reader);
     * }
     * 
* * @param reader the Reader to read from, not null * @return an Iterator of the lines in the reader, never null * @throws IllegalArgumentException if the reader is null * @since 1.2 */ public static LineIterator lineIterator(final Reader reader) { return new LineIterator(reader); } /** * Returns an Iterator for the lines in an InputStream, using * the character encoding specified (or default encoding if null). *

* LineIterator holds a reference to the open * InputStream specified here. When you have finished with * the iterator you should close the stream to free internal resources. * This can be done by closing the stream directly, or by calling * {@link LineIterator#close()} or {@link LineIterator#closeQuietly(LineIterator)}. *

* The recommended usage pattern is: *

     * try {
     *   LineIterator it = IOUtils.lineIterator(stream, charset);
     *   while (it.hasNext()) {
     *     String line = it.nextLine();
     *     /// do something with line
     *   }
     * } finally {
     *   IOUtils.closeQuietly(stream);
     * }
     * 
* * @param input the InputStream to read from, not null * @param encoding the encoding to use, null means platform default * @return an Iterator of the lines in the reader, never null * @throws IllegalArgumentException if the input is null * @throws IOException if an I/O error occurs, such as if the encoding is invalid * @since 2.3 */ public static LineIterator lineIterator(final InputStream input, final Charset encoding) throws IOException { return new LineIterator(new InputStreamReader(input, Charsets.toCharset(encoding))); } /** * Returns an Iterator for the lines in an InputStream, using * the character encoding specified (or default encoding if null). *

* LineIterator holds a reference to the open * InputStream specified here. When you have finished with * the iterator you should close the stream to free internal resources. * This can be done by closing the stream directly, or by calling * {@link LineIterator#close()} or {@link LineIterator#closeQuietly(LineIterator)}. *

* The recommended usage pattern is: *

     * try {
     *   LineIterator it = IOUtils.lineIterator(stream, "UTF-8");
     *   while (it.hasNext()) {
     *     String line = it.nextLine();
     *     /// do something with line
     *   }
     * } finally {
     *   IOUtils.closeQuietly(stream);
     * }
     * 
* * @param input the InputStream to read from, not null * @param encoding the encoding to use, null means platform default * @return an Iterator of the lines in the reader, never null * @throws IllegalArgumentException if the input is null * @throws IOException if an I/O error occurs, such as if the encoding is invalid * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io * .UnsupportedEncodingException} in version 2.2 if the * encoding is not supported. * @since 1.2 */ public static LineIterator lineIterator(final InputStream input, final String encoding) throws IOException { return lineIterator(input, Charsets.toCharset(encoding)); } //----------------------------------------------------------------------- /** * Converts the specified CharSequence to an input stream, encoded as bytes * using the default character encoding of the platform. * * @param input the CharSequence to convert * @return an input stream * @since 2.0 * @deprecated 2.5 use {@link #toInputStream(CharSequence, Charset)} instead */ @Deprecated public static InputStream toInputStream(final CharSequence input) { return toInputStream(input, Charset.defaultCharset()); } /** * Converts the specified CharSequence to an input stream, encoded as bytes * using the specified character encoding. * * @param input the CharSequence to convert * @param encoding the encoding to use, null means platform default * @return an input stream * @since 2.3 */ public static InputStream toInputStream(final CharSequence input, final Charset encoding) { return toInputStream(input.toString(), encoding); } /** * Converts the specified CharSequence to an input stream, encoded as bytes * using the specified character encoding. *

* Character encoding names can be found at * IANA. * * @param input the CharSequence to convert * @param encoding the encoding to use, null means platform default * @return an input stream * @throws IOException if the encoding is invalid * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io * .UnsupportedEncodingException} in version 2.2 if the * encoding is not supported. * @since 2.0 */ public static InputStream toInputStream(final CharSequence input, final String encoding) throws IOException { return toInputStream(input, Charsets.toCharset(encoding)); } //----------------------------------------------------------------------- /** * Converts the specified string to an input stream, encoded as bytes * using the default character encoding of the platform. * * @param input the string to convert * @return an input stream * @since 1.1 * @deprecated 2.5 use {@link #toInputStream(String, Charset)} instead */ @Deprecated public static InputStream toInputStream(final String input) { return toInputStream(input, Charset.defaultCharset()); } /** * Converts the specified string to an input stream, encoded as bytes * using the specified character encoding. * * @param input the string to convert * @param encoding the encoding to use, null means platform default * @return an input stream * @since 2.3 */ public static InputStream toInputStream(final String input, final Charset encoding) { return new ByteArrayInputStream(input.getBytes(Charsets.toCharset(encoding))); } /** * Converts the specified string to an input stream, encoded as bytes * using the specified character encoding. *

* Character encoding names can be found at * IANA. * * @param input the string to convert * @param encoding the encoding to use, null means platform default * @return an input stream * @throws IOException if the encoding is invalid * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io * .UnsupportedEncodingException} in version 2.2 if the * encoding is not supported. * @since 1.1 */ public static InputStream toInputStream(final String input, final String encoding) throws IOException { final byte[] bytes = input.getBytes(Charsets.toCharset(encoding)); return new ByteArrayInputStream(bytes); } // write byte[] //----------------------------------------------------------------------- /** * Writes bytes from a byte[] to an OutputStream. * * @param data the byte array to write, do not modify during output, * null ignored * @param output the OutputStream to write to * @throws NullPointerException if output is null * @throws IOException if an I/O error occurs * @since 1.1 */ public static void write(final byte[] data, final OutputStream output) throws IOException { if (data != null) { output.write(data); } } /** * Writes bytes from a byte[] to an OutputStream using chunked writes. * This is intended for writing very large byte arrays which might otherwise cause excessive * memory usage if the native code has to allocate a copy. * * @param data the byte array to write, do not modify during output, * null ignored * @param output the OutputStream to write to * @throws NullPointerException if output is null * @throws IOException if an I/O error occurs * @since 2.5 */ public static void writeChunked(final byte[] data, final OutputStream output) throws IOException { if (data != null) { int bytes = data.length; int offset = 0; while (bytes > 0) { final int chunk = Math.min(bytes, DEFAULT_BUFFER_SIZE); output.write(data, offset, chunk); bytes -= chunk; offset += chunk; } } } /** * Writes bytes from a byte[] to chars on a Writer * using the default character encoding of the platform. *

* This method uses {@link String#String(byte[])}. * * @param data the byte array to write, do not modify during output, * null ignored * @param output the Writer to write to * @throws NullPointerException if output is null * @throws IOException if an I/O error occurs * @since 1.1 * @deprecated 2.5 use {@link #write(byte[], Writer, Charset)} instead */ @Deprecated public static void write(final byte[] data, final Writer output) throws IOException { write(data, output, Charset.defaultCharset()); } /** * Writes bytes from a byte[] to chars on a Writer * using the specified character encoding. *

* This method uses {@link String#String(byte[], String)}. * * @param data the byte array to write, do not modify during output, * null ignored * @param output the Writer to write to * @param encoding the encoding to use, null means platform default * @throws NullPointerException if output is null * @throws IOException if an I/O error occurs * @since 2.3 */ public static void write(final byte[] data, final Writer output, final Charset encoding) throws IOException { if (data != null) { output.write(new String(data, Charsets.toCharset(encoding))); } } /** * Writes bytes from a byte[] to chars on a Writer * using the specified character encoding. *

* Character encoding names can be found at * IANA. *

* This method uses {@link String#String(byte[], String)}. * * @param data the byte array to write, do not modify during output, * null ignored * @param output the Writer to write to * @param encoding the encoding to use, null means platform default * @throws NullPointerException if output is null * @throws IOException if an I/O error occurs * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io * .UnsupportedEncodingException} in version 2.2 if the * encoding is not supported. * @since 1.1 */ public static void write(final byte[] data, final Writer output, final String encoding) throws IOException { write(data, output, Charsets.toCharset(encoding)); } // write char[] //----------------------------------------------------------------------- /** * Writes chars from a char[] to a Writer * * @param data the char array to write, do not modify during output, * null ignored * @param output the Writer to write to * @throws NullPointerException if output is null * @throws IOException if an I/O error occurs * @since 1.1 */ public static void write(final char[] data, final Writer output) throws IOException { if (data != null) { output.write(data); } } /** * Writes chars from a char[] to a Writer using chunked writes. * This is intended for writing very large byte arrays which might otherwise cause excessive * memory usage if the native code has to allocate a copy. * * @param data the char array to write, do not modify during output, * null ignored * @param output the Writer to write to * @throws NullPointerException if output is null * @throws IOException if an I/O error occurs * @since 2.5 */ public static void writeChunked(final char[] data, final Writer output) throws IOException { if (data != null) { int bytes = data.length; int offset = 0; while (bytes > 0) { final int chunk = Math.min(bytes, DEFAULT_BUFFER_SIZE); output.write(data, offset, chunk); bytes -= chunk; offset += chunk; } } } /** * Writes chars from a char[] to bytes on an * OutputStream. *

* This method uses {@link String#String(char[])} and * {@link String#getBytes()}. * * @param data the char array to write, do not modify during output, * null ignored * @param output the OutputStream to write to * @throws NullPointerException if output is null * @throws IOException if an I/O error occurs * @since 1.1 * @deprecated 2.5 use {@link #write(char[], OutputStream, Charset)} instead */ @Deprecated public static void write(final char[] data, final OutputStream output) throws IOException { write(data, output, Charset.defaultCharset()); } /** * Writes chars from a char[] to bytes on an * OutputStream using the specified character encoding. *

* This method uses {@link String#String(char[])} and * {@link String#getBytes(String)}. * * @param data the char array to write, do not modify during output, * null ignored * @param output the OutputStream to write to * @param encoding the encoding to use, null means platform default * @throws NullPointerException if output is null * @throws IOException if an I/O error occurs * @since 2.3 */ public static void write(final char[] data, final OutputStream output, final Charset encoding) throws IOException { if (data != null) { output.write(new String(data).getBytes(Charsets.toCharset(encoding))); } } /** * Writes chars from a char[] to bytes on an * OutputStream using the specified character encoding. *

* Character encoding names can be found at * IANA. *

* This method uses {@link String#String(char[])} and * {@link String#getBytes(String)}. * * @param data the char array to write, do not modify during output, * null ignored * @param output the OutputStream to write to * @param encoding the encoding to use, null means platform default * @throws NullPointerException if output is null * @throws IOException if an I/O error occurs * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io * .UnsupportedEncodingException} in version 2.2 if the encoding is not supported. * @since 1.1 */ public static void write(final char[] data, final OutputStream output, final String encoding) throws IOException { write(data, output, Charsets.toCharset(encoding)); } // write CharSequence //----------------------------------------------------------------------- /** * Writes chars from a CharSequence to a Writer. * * @param data the CharSequence to write, null ignored * @param output the Writer to write to * @throws NullPointerException if output is null * @throws IOException if an I/O error occurs * @since 2.0 */ public static void write(final CharSequence data, final Writer output) throws IOException { if (data != null) { write(data.toString(), output); } } /** * Writes chars from a CharSequence to bytes on an * OutputStream using the default character encoding of the * platform. *

* This method uses {@link String#getBytes()}. * * @param data the CharSequence to write, null ignored * @param output the OutputStream to write to * @throws NullPointerException if output is null * @throws IOException if an I/O error occurs * @since 2.0 * @deprecated 2.5 use {@link #write(CharSequence, OutputStream, Charset)} instead */ @Deprecated public static void write(final CharSequence data, final OutputStream output) throws IOException { write(data, output, Charset.defaultCharset()); } /** * Writes chars from a CharSequence to bytes on an * OutputStream using the specified character encoding. *

* This method uses {@link String#getBytes(String)}. * * @param data the CharSequence to write, null ignored * @param output the OutputStream to write to * @param encoding the encoding to use, null means platform default * @throws NullPointerException if output is null * @throws IOException if an I/O error occurs * @since 2.3 */ public static void write(final CharSequence data, final OutputStream output, final Charset encoding) throws IOException { if (data != null) { write(data.toString(), output, encoding); } } /** * Writes chars from a CharSequence to bytes on an * OutputStream using the specified character encoding. *

* Character encoding names can be found at * IANA. *

* This method uses {@link String#getBytes(String)}. * * @param data the CharSequence to write, null ignored * @param output the OutputStream to write to * @param encoding the encoding to use, null means platform default * @throws NullPointerException if output is null * @throws IOException if an I/O error occurs * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io * .UnsupportedEncodingException} in version 2.2 if the encoding is not supported. * @since 2.0 */ public static void write(final CharSequence data, final OutputStream output, final String encoding) throws IOException { write(data, output, Charsets.toCharset(encoding)); } // write String //----------------------------------------------------------------------- /** * Writes chars from a String to a Writer. * * @param data the String to write, null ignored * @param output the Writer to write to * @throws NullPointerException if output is null * @throws IOException if an I/O error occurs * @since 1.1 */ public static void write(final String data, final Writer output) throws IOException { if (data != null) { output.write(data); } } /** * Writes chars from a String to bytes on an * OutputStream using the default character encoding of the * platform. *

* This method uses {@link String#getBytes()}. * * @param data the String to write, null ignored * @param output the OutputStream to write to * @throws NullPointerException if output is null * @throws IOException if an I/O error occurs * @since 1.1 * @deprecated 2.5 use {@link #write(String, OutputStream, Charset)} instead */ @Deprecated public static void write(final String data, final OutputStream output) throws IOException { write(data, output, Charset.defaultCharset()); } /** * Writes chars from a String to bytes on an * OutputStream using the specified character encoding. *

* This method uses {@link String#getBytes(String)}. * * @param data the String to write, null ignored * @param output the OutputStream to write to * @param encoding the encoding to use, null means platform default * @throws NullPointerException if output is null * @throws IOException if an I/O error occurs * @since 2.3 */ public static void write(final String data, final OutputStream output, final Charset encoding) throws IOException { if (data != null) { output.write(data.getBytes(Charsets.toCharset(encoding))); } } /** * Writes chars from a String to bytes on an * OutputStream using the specified character encoding. *

* Character encoding names can be found at * IANA. *

* This method uses {@link String#getBytes(String)}. * * @param data the String to write, null ignored * @param output the OutputStream to write to * @param encoding the encoding to use, null means platform default * @throws NullPointerException if output is null * @throws IOException if an I/O error occurs * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io * .UnsupportedEncodingException} in version 2.2 if the encoding is not supported. * @since 1.1 */ public static void write(final String data, final OutputStream output, final String encoding) throws IOException { write(data, output, Charsets.toCharset(encoding)); } // write StringBuffer //----------------------------------------------------------------------- /** * Writes chars from a StringBuffer to a Writer. * * @param data the StringBuffer to write, null ignored * @param output the Writer to write to * @throws NullPointerException if output is null * @throws IOException if an I/O error occurs * @since 1.1 * @deprecated replaced by write(CharSequence, Writer) */ @Deprecated public static void write(final StringBuffer data, final Writer output) throws IOException { if (data != null) { output.write(data.toString()); } } /** * Writes chars from a StringBuffer to bytes on an * OutputStream using the default character encoding of the * platform. *

* This method uses {@link String#getBytes()}. * * @param data the StringBuffer to write, null ignored * @param output the OutputStream to write to * @throws NullPointerException if output is null * @throws IOException if an I/O error occurs * @since 1.1 * @deprecated replaced by write(CharSequence, OutputStream) */ @Deprecated public static void write(final StringBuffer data, final OutputStream output) throws IOException { write(data, output, (String) null); } /** * Writes chars from a StringBuffer to bytes on an * OutputStream using the specified character encoding. *

* Character encoding names can be found at * IANA. *

* This method uses {@link String#getBytes(String)}. * * @param data the StringBuffer to write, null ignored * @param output the OutputStream to write to * @param encoding the encoding to use, null means platform default * @throws NullPointerException if output is null * @throws IOException if an I/O error occurs * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io * .UnsupportedEncodingException} in version 2.2 if the encoding is not supported. * @since 1.1 * @deprecated replaced by write(CharSequence, OutputStream, String) */ @Deprecated public static void write(final StringBuffer data, final OutputStream output, final String encoding) throws IOException { if (data != null) { output.write(data.toString().getBytes(Charsets.toCharset(encoding))); } } // writeLines //----------------------------------------------------------------------- /** * Writes the toString() value of each item in a collection to * an OutputStream line by line, using the default character * encoding of the platform and the specified line ending. * * @param lines the lines to write, null entries produce blank lines * @param lineEnding the line separator to use, null is system default * @param output the OutputStream to write to, not null, not closed * @throws NullPointerException if the output is null * @throws IOException if an I/O error occurs * @since 1.1 * @deprecated 2.5 use {@link #writeLines(Collection, String, OutputStream, Charset)} instead */ @Deprecated public static void writeLines(final Collection lines, final String lineEnding, final OutputStream output) throws IOException { writeLines(lines, lineEnding, output, Charset.defaultCharset()); } /** * Writes the toString() value of each item in a collection to * an OutputStream line by line, using the specified character * encoding and the specified line ending. * * @param lines the lines to write, null entries produce blank lines * @param lineEnding the line separator to use, null is system default * @param output the OutputStream to write to, not null, not closed * @param encoding the encoding to use, null means platform default * @throws NullPointerException if the output is null * @throws IOException if an I/O error occurs * @since 2.3 */ public static void writeLines(final Collection lines, String lineEnding, final OutputStream output, final Charset encoding) throws IOException { if (lines == null) { return; } if (lineEnding == null) { lineEnding = LINE_SEPARATOR; } final Charset cs = Charsets.toCharset(encoding); for (final Object line : lines) { if (line != null) { output.write(line.toString().getBytes(cs)); } output.write(lineEnding.getBytes(cs)); } } /** * Writes the toString() value of each item in a collection to * an OutputStream line by line, using the specified character * encoding and the specified line ending. *

* Character encoding names can be found at * IANA. * * @param lines the lines to write, null entries produce blank lines * @param lineEnding the line separator to use, null is system default * @param output the OutputStream to write to, not null, not closed * @param encoding the encoding to use, null means platform default * @throws NullPointerException if the output is null * @throws IOException if an I/O error occurs * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io * .UnsupportedEncodingException} in version 2.2 if the * encoding is not supported. * @since 1.1 */ public static void writeLines(final Collection lines, final String lineEnding, final OutputStream output, final String encoding) throws IOException { writeLines(lines, lineEnding, output, Charsets.toCharset(encoding)); } /** * Writes the toString() value of each item in a collection to * a Writer line by line, using the specified line ending. * * @param lines the lines to write, null entries produce blank lines * @param lineEnding the line separator to use, null is system default * @param writer the Writer to write to, not null, not closed * @throws NullPointerException if the input is null * @throws IOException if an I/O error occurs * @since 1.1 */ public static void writeLines(final Collection lines, String lineEnding, final Writer writer) throws IOException { if (lines == null) { return; } if (lineEnding == null) { lineEnding = LINE_SEPARATOR; } for (final Object line : lines) { if (line != null) { writer.write(line.toString()); } writer.write(lineEnding); } } // copy from InputStream //----------------------------------------------------------------------- /** * Copies bytes from an InputStream to an * OutputStream. *

* This method buffers the input internally, so there is no need to use a * BufferedInputStream. *

* Large streams (over 2GB) will return a bytes copied value of * -1 after the copy has completed since the correct * number of bytes cannot be returned as an int. For large streams * use the copyLarge(InputStream, OutputStream) method. * * @param input the InputStream to read from * @param output the OutputStream to write to * @return the number of bytes copied, or -1 if > Integer.MAX_VALUE * @throws NullPointerException if the input or output is null * @throws IOException if an I/O error occurs * @since 1.1 */ public static int copy(final InputStream input, final OutputStream output) throws IOException { final long count = copyLarge(input, output); if (count > Integer.MAX_VALUE) { return -1; } return (int) count; } /** * Copies bytes from an InputStream to an OutputStream using an internal buffer of the * given size. *

* This method buffers the input internally, so there is no need to use a BufferedInputStream. *

* * @param input the InputStream to read from * @param output the OutputStream to write to * @param bufferSize the bufferSize used to copy from the input to the output * @return the number of bytes copied * @throws NullPointerException if the input or output is null * @throws IOException if an I/O error occurs * @since 2.5 */ public static long copy(final InputStream input, final OutputStream output, final int bufferSize) throws IOException { return copyLarge(input, output, new byte[bufferSize]); } /** * Copies bytes from a large (over 2GB) InputStream to an * OutputStream. *

* This method buffers the input internally, so there is no need to use a * BufferedInputStream. *

* The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}. * * @param input the InputStream to read from * @param output the OutputStream to write to * @return the number of bytes copied * @throws NullPointerException if the input or output is null * @throws IOException if an I/O error occurs * @since 1.3 */ public static long copyLarge(final InputStream input, final OutputStream output) throws IOException { return copy(input, output, DEFAULT_BUFFER_SIZE); } /** * Copies bytes from a large (over 2GB) InputStream to an * OutputStream. *

* This method uses the provided buffer, so there is no need to use a * BufferedInputStream. *

* * @param input the InputStream to read from * @param output the OutputStream to write to * @param buffer the buffer to use for the copy * @return the number of bytes copied * @throws NullPointerException if the input or output is null * @throws IOException if an I/O error occurs * @since 2.2 */ public static long copyLarge(final InputStream input, final OutputStream output, final byte[] buffer) throws IOException { long count = 0; int n; while (EOF != (n = input.read(buffer))) { output.write(buffer, 0, n); count += n; } return count; } /** * Copies some or all bytes from a large (over 2GB) InputStream to an * OutputStream, optionally skipping input bytes. *

* This method buffers the input internally, so there is no need to use a * BufferedInputStream. *

*

* Note that the implementation uses {@link #skip(InputStream, long)}. * This means that the method may be considerably less efficient than using the actual skip implementation, * this is done to guarantee that the correct number of characters are skipped. *

* The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}. * * @param input the InputStream to read from * @param output the OutputStream to write to * @param inputOffset : number of bytes to skip from input before copying * -ve values are ignored * @param length : number of bytes to copy. -ve means all * @return the number of bytes copied * @throws NullPointerException if the input or output is null * @throws IOException if an I/O error occurs * @since 2.2 */ public static long copyLarge(final InputStream input, final OutputStream output, final long inputOffset, final long length) throws IOException { return copyLarge(input, output, inputOffset, length, new byte[DEFAULT_BUFFER_SIZE]); } /** * Copies some or all bytes from a large (over 2GB) InputStream to an * OutputStream, optionally skipping input bytes. *

* This method uses the provided buffer, so there is no need to use a * BufferedInputStream. *

*

* Note that the implementation uses {@link #skip(InputStream, long)}. * This means that the method may be considerably less efficient than using the actual skip implementation, * this is done to guarantee that the correct number of characters are skipped. *

* * @param input the InputStream to read from * @param output the OutputStream to write to * @param inputOffset : number of bytes to skip from input before copying * -ve values are ignored * @param length : number of bytes to copy. -ve means all * @param buffer the buffer to use for the copy * @return the number of bytes copied * @throws NullPointerException if the input or output is null * @throws IOException if an I/O error occurs * @since 2.2 */ public static long copyLarge(final InputStream input, final OutputStream output, final long inputOffset, final long length, final byte[] buffer) throws IOException { if (inputOffset > 0) { skipFully(input, inputOffset); } if (length == 0) { return 0; } final int bufferLength = buffer.length; int bytesToRead = bufferLength; if (length > 0 && length < bufferLength) { bytesToRead = (int) length; } int read; long totalRead = 0; while (bytesToRead > 0 && EOF != (read = input.read(buffer, 0, bytesToRead))) { output.write(buffer, 0, read); totalRead += read; if (length > 0) { // only adjust length if not reading to the end // Note the cast must work because buffer.length is an integer bytesToRead = (int) Math.min(length - totalRead, bufferLength); } } return totalRead; } /** * Copies bytes from an InputStream to chars on a * Writer using the default character encoding of the platform. *

* This method buffers the input internally, so there is no need to use a * BufferedInputStream. *

* This method uses {@link InputStreamReader}. * * @param input the InputStream to read from * @param output the Writer to write to * @throws NullPointerException if the input or output is null * @throws IOException if an I/O error occurs * @since 1.1 * @deprecated 2.5 use {@link #copy(InputStream, Writer, Charset)} instead */ @Deprecated public static void copy(final InputStream input, final Writer output) throws IOException { copy(input, output, Charset.defaultCharset()); } /** * Copies bytes from an InputStream to chars on a * Writer using the specified character encoding. *

* This method buffers the input internally, so there is no need to use a * BufferedInputStream. *

* This method uses {@link InputStreamReader}. * * @param input the InputStream to read from * @param output the Writer to write to * @param inputEncoding the encoding to use for the input stream, null means platform default * @throws NullPointerException if the input or output is null * @throws IOException if an I/O error occurs * @since 2.3 */ public static void copy(final InputStream input, final Writer output, final Charset inputEncoding) throws IOException { final InputStreamReader in = new InputStreamReader(input, Charsets.toCharset(inputEncoding)); copy(in, output); } /** * Copies bytes from an InputStream to chars on a * Writer using the specified character encoding. *

* This method buffers the input internally, so there is no need to use a * BufferedInputStream. *

* Character encoding names can be found at * IANA. *

* This method uses {@link InputStreamReader}. * * @param input the InputStream to read from * @param output the Writer to write to * @param inputEncoding the encoding to use for the InputStream, null means platform default * @throws NullPointerException if the input or output is null * @throws IOException if an I/O error occurs * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io * .UnsupportedEncodingException} in version 2.2 if the * encoding is not supported. * @since 1.1 */ public static void copy(final InputStream input, final Writer output, final String inputEncoding) throws IOException { copy(input, output, Charsets.toCharset(inputEncoding)); } // copy from Reader //----------------------------------------------------------------------- /** * Copies chars from a Reader to a Writer. *

* This method buffers the input internally, so there is no need to use a * BufferedReader. *

* Large streams (over 2GB) will return a chars copied value of * -1 after the copy has completed since the correct * number of chars cannot be returned as an int. For large streams * use the copyLarge(Reader, Writer) method. * * @param input the Reader to read from * @param output the Writer to write to * @return the number of characters copied, or -1 if > Integer.MAX_VALUE * @throws NullPointerException if the input or output is null * @throws IOException if an I/O error occurs * @since 1.1 */ public static int copy(final Reader input, final Writer output) throws IOException { final long count = copyLarge(input, output); if (count > Integer.MAX_VALUE) { return -1; } return (int) count; } /** * Copies chars from a large (over 2GB) Reader to a Writer. *

* This method buffers the input internally, so there is no need to use a * BufferedReader. *

* The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}. * * @param input the Reader to read from * @param output the Writer to write to * @return the number of characters copied * @throws NullPointerException if the input or output is null * @throws IOException if an I/O error occurs * @since 1.3 */ public static long copyLarge(final Reader input, final Writer output) throws IOException { return copyLarge(input, output, new char[DEFAULT_BUFFER_SIZE]); } /** * Copies chars from a large (over 2GB) Reader to a Writer. *

* This method uses the provided buffer, so there is no need to use a * BufferedReader. *

* * @param input the Reader to read from * @param output the Writer to write to * @param buffer the buffer to be used for the copy * @return the number of characters copied * @throws NullPointerException if the input or output is null * @throws IOException if an I/O error occurs * @since 2.2 */ public static long copyLarge(final Reader input, final Writer output, final char[] buffer) throws IOException { long count = 0; int n; while (EOF != (n = input.read(buffer))) { output.write(buffer, 0, n); count += n; } return count; } /** * Copies some or all chars from a large (over 2GB) InputStream to an * OutputStream, optionally skipping input chars. *

* This method buffers the input internally, so there is no need to use a * BufferedReader. *

* The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}. * * @param input the Reader to read from * @param output the Writer to write to * @param inputOffset : number of chars to skip from input before copying * -ve values are ignored * @param length : number of chars to copy. -ve means all * @return the number of chars copied * @throws NullPointerException if the input or output is null * @throws IOException if an I/O error occurs * @since 2.2 */ public static long copyLarge(final Reader input, final Writer output, final long inputOffset, final long length) throws IOException { return copyLarge(input, output, inputOffset, length, new char[DEFAULT_BUFFER_SIZE]); } /** * Copies some or all chars from a large (over 2GB) InputStream to an * OutputStream, optionally skipping input chars. *

* This method uses the provided buffer, so there is no need to use a * BufferedReader. *

* * @param input the Reader to read from * @param output the Writer to write to * @param inputOffset : number of chars to skip from input before copying * -ve values are ignored * @param length : number of chars to copy. -ve means all * @param buffer the buffer to be used for the copy * @return the number of chars copied * @throws NullPointerException if the input or output is null * @throws IOException if an I/O error occurs * @since 2.2 */ public static long copyLarge(final Reader input, final Writer output, final long inputOffset, final long length, final char[] buffer) throws IOException { if (inputOffset > 0) { skipFully(input, inputOffset); } if (length == 0) { return 0; } int bytesToRead = buffer.length; if (length > 0 && length < buffer.length) { bytesToRead = (int) length; } int read; long totalRead = 0; while (bytesToRead > 0 && EOF != (read = input.read(buffer, 0, bytesToRead))) { output.write(buffer, 0, read); totalRead += read; if (length > 0) { // only adjust length if not reading to the end // Note the cast must work because buffer.length is an integer bytesToRead = (int) Math.min(length - totalRead, buffer.length); } } return totalRead; } /** * Copies chars from a Reader to bytes on an * OutputStream using the default character encoding of the * platform, and calling flush. *

* This method buffers the input internally, so there is no need to use a * BufferedReader. *

* Due to the implementation of OutputStreamWriter, this method performs a * flush. *

* This method uses {@link OutputStreamWriter}. * * @param input the Reader to read from * @param output the OutputStream to write to * @throws NullPointerException if the input or output is null * @throws IOException if an I/O error occurs * @since 1.1 * @deprecated 2.5 use {@link #copy(Reader, OutputStream, Charset)} instead */ @Deprecated public static void copy(final Reader input, final OutputStream output) throws IOException { copy(input, output, Charset.defaultCharset()); } /** * Copies chars from a Reader to bytes on an * OutputStream using the specified character encoding, and * calling flush. *

* This method buffers the input internally, so there is no need to use a * BufferedReader. *

*

* Due to the implementation of OutputStreamWriter, this method performs a * flush. *

*

* This method uses {@link OutputStreamWriter}. *

* * @param input the Reader to read from * @param output the OutputStream to write to * @param outputEncoding the encoding to use for the OutputStream, null means platform default * @throws NullPointerException if the input or output is null * @throws IOException if an I/O error occurs * @since 2.3 */ public static void copy(final Reader input, final OutputStream output, final Charset outputEncoding) throws IOException { final OutputStreamWriter out = new OutputStreamWriter(output, Charsets.toCharset(outputEncoding)); copy(input, out); // XXX Unless anyone is planning on rewriting OutputStreamWriter, // we have to flush here. out.flush(); } /** * Copies chars from a Reader to bytes on an * OutputStream using the specified character encoding, and * calling flush. *

* This method buffers the input internally, so there is no need to use a * BufferedReader. *

* Character encoding names can be found at * IANA. *

* Due to the implementation of OutputStreamWriter, this method performs a * flush. *

* This method uses {@link OutputStreamWriter}. * * @param input the Reader to read from * @param output the OutputStream to write to * @param outputEncoding the encoding to use for the OutputStream, null means platform default * @throws NullPointerException if the input or output is null * @throws IOException if an I/O error occurs * @throws java.nio.charset.UnsupportedCharsetException thrown instead of {@link java.io * .UnsupportedEncodingException} in version 2.2 if the * encoding is not supported. * @since 1.1 */ public static void copy(final Reader input, final OutputStream output, final String outputEncoding) throws IOException { copy(input, output, Charsets.toCharset(outputEncoding)); } // content equals //----------------------------------------------------------------------- /** * Compares the contents of two Streams to determine if they are equal or * not. *

* This method buffers the input internally using * BufferedInputStream if they are not already buffered. * * @param input1 the first stream * @param input2 the second stream * @return true if the content of the streams are equal or they both don't * exist, false otherwise * @throws NullPointerException if either input is null * @throws IOException if an I/O error occurs */ public static boolean contentEquals(InputStream input1, InputStream input2) throws IOException { if (input1 == input2) { return true; } if (!(input1 instanceof BufferedInputStream)) { input1 = new BufferedInputStream(input1); } if (!(input2 instanceof BufferedInputStream)) { input2 = new BufferedInputStream(input2); } int ch = input1.read(); while (EOF != ch) { final int ch2 = input2.read(); if (ch != ch2) { return false; } ch = input1.read(); } final int ch2 = input2.read(); return ch2 == EOF; } /** * Compares the contents of two Readers to determine if they are equal or * not. *

* This method buffers the input internally using * BufferedReader if they are not already buffered. * * @param input1 the first reader * @param input2 the second reader * @return true if the content of the readers are equal or they both don't * exist, false otherwise * @throws NullPointerException if either input is null * @throws IOException if an I/O error occurs * @since 1.1 */ public static boolean contentEquals(Reader input1, Reader input2) throws IOException { if (input1 == input2) { return true; } input1 = toBufferedReader(input1); input2 = toBufferedReader(input2); int ch = input1.read(); while (EOF != ch) { final int ch2 = input2.read(); if (ch != ch2) { return false; } ch = input1.read(); } final int ch2 = input2.read(); return ch2 == EOF; } /** * Compares the contents of two Readers to determine if they are equal or * not, ignoring EOL characters. *

* This method buffers the input internally using * BufferedReader if they are not already buffered. * * @param input1 the first reader * @param input2 the second reader * @return true if the content of the readers are equal (ignoring EOL differences), false otherwise * @throws NullPointerException if either input is null * @throws IOException if an I/O error occurs * @since 2.2 */ public static boolean contentEqualsIgnoreEOL(final Reader input1, final Reader input2) throws IOException { if (input1 == input2) { return true; } final BufferedReader br1 = toBufferedReader(input1); final BufferedReader br2 = toBufferedReader(input2); String line1 = br1.readLine(); String line2 = br2.readLine(); while (line1 != null && line2 != null && line1.equals(line2)) { line1 = br1.readLine(); line2 = br2.readLine(); } return line1 == null ? line2 == null ? true : false : line1.equals(line2); } /** * Skips bytes from an input byte stream. * This implementation guarantees that it will read as many bytes * as possible before giving up; this may not always be the case for * skip() implementations in subclasses of {@link InputStream}. *

* Note that the implementation uses {@link InputStream#read(byte[], int, int)} rather * than delegating to {@link InputStream#skip(long)}. * This means that the method may be considerably less efficient than using the actual skip implementation, * this is done to guarantee that the correct number of bytes are skipped. *

* * @param input byte stream to skip * @param toSkip number of bytes to skip. * @return number of bytes actually skipped. * @throws IOException if there is a problem reading the file * @throws IllegalArgumentException if toSkip is negative * @see InputStream#skip(long) * @see IO-203 - Add skipFully() method for InputStreams * @since 2.0 */ public static long skip(final InputStream input, final long toSkip) throws IOException { if (toSkip < 0) { throw new IllegalArgumentException("Skip count must be non-negative, actual: " + toSkip); } /* * N.B. no need to synchronize this because: - we don't care if the buffer is created multiple times (the data * is ignored) - we always use the same size buffer, so if it it is recreated it will still be OK (if the buffer * size were variable, we would need to synch. to ensure some other thread did not create a smaller one) */ if (SKIP_BYTE_BUFFER == null) { SKIP_BYTE_BUFFER = new byte[SKIP_BUFFER_SIZE]; } long remain = toSkip; while (remain > 0) { // See https://issues.apache.org/jira/browse/IO-203 for why we use read() rather than delegating to skip() final long n = input.read(SKIP_BYTE_BUFFER, 0, (int) Math.min(remain, SKIP_BUFFER_SIZE)); if (n < 0) { // EOF break; } remain -= n; } return toSkip - remain; } /** * Skips bytes from a ReadableByteChannel. * This implementation guarantees that it will read as many bytes * as possible before giving up. * * @param input ReadableByteChannel to skip * @param toSkip number of bytes to skip. * @return number of bytes actually skipped. * @throws IOException if there is a problem reading the ReadableByteChannel * @throws IllegalArgumentException if toSkip is negative * @since 2.5 */ public static long skip(final ReadableByteChannel input, final long toSkip) throws IOException { if (toSkip < 0) { throw new IllegalArgumentException("Skip count must be non-negative, actual: " + toSkip); } final ByteBuffer skipByteBuffer = ByteBuffer.allocate((int) Math.min(toSkip, SKIP_BUFFER_SIZE)); long remain = toSkip; while (remain > 0) { skipByteBuffer.position(0); skipByteBuffer.limit((int) Math.min(remain, SKIP_BUFFER_SIZE)); final int n = input.read(skipByteBuffer); if (n == EOF) { break; } remain -= n; } return toSkip - remain; } /** * Skips characters from an input character stream. * This implementation guarantees that it will read as many characters * as possible before giving up; this may not always be the case for * skip() implementations in subclasses of {@link Reader}. *

* Note that the implementation uses {@link Reader#read(char[], int, int)} rather * than delegating to {@link Reader#skip(long)}. * This means that the method may be considerably less efficient than using the actual skip implementation, * this is done to guarantee that the correct number of characters are skipped. *

* * @param input character stream to skip * @param toSkip number of characters to skip. * @return number of characters actually skipped. * @throws IOException if there is a problem reading the file * @throws IllegalArgumentException if toSkip is negative * @see Reader#skip(long) * @see IO-203 - Add skipFully() method for InputStreams * @since 2.0 */ public static long skip(final Reader input, final long toSkip) throws IOException { if (toSkip < 0) { throw new IllegalArgumentException("Skip count must be non-negative, actual: " + toSkip); } /* * N.B. no need to synchronize this because: - we don't care if the buffer is created multiple times (the data * is ignored) - we always use the same size buffer, so if it it is recreated it will still be OK (if the buffer * size were variable, we would need to synch. to ensure some other thread did not create a smaller one) */ if (SKIP_CHAR_BUFFER == null) { SKIP_CHAR_BUFFER = new char[SKIP_BUFFER_SIZE]; } long remain = toSkip; while (remain > 0) { // See https://issues.apache.org/jira/browse/IO-203 for why we use read() rather than delegating to skip() final long n = input.read(SKIP_CHAR_BUFFER, 0, (int) Math.min(remain, SKIP_BUFFER_SIZE)); if (n < 0) { // EOF break; } remain -= n; } return toSkip - remain; } /** * Skips the requested number of bytes or fail if there are not enough left. *

* This allows for the possibility that {@link InputStream#skip(long)} may * not skip as many bytes as requested (most likely because of reaching EOF). *

* Note that the implementation uses {@link #skip(InputStream, long)}. * This means that the method may be considerably less efficient than using the actual skip implementation, * this is done to guarantee that the correct number of characters are skipped. *

* * @param input stream to skip * @param toSkip the number of bytes to skip * @throws IOException if there is a problem reading the file * @throws IllegalArgumentException if toSkip is negative * @throws EOFException if the number of bytes skipped was incorrect * @see InputStream#skip(long) * @since 2.0 */ public static void skipFully(final InputStream input, final long toSkip) throws IOException { if (toSkip < 0) { throw new IllegalArgumentException("Bytes to skip must not be negative: " + toSkip); } final long skipped = skip(input, toSkip); if (skipped != toSkip) { throw new EOFException("Bytes to skip: " + toSkip + " actual: " + skipped); } } /** * Skips the requested number of bytes or fail if there are not enough left. * * @param input ReadableByteChannel to skip * @param toSkip the number of bytes to skip * @throws IOException if there is a problem reading the ReadableByteChannel * @throws IllegalArgumentException if toSkip is negative * @throws EOFException if the number of bytes skipped was incorrect * @since 2.5 */ public static void skipFully(final ReadableByteChannel input, final long toSkip) throws IOException { if (toSkip < 0) { throw new IllegalArgumentException("Bytes to skip must not be negative: " + toSkip); } final long skipped = skip(input, toSkip); if (skipped != toSkip) { throw new EOFException("Bytes to skip: " + toSkip + " actual: " + skipped); } } /** * Skips the requested number of characters or fail if there are not enough left. *

* This allows for the possibility that {@link Reader#skip(long)} may * not skip as many characters as requested (most likely because of reaching EOF). *

* Note that the implementation uses {@link #skip(Reader, long)}. * This means that the method may be considerably less efficient than using the actual skip implementation, * this is done to guarantee that the correct number of characters are skipped. *

* * @param input stream to skip * @param toSkip the number of characters to skip * @throws IOException if there is a problem reading the file * @throws IllegalArgumentException if toSkip is negative * @throws EOFException if the number of characters skipped was incorrect * @see Reader#skip(long) * @since 2.0 */ public static void skipFully(final Reader input, final long toSkip) throws IOException { final long skipped = skip(input, toSkip); if (skipped != toSkip) { throw new EOFException("Chars to skip: " + toSkip + " actual: " + skipped); } } /** * Reads characters from an input character stream. * This implementation guarantees that it will read as many characters * as possible before giving up; this may not always be the case for * subclasses of {@link Reader}. * * @param input where to read input from * @param buffer destination * @param offset initial offset into buffer * @param length length to read, must be >= 0 * @return actual length read; may be less than requested if EOF was reached * @throws IOException if a read error occurs * @since 2.2 */ public static int read(final Reader input, final char[] buffer, final int offset, final int length) throws IOException { if (length < 0) { throw new IllegalArgumentException("Length must not be negative: " + length); } int remaining = length; while (remaining > 0) { final int location = length - remaining; final int count = input.read(buffer, offset + location, remaining); if (EOF == count) { // EOF break; } remaining -= count; } return length - remaining; } /** * Reads characters from an input character stream. * This implementation guarantees that it will read as many characters * as possible before giving up; this may not always be the case for * subclasses of {@link Reader}. * * @param input where to read input from * @param buffer destination * @return actual length read; may be less than requested if EOF was reached * @throws IOException if a read error occurs * @since 2.2 */ public static int read(final Reader input, final char[] buffer) throws IOException { return read(input, buffer, 0, buffer.length); } /** * Reads bytes from an input stream. * This implementation guarantees that it will read as many bytes * as possible before giving up; this may not always be the case for * subclasses of {@link InputStream}. * * @param input where to read input from * @param buffer destination * @param offset initial offset into buffer * @param length length to read, must be >= 0 * @return actual length read; may be less than requested if EOF was reached * @throws IOException if a read error occurs * @since 2.2 */ public static int read(final InputStream input, final byte[] buffer, final int offset, final int length) throws IOException { if (length < 0) { throw new IllegalArgumentException("Length must not be negative: " + length); } int remaining = length; while (remaining > 0) { final int location = length - remaining; final int count = input.read(buffer, offset + location, remaining); if (EOF == count) { // EOF break; } remaining -= count; } return length - remaining; } /** * Reads bytes from an input stream. * This implementation guarantees that it will read as many bytes * as possible before giving up; this may not always be the case for * subclasses of {@link InputStream}. * * @param input where to read input from * @param buffer destination * @return actual length read; may be less than requested if EOF was reached * @throws IOException if a read error occurs * @since 2.2 */ public static int read(final InputStream input, final byte[] buffer) throws IOException { return read(input, buffer, 0, buffer.length); } /** * Reads bytes from a ReadableByteChannel. *

* This implementation guarantees that it will read as many bytes * as possible before giving up; this may not always be the case for * subclasses of {@link ReadableByteChannel}. * * @param input the byte channel to read * @param buffer byte buffer destination * @return the actual length read; may be less than requested if EOF was reached * @throws IOException if a read error occurs * @since 2.5 */ public static int read(final ReadableByteChannel input, final ByteBuffer buffer) throws IOException { final int length = buffer.remaining(); while (buffer.remaining() > 0) { final int count = input.read(buffer); if (EOF == count) { // EOF break; } } return length - buffer.remaining(); } /** * Reads the requested number of characters or fail if there are not enough left. *

* This allows for the possibility that {@link Reader#read(char[], int, int)} may * not read as many characters as requested (most likely because of reaching EOF). * * @param input where to read input from * @param buffer destination * @param offset initial offset into buffer * @param length length to read, must be >= 0 * @throws IOException if there is a problem reading the file * @throws IllegalArgumentException if length is negative * @throws EOFException if the number of characters read was incorrect * @since 2.2 */ public static void readFully(final Reader input, final char[] buffer, final int offset, final int length) throws IOException { final int actual = read(input, buffer, offset, length); if (actual != length) { throw new EOFException("Length to read: " + length + " actual: " + actual); } } /** * Reads the requested number of characters or fail if there are not enough left. *

* This allows for the possibility that {@link Reader#read(char[], int, int)} may * not read as many characters as requested (most likely because of reaching EOF). * * @param input where to read input from * @param buffer destination * @throws IOException if there is a problem reading the file * @throws IllegalArgumentException if length is negative * @throws EOFException if the number of characters read was incorrect * @since 2.2 */ public static void readFully(final Reader input, final char[] buffer) throws IOException { readFully(input, buffer, 0, buffer.length); } /** * Reads the requested number of bytes or fail if there are not enough left. *

* This allows for the possibility that {@link InputStream#read(byte[], int, int)} may * not read as many bytes as requested (most likely because of reaching EOF). * * @param input where to read input from * @param buffer destination * @param offset initial offset into buffer * @param length length to read, must be >= 0 * @throws IOException if there is a problem reading the file * @throws IllegalArgumentException if length is negative * @throws EOFException if the number of bytes read was incorrect * @since 2.2 */ public static void readFully(final InputStream input, final byte[] buffer, final int offset, final int length) throws IOException { final int actual = read(input, buffer, offset, length); if (actual != length) { throw new EOFException("Length to read: " + length + " actual: " + actual); } } /** * Reads the requested number of bytes or fail if there are not enough left. *

* This allows for the possibility that {@link InputStream#read(byte[], int, int)} may * not read as many bytes as requested (most likely because of reaching EOF). * * @param input where to read input from * @param buffer destination * @throws IOException if there is a problem reading the file * @throws IllegalArgumentException if length is negative * @throws EOFException if the number of bytes read was incorrect * @since 2.2 */ public static void readFully(final InputStream input, final byte[] buffer) throws IOException { readFully(input, buffer, 0, buffer.length); } /** * Reads the requested number of bytes or fail if there are not enough left. *

* This allows for the possibility that {@link InputStream#read(byte[], int, int)} may * not read as many bytes as requested (most likely because of reaching EOF). * * @param input where to read input from * @param length length to read, must be >= 0 * @return the bytes read from input * @throws IOException if there is a problem reading the file * @throws IllegalArgumentException if length is negative * @throws EOFException if the number of bytes read was incorrect * @since 2.5 */ public static byte[] readFully(final InputStream input, final int length) throws IOException { final byte[] buffer = new byte[length]; readFully(input, buffer, 0, buffer.length); return buffer; } /** * Reads the requested number of bytes or fail if there are not enough left. *

* This allows for the possibility that {@link ReadableByteChannel#read(ByteBuffer)} may * not read as many bytes as requested (most likely because of reaching EOF). * * @param input the byte channel to read * @param buffer byte buffer destination * @throws IOException if there is a problem reading the file * @throws EOFException if the number of bytes read was incorrect * @since 2.5 */ public static void readFully(final ReadableByteChannel input, final ByteBuffer buffer) throws IOException { final int expected = buffer.remaining(); final int actual = read(input, buffer); if (actual != expected) { throw new EOFException("Length to read: " + expected + " actual: " + actual); } } }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy