This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-io.git
The following commit(s) were added to refs/heads/master by this push:
new 4859ac25a Javadoc
4859ac25a is described below
commit 4859ac25a06b1b69b5ed41dceb57098624665862
Author: Gary Gregory <[email protected]>
AuthorDate: Wed Aug 27 09:36:56 2025 -0400
Javadoc
---
src/main/java/org/apache/commons/io/IOUtils.java | 1169 ++++++++++------------
1 file changed, 555 insertions(+), 614 deletions(-)
diff --git a/src/main/java/org/apache/commons/io/IOUtils.java
b/src/main/java/org/apache/commons/io/IOUtils.java
index aa3752dc4..cd8d042a9 100644
--- a/src/main/java/org/apache/commons/io/IOUtils.java
+++ b/src/main/java/org/apache/commons/io/IOUtils.java
@@ -225,9 +225,9 @@ public class IOUtils {
* 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
+ * @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
*/
@SuppressWarnings("resource") // parameter null check
@@ -243,10 +243,10 @@ public static BufferedInputStream buffer(final
InputStream 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 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
+ * @return the given InputStream or a new {@link BufferedInputStream} for
the given InputStream.
+ * @throws NullPointerException if the input parameter is null.
* @since 2.5
*/
@SuppressWarnings("resource") // parameter null check
@@ -262,9 +262,9 @@ public static BufferedInputStream buffer(final InputStream
inputStream, final in
* 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 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
+ * @throws NullPointerException if the input parameter is null..
* @since 2.5
*/
@SuppressWarnings("resource") // parameter null check
@@ -280,10 +280,10 @@ public static BufferedOutputStream buffer(final
OutputStream 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 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
+ * @return the given OutputStream or a new {@link BufferedOutputStream}
for the given OutputStream.
+ * @throws NullPointerException if the input parameter is null.
* @since 2.5
*/
@SuppressWarnings("resource") // parameter null check
@@ -299,9 +299,9 @@ public static BufferedOutputStream buffer(final
OutputStream outputStream, final
* 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
+ * @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) {
@@ -312,10 +312,10 @@ public static BufferedReader buffer(final Reader 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 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
+ * @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) {
@@ -326,9 +326,9 @@ public static BufferedReader buffer(final Reader reader,
final int 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
+ * @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) {
@@ -339,10 +339,10 @@ public static BufferedWriter buffer(final Writer 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 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
+ * @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) {
@@ -474,7 +474,7 @@ public static void close(final URLConnection conn) {
/**
* Avoids the need to type cast.
*
- * @param closeable the object to close, may be null
+ * @param closeable the object to close, may be null.
*/
private static void closeQ(final Closeable closeable) {
closeQuietly(closeable, null);
@@ -516,7 +516,7 @@ private static void closeQ(final Closeable closeable) {
* Also consider using a try-with-resources statement where appropriate.
* </p>
*
- * @param closeable the objects to close, may be null or already closed
+ * @param closeable the objects to close, may be null or already closed.
* @since 2.0
* @see Throwable#addSuppressed(Throwable)
*/
@@ -565,7 +565,7 @@ public static void closeQuietly(final Closeable closeable) {
* <p>
* Also consider using a try-with-resources statement where appropriate.
* </p>
- * @param closeables the objects to close, may be null or already closed
+ * @param closeables the objects to close, may be null or already closed.
* @see #closeQuietly(Closeable)
* @since 2.5
* @see Throwable#addSuppressed(Throwable)
@@ -621,7 +621,7 @@ public static void closeQuietly(final Closeable closeable,
final Consumer<Except
* Also consider using a try-with-resources statement where appropriate.
* </p>
*
- * @param input the InputStream to close, may be null or already closed
+ * @param input the InputStream to close, may be null or already closed.
* @see Throwable#addSuppressed(Throwable)
*/
public static void closeQuietly(final InputStream input) {
@@ -634,7 +634,7 @@ public static void closeQuietly(final InputStream input) {
* Equivalent calling {@link Closeable#close()} on each element, except
any exceptions will be ignored.
* </p>
*
- * @param closeables the objects to close, may be null or already closed
+ * @param closeables the objects to close, may be null or already closed.
* @see #closeQuietly(Closeable)
* @since 2.12.0
*/
@@ -671,7 +671,7 @@ public static void closeQuietly(final Iterable<Closeable>
closeables) {
* Also consider using a try-with-resources statement where appropriate.
* </p>
*
- * @param output the OutputStream to close, may be null or already closed
+ * @param output the OutputStream to close, may be null or already closed.
* @see Throwable#addSuppressed(Throwable)
*/
public static void closeQuietly(final OutputStream output) {
@@ -704,7 +704,7 @@ public static void closeQuietly(final OutputStream output) {
* Also consider using a try-with-resources statement where appropriate.
* </p>
*
- * @param reader the Reader to close, may be null or already closed
+ * @param reader the Reader to close, may be null or already closed.
* @see Throwable#addSuppressed(Throwable)
*/
public static void closeQuietly(final Reader reader) {
@@ -736,7 +736,7 @@ public static void closeQuietly(final Reader reader) {
* Also consider using a try-with-resources statement where appropriate.
* </p>
*
- * @param selector the Selector to close, may be null or already closed
+ * @param selector the Selector to close, may be null or already closed.
* @since 2.2
* @see Throwable#addSuppressed(Throwable)
*/
@@ -769,7 +769,7 @@ public static void closeQuietly(final Selector selector) {
* Also consider using a try-with-resources statement where appropriate.
* </p>
*
- * @param serverSocket the ServerSocket to close, may be null or already
closed
+ * @param serverSocket the ServerSocket to close, may be null or already
closed.
* @since 2.2
* @see Throwable#addSuppressed(Throwable)
*/
@@ -802,7 +802,7 @@ public static void closeQuietly(final ServerSocket
serverSocket) {
* Also consider using a try-with-resources statement where appropriate.
* </p>
*
- * @param socket the Socket to close, may be null or already closed
+ * @param socket the Socket to close, may be null or already closed.
* @since 2.0
* @see Throwable#addSuppressed(Throwable)
*/
@@ -816,7 +816,7 @@ public static void closeQuietly(final Socket socket) {
* Equivalent calling {@link Closeable#close()} on each element, except
any exceptions will be ignored.
* </p>
*
- * @param closeables the objects to close, may be null or already closed
+ * @param closeables the objects to close, may be null or already closed.
* @see #closeQuietly(Closeable)
* @since 2.12.0
*/
@@ -851,7 +851,7 @@ public static void closeQuietly(final Stream<Closeable>
closeables) {
* Also consider using a try-with-resources statement where appropriate.
* </p>
*
- * @param writer the Writer to close, may be null or already closed
+ * @param writer the Writer to close, may be null or already closed.
* @see Throwable#addSuppressed(Throwable)
*/
public static void closeQuietly(final Writer writer) {
@@ -898,11 +898,11 @@ public static long consume(final Reader input) throws
IOException {
* {@link BufferedInputStream} if they are not already buffered.
* </p>
*
- * @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 IOException if an I/O error occurs
+ * @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 IOException if an I/O error occurs.
*/
@SuppressWarnings("resource") // Caller closes input streams
public static boolean contentEquals(final InputStream input1, final
InputStream input2) throws IOException {
@@ -936,11 +936,11 @@ private static boolean contentEquals(final Iterator<?>
iterator1, final Iterator
* This method buffers the input internally using {@link BufferedReader}
if they are not already buffered.
* </p>
*
- * @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
+ * @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(final Reader input1, final Reader
input2) throws IOException {
@@ -1018,11 +1018,11 @@ private static boolean contentEqualsIgnoreEOL(final
BufferedReader reader1, fina
* {@link BufferedReader} if they are not already buffered.
* </p>
*
- * @param reader1 the first reader
- * @param reader2 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 UncheckedIOException if an I/O error occurs
+ * @param reader1 the first reader.
+ * @param reader2 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 UncheckedIOException if an I/O error occurs.
* @since 2.2
*/
@SuppressWarnings("resource")
@@ -1068,16 +1068,15 @@ public static int copy(final InputStream inputStream,
final OutputStream outputS
* </p>
*
* @param inputStream the {@link InputStream} to read.
- * @param outputStream the {@link OutputStream} to write to
- * @param bufferSize the bufferSize used to copy from the input to the
output
+ * @param outputStream the {@link 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 InputStream is {@code null}.
* @throws NullPointerException if the OutputStream is {@code null}.
* @throws IOException if an I/O error occurs.
* @since 2.5
*/
- public static long copy(final InputStream inputStream, final OutputStream
outputStream, final int bufferSize)
- throws IOException {
+ public static long copy(final InputStream inputStream, final OutputStream
outputStream, final int bufferSize) throws IOException {
return copyLarge(inputStream, outputStream, byteArray(bufferSize));
}
@@ -1092,16 +1091,15 @@ public static long copy(final InputStream inputStream,
final OutputStream output
* This method uses {@link InputStreamReader}.
* </p>
*
- * @param input the {@link InputStream} to read
- * @param writer the {@link Writer} to write to
- * @throws NullPointerException if the input or output is null
- * @throws IOException if an I/O error occurs
+ * @param input the {@link InputStream} to read.
+ * @param writer the {@link 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 Use {@link #copy(InputStream, Writer, Charset)} instead
+ * @deprecated Use {@link #copy(InputStream, Writer, Charset)} instead.
*/
@Deprecated
- public static void copy(final InputStream input, final Writer writer)
- throws IOException {
+ public static void copy(final InputStream input, final Writer writer)
throws IOException {
copy(input, writer, Charset.defaultCharset());
}
@@ -1116,15 +1114,14 @@ public static void copy(final InputStream input, final
Writer writer)
* This method uses {@link InputStreamReader}.
* </p>
*
- * @param input the {@link InputStream} to read
- * @param writer the {@link Writer} to write to
- * @param inputCharset the charset 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
+ * @param input the {@link InputStream} to read.
+ * @param writer the {@link Writer} to write to.
+ * @param inputCharset the charset 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 writer,
final Charset inputCharset)
- throws IOException {
+ public static void copy(final InputStream input, final Writer writer,
final Charset inputCharset) throws IOException {
copy(new InputStreamReader(input, Charsets.toCharset(inputCharset)),
writer);
}
@@ -1145,14 +1142,13 @@ public static void copy(final InputStream input, final
Writer writer, final Char
*
* @param input the {@link InputStream} to read
* @param writer the {@link Writer} to write to
- * @param inputCharsetName the name of the requested charset 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 if the encoding is
not supported
+ * @param inputCharsetName the name of the requested charset 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 if the encoding is
not supported.
* @since 1.1
*/
- public static void copy(final InputStream input, final Writer writer,
final String inputCharsetName)
- throws IOException {
+ public static void copy(final InputStream input, final Writer writer,
final String inputCharsetName) throws IOException {
copy(input, writer, Charsets.toCharset(inputCharsetName));
}
@@ -1200,11 +1196,11 @@ public static QueueInputStream copy(final
java.io.ByteArrayOutputStream outputSt
* use the {@link #copyLarge(Reader, Writer)} method.
* </p>
*
- * @param reader the {@link Reader} to read
- * @param output the {@link Appendable} 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
+ * @param reader the {@link Reader} to read.
+ * @param output the {@link Appendable} 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 2.7
*/
public static long copy(final Reader reader, final Appendable output)
throws IOException {
@@ -1218,12 +1214,12 @@ public static long copy(final Reader reader, final
Appendable output) throws IOE
* {@link BufferedReader}.
* </p>
*
- * @param reader the {@link Reader} to read
- * @param output the {@link Appendable} 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
+ * @param reader the {@link Reader} to read.
+ * @param output the {@link Appendable} 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.7
*/
public static long copy(final Reader reader, final Appendable output,
final CharBuffer buffer) throws IOException {
@@ -1238,59 +1234,50 @@ public static long copy(final Reader reader, final
Appendable output, final Char
}
/**
- * Copies chars from a {@link Reader} to bytes on an
- * {@link OutputStream} using the the virtual machine's {@link
Charset#defaultCharset() default charset},
+ * Copies chars from a {@link Reader} to bytes on an {@link OutputStream}
using the the virtual machine's {@link Charset#defaultCharset() default
charset},
* and calling flush.
* <p>
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedReader}.
+ * This method buffers the input internally, so there is no need to use a
{@link BufferedReader}.
* </p>
* <p>
- * Due to the implementation of OutputStreamWriter, this method performs a
- * flush.
+ * Due to the implementation of OutputStreamWriter, this method performs a
flush.
* </p>
* <p>
* This method uses {@link OutputStreamWriter}.
* </p>
*
- * @param reader the {@link Reader} to read
- * @param output the {@link OutputStream} to write to
- * @throws NullPointerException if the input or output is null
- * @throws IOException if an I/O error occurs
+ * @param reader the {@link Reader} to read.
+ * @param output the {@link 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 Use {@link #copy(Reader, OutputStream, Charset)} instead
*/
@Deprecated
- public static void copy(final Reader reader, final OutputStream output)
- throws IOException {
+ public static void copy(final Reader reader, final OutputStream output)
throws IOException {
copy(reader, output, Charset.defaultCharset());
}
/**
- * Copies chars from a {@link Reader} to bytes on an
- * {@link OutputStream} using the specified character encoding, and
- * calling flush.
+ * Copies chars from a {@link Reader} to bytes on an {@link OutputStream}
using the specified character encoding, and calling flush.
* <p>
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedReader}.
+ * This method buffers the input internally, so there is no need to use a
{@link BufferedReader}.
* </p>
* <p>
- * Due to the implementation of OutputStreamWriter, this method performs a
- * flush.
+ * Due to the implementation of OutputStreamWriter, this method performs a
flush.
* </p>
* <p>
* This method uses {@link OutputStreamWriter}.
* </p>
*
- * @param reader the {@link Reader} to read
- * @param output the {@link OutputStream} to write to
- * @param outputCharset the charset 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
+ * @param reader the {@link Reader} to read.
+ * @param output the {@link OutputStream} to write to.
+ * @param outputCharset the charset 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 reader, final OutputStream output,
final Charset outputCharset)
- throws IOException {
+ public static void copy(final Reader reader, final OutputStream output,
final Charset outputCharset) throws IOException {
final OutputStreamWriter writer = new OutputStreamWriter(output,
Charsets.toCharset(outputCharset));
copy(reader, writer);
// XXX Unless anyone is planning on rewriting OutputStreamWriter,
@@ -1299,35 +1286,29 @@ public static void copy(final Reader reader, final
OutputStream output, final Ch
}
/**
- * Copies chars from a {@link Reader} to bytes on an
- * {@link OutputStream} using the specified character encoding, and
- * calling flush.
+ * Copies chars from a {@link Reader} to bytes on an {@link OutputStream}
using the specified character encoding, and calling flush.
* <p>
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedReader}.
+ * This method buffers the input internally, so there is no need to use a
{@link BufferedReader}.
* </p>
* <p>
- * Character encoding names can be found at
- * <a href="http://www.iana.org/assignments/character-sets";>IANA</a>.
+ * Character encoding names can be found at <a
href="http://www.iana.org/assignments/character-sets";>IANA</a>.
* </p>
* <p>
- * Due to the implementation of OutputStreamWriter, this method performs a
- * flush.
+ * Due to the implementation of OutputStreamWriter, this method performs a
flush.
* </p>
* <p>
* This method uses {@link OutputStreamWriter}.
* </p>
*
- * @param reader the {@link Reader} to read
- * @param output the {@link OutputStream} to write to
- * @param outputCharsetName the name of the requested charset 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 if the encoding is
not supported
+ * @param reader the {@link Reader} to read.
+ * @param output the {@link OutputStream} to write to.
+ * @param outputCharsetName the name of the requested charset 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 if the encoding is
not supported.
* @since 1.1
*/
- public static void copy(final Reader reader, final OutputStream output,
final String outputCharsetName)
- throws IOException {
+ public static void copy(final Reader reader, final OutputStream output,
final String outputCharsetName) throws IOException {
copy(reader, output, Charsets.toCharset(outputCharsetName));
}
@@ -1346,9 +1327,9 @@ public static void copy(final Reader reader, final
OutputStream output, final St
*
* @param reader the {@link Reader} to read.
* @param writer the {@link Writer} to write.
- * @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
+ * @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 reader, final Writer writer) throws
IOException {
@@ -1549,9 +1530,9 @@ public static long copyLarge(final InputStream input,
final OutputStream output,
*
* @param reader the {@link Reader} to source.
* @param writer the {@link Writer} to target.
- * @return the number of characters copied
- * @throws NullPointerException if the input or output is null
- * @throws IOException if an I/O error occurs
+ * @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 reader, final Writer writer)
throws IOException {
@@ -1584,53 +1565,44 @@ public static long copyLarge(final Reader reader, final
Writer writer, final cha
}
/**
- * Copies some or all chars from a large (over 2GB) {@link InputStream} to
an
- * {@link OutputStream}, optionally skipping input chars.
+ * Copies some or all chars from a large (over 2GB) {@link InputStream} to
an {@link OutputStream}, optionally skipping input chars.
* <p>
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedReader}.
+ * This method buffers the input internally, so there is no need to use a
{@link BufferedReader}.
* </p>
* <p>
* The buffer size is given by {@link #DEFAULT_BUFFER_SIZE}.
* </p>
*
- * @param reader the {@link Reader} to read
- * @param writer the {@link 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
+ * @param reader the {@link Reader} to read.
+ * @param writer the {@link 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 reader, final Writer writer,
final long inputOffset, final long length)
- throws IOException {
+ public static long copyLarge(final Reader reader, final Writer writer,
final long inputOffset, final long length) throws IOException {
return copyLarge(reader, writer, inputOffset, length,
getScratchCharArray());
}
/**
- * Copies some or all chars from a large (over 2GB) {@link InputStream} to
an
- * {@link OutputStream}, optionally skipping input chars.
+ * Copies some or all chars from a large (over 2GB) {@link InputStream} to
an {@link OutputStream}, optionally skipping input chars.
* <p>
- * This method uses the provided buffer, so there is no need to use a
- * {@link BufferedReader}.
+ * This method uses the provided buffer, so there is no need to use a
{@link BufferedReader}.
* </p>
*
- * @param reader the {@link Reader} to read
- * @param writer the {@link 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
+ * @param reader the {@link Reader} to read.
+ * @param writer the {@link 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 reader, final Writer writer,
final long inputOffset, final long length,
- final char[] buffer)
- throws IOException {
+ public static long copyLarge(final Reader reader, final Writer writer,
final long inputOffset, final long length, final char[] buffer) throws
IOException {
if (inputOffset > 0) {
skipFully(reader, inputOffset);
}
@@ -1715,7 +1687,7 @@ static char[] getScratchCharArrayWriteOnly() {
/**
* Returns the length of the given array in a null-safe manner.
*
- * @param array an array or null
+ * @param array an array or null.
* @return the array length, or 0 if the given array is null.
* @since 2.7
*/
@@ -1726,7 +1698,7 @@ public static int length(final byte[] array) {
/**
* Returns the length of the given array in a null-safe manner.
*
- * @param array an array or null
+ * @param array an array or null.
* @return the array length, or 0 if the given array is null.
* @since 2.7
*/
@@ -1737,7 +1709,7 @@ public static int length(final char[] array) {
/**
* Returns the length of the given CharSequence in a null-safe manner.
*
- * @param csq a CharSequence or null
+ * @param csq a CharSequence or null.
* @return the CharSequence length, or 0 if the given CharSequence is null.
* @since 2.7
*/
@@ -1748,7 +1720,7 @@ public static int length(final CharSequence csq) {
/**
* Returns the length of the given array in a null-safe manner.
*
- * @param array an array or null
+ * @param array an array or null.
* @return the array length, or 0 if the given array is null.
* @since 2.7
*/
@@ -1781,10 +1753,10 @@ public static int length(final Object[] array) {
* }
* </pre>
*
- * @param input the {@link InputStream} to read, not null
- * @param charset the charset to use, null means platform default
- * @return an Iterator of the lines in the reader, never null
- * @throws IllegalArgumentException if the input is null
+ * @param input the {@link InputStream} to read, not null.
+ * @param charset the charset to use, null means platform default.
+ * @return an Iterator of the lines in the reader, never null.
+ * @throws IllegalArgumentException if the input is null.
* @since 2.3
*/
public static LineIterator lineIterator(final InputStream input, final
Charset charset) {
@@ -1816,11 +1788,11 @@ public static LineIterator lineIterator(final
InputStream input, final Charset c
* }
* </pre>
*
- * @param input the {@link InputStream} to read, not null
- * @param charsetName 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 java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
+ * @param input the {@link InputStream} to read, not null.
+ * @param charsetName 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 java.nio.charset.UnsupportedCharsetException if the encoding is
not supported.
* @since 1.2
*/
public static LineIterator lineIterator(final InputStream input, final
String charsetName) {
@@ -1851,9 +1823,9 @@ public static LineIterator lineIterator(final InputStream
input, final String ch
* }
* </pre>
*
- * @param reader the {@link Reader} to read, not null
- * @return an Iterator of the lines in the reader, never null
- * @throws NullPointerException if the reader is null
+ * @param reader the {@link Reader} to read, not null.
+ * @return an Iterator of the lines in the reader, never null.
+ * @throws NullPointerException if the reader is null.
* @since 1.2
*/
public static LineIterator lineIterator(final Reader reader) {
@@ -1866,10 +1838,10 @@ public static LineIterator lineIterator(final Reader
reader) {
* 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
+ * @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 {
@@ -1882,13 +1854,13 @@ public static int read(final InputStream input, final
byte[] buffer) throws IOEx
* as possible before giving up; this may not always be the case for
* subclasses of {@link InputStream}.
*
- * @param input where to read input
- * @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 IllegalArgumentException if length is negative
- * @throws IOException if a read error occurs
+ * @param input where to read input.
+ * @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 IllegalArgumentException if length is negative.
+ * @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)
@@ -1903,13 +1875,13 @@ public static int read(final InputStream input, final
byte[] buffer, final int o
* Reads bytes from an input. This implementation guarantees that it will
read as many bytes as possible before giving up; this may not always be the case
* for subclasses of {@link InputStream}.
*
- * @param input How to read input
- * @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 IllegalArgumentException if length is negative
- * @throws IOException if a read error occurs
+ * @param input How to read input.
+ * @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 IllegalArgumentException if length is negative.
+ * @throws IOException if a read error occurs.
* @since 2.2
*/
static int read(final IOTriFunction<byte[], Integer, Integer, Integer>
input, final byte[] buffer, final int offset, final int length)
@@ -1937,10 +1909,10 @@ static int read(final IOTriFunction<byte[], Integer,
Integer, Integer> input, fi
* subclasses of {@link ReadableByteChannel}.
* </p>
*
- * @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
+ * @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 {
@@ -1960,10 +1932,10 @@ public static int read(final ReadableByteChannel input,
final ByteBuffer buffer)
* as possible before giving up; this may not always be the case for
* subclasses of {@link Reader}.
*
- * @param reader 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
+ * @param reader 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 reader, final char[] buffer) throws
IOException {
@@ -1976,13 +1948,13 @@ public static int read(final Reader reader, final
char[] buffer) throws IOExcept
* as possible before giving up; this may not always be the case for
* subclasses of {@link Reader}.
*
- * @param reader 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 IllegalArgumentException if length is negative
- * @throws IOException if a read error occurs
+ * @param reader 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 IllegalArgumentException if length is negative.
+ * @throws IOException if a read error occurs.
* @since 2.2
*/
public static int read(final Reader reader, final char[] buffer, final int
offset, final int length)
@@ -2009,11 +1981,11 @@ public static int read(final Reader reader, final
char[] buffer, final int offse
* not read as many bytes as requested (most likely because of reaching
EOF).
* </p>
*
- * @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
+ * @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 {
@@ -2027,13 +1999,13 @@ public static void readFully(final InputStream input,
final byte[] buffer) throw
* not read as many bytes as requested (most likely because of reaching
EOF).
* </p>
*
- * @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
+ * @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)
@@ -2051,12 +2023,12 @@ public static void readFully(final InputStream input,
final byte[] buffer, final
* not read as many bytes as requested (most likely because of reaching
EOF).
* </p>
*
- * @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
+ * @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 {
@@ -2072,10 +2044,10 @@ public static byte[] readFully(final InputStream input,
final int length) throws
* not read as many bytes as requested (most likely because of reaching
EOF).
* </p>
*
- * @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
+ * @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 {
@@ -2093,11 +2065,11 @@ public static void readFully(final ReadableByteChannel
input, final ByteBuffer b
* not read as many characters as requested (most likely because of
reaching EOF).
* </p>
*
- * @param reader 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
+ * @param reader 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 reader, final char[] buffer)
throws IOException {
@@ -2111,13 +2083,13 @@ public static void readFully(final Reader reader, final
char[] buffer) throws IO
* not read as many characters as requested (most likely because of
reaching EOF).
* </p>
*
- * @param reader 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
+ * @param reader 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 reader, final char[] buffer,
final int offset, final int length)
@@ -2131,9 +2103,9 @@ public static void readFully(final Reader reader, final
char[] buffer, final int
/**
* Gets the contents of a {@link CharSequence} as a list of Strings, one
entry per line.
*
- * @param csq the {@link CharSequence} to read, not null
- * @return the list of Strings, never null
- * @throws UncheckedIOException if an I/O error occurs
+ * @param csq the {@link CharSequence} to read, not null.
+ * @return the list of Strings, never null.
+ * @throws UncheckedIOException if an I/O error occurs.
* @since 2.18.0
*/
public static List<String> readLines(final CharSequence csq) throws
UncheckedIOException {
@@ -2150,10 +2122,10 @@ public static List<String> readLines(final CharSequence
csq) throws UncheckedIOE
* {@link BufferedInputStream}.
* </p>
*
- * @param input the {@link InputStream} to read, not null
- * @return the list of Strings, never null
- * @throws NullPointerException if the input is null
- * @throws UncheckedIOException if an I/O error occurs
+ * @param input the {@link InputStream} to read, not null.
+ * @return the list of Strings, never null.
+ * @throws NullPointerException if the input is null.
+ * @throws UncheckedIOException if an I/O error occurs.
* @since 1.1
* @deprecated Use {@link #readLines(InputStream, Charset)} instead
*/
@@ -2170,11 +2142,11 @@ public static List<String> readLines(final InputStream
input) throws UncheckedIO
* {@link BufferedInputStream}.
* </p>
*
- * @param input the {@link InputStream} to read, not null
- * @param charset the charset to use, null means platform default
- * @return the list of Strings, never null
- * @throws NullPointerException if the input is null
- * @throws UncheckedIOException if an I/O error occurs
+ * @param input the {@link InputStream} to read, not null.
+ * @param charset the charset to use, null means platform default.
+ * @return the list of Strings, never null.
+ * @throws NullPointerException if the input is null.
+ * @throws UncheckedIOException if an I/O error occurs.
* @since 2.3
*/
public static List<String> readLines(final InputStream input, final
Charset charset) throws UncheckedIOException {
@@ -2193,12 +2165,12 @@ public static List<String> readLines(final InputStream
input, final Charset char
* {@link BufferedInputStream}.
* </p>
*
- * @param input the {@link InputStream} to read, not null
- * @param charsetName the name of the requested charset, null means
platform default
- * @return the list of Strings, never null
- * @throws NullPointerException if the input is
null
- * @throws UncheckedIOException if an I/O error
occurs
- * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
+ * @param input the {@link InputStream} to read, not null.
+ * @param charsetName the name of the requested charset, null means
platform default.
+ * @return the list of Strings, never null.
+ * @throws NullPointerException if the input is
null.
+ * @throws UncheckedIOException if an I/O error
occurs.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported.
* @since 1.1
*/
public static List<String> readLines(final InputStream input, final String
charsetName) throws UncheckedIOException {
@@ -2213,10 +2185,10 @@ public static List<String> readLines(final InputStream
input, final String chars
* {@link BufferedReader}.
* </p>
*
- * @param reader the {@link Reader} to read, not null
- * @return the list of Strings, never null
- * @throws NullPointerException if the input is null
- * @throws UncheckedIOException if an I/O error occurs
+ * @param reader the {@link Reader} to read, not null.
+ * @return the list of Strings, never null.
+ * @throws NullPointerException if the input is null.
+ * @throws UncheckedIOException if an I/O error occurs.
* @since 1.1
*/
@SuppressWarnings("resource") // reader wraps input and is the
responsibility of the caller.
@@ -2231,7 +2203,7 @@ public static List<String> readLines(final Reader reader)
throws UncheckedIOExce
* </p>
*
* @param name The resource name.
- * @return the requested byte array
+ * @return the requested byte array.
* @throws IOException if an I/O error occurs or the resource is not found.
* @see #resourceToByteArray(String, ClassLoader)
* @since 2.6
@@ -2247,8 +2219,8 @@ public static byte[] resourceToByteArray(final String
name) throws IOException {
* </p>
*
* @param name The resource name.
- * @param classLoader the class loader that the resolution of the resource
is delegated to
- * @return the requested byte array
+ * @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 or the resource is not found.
* @see #resourceToURL(String, ClassLoader)
* @since 2.6
@@ -2264,8 +2236,8 @@ public static byte[] resourceToByteArray(final String
name, final ClassLoader cl
* </p>
*
* @param name The resource name.
- * @param charset the charset to use, null means platform default
- * @return the requested String
+ * @param charset the charset to use, null means platform default.
+ * @return the requested String.
* @throws IOException if an I/O error occurs or the resource is not found.
* @see #resourceToString(String, Charset, ClassLoader)
* @since 2.6
@@ -2281,9 +2253,9 @@ public static String resourceToString(final String name,
final Charset charset)
* </p>
*
* @param name The resource name.
- * @param charset the Charset to use, null means platform default
- * @param classLoader the class loader that the resolution of the resource
is delegated to
- * @return the requested String
+ * @param charset the Charset 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.
* @see #resourceToURL(String, ClassLoader)
* @since 2.6
@@ -2315,7 +2287,7 @@ public static URL resourceToURL(final String name) throws
IOException {
* </p>
*
* @param name The resource name.
- * @param classLoader Delegate to this class loader if not null
+ * @param classLoader Delegate to this class loader if not null.
* @return A URL object for reading the resource.
* @throws IOException if the resource is not found.
* @since 2.6
@@ -2342,11 +2314,11 @@ public static URL resourceToURL(final String name,
final ClassLoader classLoader
* this is done to guarantee that the correct number of bytes are skipped.
* </p>
*
- * @param input byte stream to skip
+ * @param input byte stream to skip.
* @param skip 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
+ * @throws IOException if there is a problem reading the file.
+ * @throws IllegalArgumentException if toSkip is negative.
* @see InputStream#skip(long)
* @see <a href="https://issues.apache.org/jira/browse/IO-203";>IO-203 -
Add skipFully() method for InputStreams</a>
* @since 2.0
@@ -2371,12 +2343,12 @@ public static long skip(final InputStream input, final
long skip) throws IOExcep
* skipped.
* </p>
*
- * @param input byte stream to skip
+ * @param input byte stream to skip.
* @param skip number of bytes to skip.
* @param skipBufferSupplier Supplies the buffer to use for reading.
* @return number of bytes actually skipped.
- * @throws IOException if there is a problem reading the file
- * @throws IllegalArgumentException if toSkip is negative
+ * @throws IOException if there is a problem reading the file.
+ * @throws IllegalArgumentException if toSkip is negative.
* @see InputStream#skip(long)
* @see <a href="https://issues.apache.org/jira/browse/IO-203";>IO-203 -
Add skipFully() method for InputStreams</a>
* @since 2.14.0
@@ -2408,11 +2380,11 @@ public static long skip(final InputStream input, final
long skip, final Supplier
* This implementation guarantees that it will read as many bytes
* as possible before giving up.
*
- * @param input ReadableByteChannel to skip
+ * @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
+ * @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 {
@@ -2445,11 +2417,11 @@ public static long skip(final ReadableByteChannel
input, final long toSkip) thro
* this is done to guarantee that the correct number of characters are
skipped.
* </p>
*
- * @param reader character stream to skip
+ * @param reader 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
+ * @throws IOException if there is a problem reading the file.
+ * @throws IllegalArgumentException if toSkip is negative.
* @see Reader#skip(long)
* @see <a href="https://issues.apache.org/jira/browse/IO-203";>IO-203 -
Add skipFully() method for InputStreams</a>
* @since 2.0
@@ -2483,11 +2455,11 @@ public static long skip(final Reader reader, final long
toSkip) throws IOExcepti
* this is done to guarantee that the correct number of characters are
skipped.
* </p>
*
- * @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
+ * @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
*/
@@ -2512,12 +2484,12 @@ public static void skipFully(final InputStream input,
final long toSkip) throws
* skip implementation, this is done to guarantee that the correct number
of characters are skipped.
* </p>
*
- * @param input stream to skip
- * @param toSkip the number of bytes to skip
+ * @param input stream to skip.
+ * @param toSkip the number of bytes to skip.
* @param skipBufferSupplier Supplies the buffer to use for reading.
- * @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
+ * @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.14.0
*/
@@ -2534,11 +2506,11 @@ public static void skipFully(final InputStream input,
final long toSkip, final S
/**
* 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
+ * @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 {
@@ -2563,11 +2535,11 @@ public static void skipFully(final ReadableByteChannel
input, final long toSkip)
* this is done to guarantee that the correct number of characters are
skipped.
* </p>
*
- * @param reader 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
+ * @param reader 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
*/
@@ -2667,21 +2639,20 @@ public static BufferedReader toBufferedReader(final
Reader reader, final int siz
/**
* Gets the contents of an {@link InputStream} as a {@code byte[]}.
* <p>
- * This method buffers the input internally, so there is no need to use a
- * {@link BufferedInputStream}.
+ * This method buffers the input internally, so there is no need to use a
{@link BufferedInputStream}.
* </p>
*
* @param inputStream the {@link InputStream} to read.
* @return the requested byte array.
* @throws NullPointerException if the InputStream is {@code null}.
- * @throws IOException if an I/O error occurs or reading more than {@link
Integer#MAX_VALUE} occurs.
+ * @throws IOException if an I/O error occurs or reading more
than {@link Integer#MAX_VALUE} occurs.
*/
public static byte[] toByteArray(final InputStream inputStream) throws
IOException {
// We use a ThresholdingOutputStream to avoid reading AND writing more
than Integer.MAX_VALUE.
try (UnsynchronizedByteArrayOutputStream ubaOutput =
UnsynchronizedByteArrayOutputStream.builder().get();
- ThresholdingOutputStream thresholdOutput = new
ThresholdingOutputStream(Integer.MAX_VALUE, os -> {
- throw new IllegalArgumentException(String.format("Cannot read
more than %,d into a byte array", Integer.MAX_VALUE));
- }, os -> ubaOutput)) {
+ ThresholdingOutputStream thresholdOutput = new
ThresholdingOutputStream(Integer.MAX_VALUE, os -> {
+ throw new IllegalArgumentException(String.format("Cannot
read more than %,d into a byte array", Integer.MAX_VALUE));
+ }, os -> ubaOutput)) {
copy(inputStream, thresholdOutput);
return ubaOutput.toByteArray();
}
@@ -2711,13 +2682,13 @@ public static byte[] toByteArray(final InputStream
input, final int size) throws
* when {@link InputStream} size is known.
* <strong>NOTE:</strong> the method checks that the length can safely be
cast to an int without truncation
* before using {@link IOUtils#toByteArray(InputStream, int)} to read into
the byte array.
- * (Arrays can have no more than Integer.MAX_VALUE entries anyway)
+ * (Arrays can have no more than Integer.MAX_VALUE entries anyway.)
*
- * @param input the {@link InputStream} to read
+ * @param input the {@link InputStream} to read.
* @param size the size of {@link InputStream} to read, where 0 <
{@code size} <= min(Integer.MAX_VALUE, length of input stream).
- * @return byte [] the requested byte array, of length {@code size}
- * @throws IOException if an I/O error occurs or {@link
InputStream} length is less than {@code size}
- * @throws IllegalArgumentException if size is less than zero or size is
greater than Integer.MAX_VALUE
+ * @return byte [] the requested byte array, of length {@code size}.
+ * @throws IOException if an I/O error occurs or {@link
InputStream} length is less than {@code size}.
+ * @throws IllegalArgumentException if size is less than zero or size is
greater than Integer.MAX_VALUE.
* @see IOUtils#toByteArray(InputStream, int)
* @since 2.1
*/
@@ -2770,11 +2741,11 @@ static byte[] toByteArray(final IOTriFunction<byte[],
Integer, Integer, Integer>
* {@link BufferedReader}.
* </p>
*
- * @param reader the {@link Reader} to read
- * @return the requested byte array
- * @throws NullPointerException if the input is null
- * @throws IOException if an I/O error occurs
- * @deprecated Use {@link #toByteArray(Reader, Charset)} instead
+ * @param reader the {@link Reader} to read.
+ * @return the requested byte array.
+ * @throws NullPointerException if the input is null.
+ * @throws IOException if an I/O error occurs.
+ * @deprecated Use {@link #toByteArray(Reader, Charset)} instead.
*/
@Deprecated
public static byte[] toByteArray(final Reader reader) throws IOException {
@@ -2789,11 +2760,11 @@ public static byte[] toByteArray(final Reader reader)
throws IOException {
* {@link BufferedReader}.
* </p>
*
- * @param reader the {@link Reader} to read
- * @param charset the charset 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
+ * @param reader the {@link Reader} to read.
+ * @param charset the charset 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 reader, final Charset
charset) throws IOException {
@@ -2815,12 +2786,12 @@ public static byte[] toByteArray(final Reader reader,
final Charset charset) thr
* {@link BufferedReader}.
* </p>
*
- * @param reader the {@link Reader} to read
- * @param charsetName the name of the requested charset, 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 if the encoding is
not supported
+ * @param reader the {@link Reader} to read.
+ * @param charsetName the name of the requested charset, 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 if the encoding is
not supported.
* @since 1.1
*/
public static byte[] toByteArray(final Reader reader, final String
charsetName) throws IOException {
@@ -2834,10 +2805,10 @@ public static byte[] toByteArray(final Reader reader,
final String charsetName)
* This is the same as {@link String#getBytes()}.
* </p>
*
- * @param input the {@link String} to convert
- * @return the requested byte array
- * @throws NullPointerException if the input is null
- * @deprecated Use {@link String#getBytes()} instead
+ * @param input the {@link String} to convert.
+ * @return the requested byte array.
+ * @throws NullPointerException if the input is null.
+ * @deprecated Use {@link String#getBytes()} instead.
*/
@Deprecated
public static byte[] toByteArray(final String input) {
@@ -2848,10 +2819,10 @@ public static byte[] toByteArray(final String input) {
/**
* Gets the contents of a {@link URI} as a {@code byte[]}.
*
- * @param uri the {@link URI} to read
- * @return the requested byte array
- * @throws NullPointerException if the uri is null
- * @throws IOException if an I/O exception occurs
+ * @param uri the {@link 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 {
@@ -2861,10 +2832,10 @@ public static byte[] toByteArray(final URI uri) throws
IOException {
/**
* Gets the contents of a {@link URL} as a {@code byte[]}.
*
- * @param url the {@link URL} to read
- * @return the requested byte array
- * @throws NullPointerException if the input is null
- * @throws IOException if an I/O exception occurs
+ * @param url the {@link 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 {
@@ -2896,10 +2867,10 @@ public static byte[] toByteArray(final URLConnection
urlConnection) throws IOExc
* {@link BufferedInputStream}.
* </p>
*
- * @param inputStream the {@link InputStream} to read
- * @return the requested character array
- * @throws NullPointerException if the input is null
- * @throws IOException if an I/O error occurs
+ * @param inputStream the {@link InputStream} to read.
+ * @return the requested character array.
+ * @throws NullPointerException if the input is null.
+ * @throws IOException if an I/O error occurs.
* @since 1.1
* @deprecated Use {@link #toCharArray(InputStream, Charset)} instead
*/
@@ -2916,11 +2887,11 @@ public static char[] toCharArray(final InputStream
inputStream) throws IOExcepti
* {@link BufferedInputStream}.
* </p>
*
- * @param inputStream the {@link InputStream} to read
- * @param charset the charset 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
+ * @param inputStream the {@link InputStream} to read.
+ * @param charset the charset 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 inputStream, final
Charset charset)
@@ -2942,12 +2913,12 @@ public static char[] toCharArray(final InputStream
inputStream, final Charset ch
* {@link BufferedInputStream}.
* </p>
*
- * @param inputStream the {@link InputStream} to read
- * @param charsetName the name of the requested charset, 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 if the encoding is
not supported
+ * @param inputStream the {@link InputStream} to read.
+ * @param charsetName the name of the requested charset, 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 if the encoding is
not supported.
* @since 1.1
*/
public static char[] toCharArray(final InputStream inputStream, final
String charsetName) throws IOException {
@@ -2961,10 +2932,10 @@ public static char[] toCharArray(final InputStream
inputStream, final String cha
* {@link BufferedReader}.
* </p>
*
- * @param reader the {@link Reader} to read
- * @return the requested character array
- * @throws NullPointerException if the input is null
- * @throws IOException if an I/O error occurs
+ * @param reader the {@link Reader} to read.
+ * @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 reader) throws IOException {
@@ -2977,10 +2948,10 @@ public static char[] toCharArray(final Reader reader)
throws IOException {
* Converts the specified CharSequence to an input stream, encoded as bytes
* using the virtual machine's {@link Charset#defaultCharset() default
charset}.
*
- * @param input the CharSequence to convert
- * @return an input stream
+ * @param input the CharSequence to convert.
+ * @return an input stream.
* @since 2.0
- * @deprecated Use {@link #toInputStream(CharSequence, Charset)} instead
+ * @deprecated Use {@link #toInputStream(CharSequence, Charset)} instead.
*/
@Deprecated
public static InputStream toInputStream(final CharSequence input) {
@@ -2991,9 +2962,9 @@ public static InputStream toInputStream(final
CharSequence input) {
* Converts the specified CharSequence to an input stream, encoded as bytes
* using the specified character encoding.
*
- * @param input the CharSequence to convert
- * @param charset the charset to use, null means platform default
- * @return an input stream
+ * @param input the CharSequence to convert.
+ * @param charset the charset to use, null means platform default.
+ * @return an input stream.
* @since 2.3
*/
public static InputStream toInputStream(final CharSequence input, final
Charset charset) {
@@ -3008,10 +2979,10 @@ public static InputStream toInputStream(final
CharSequence input, final Charset
* <a href="http://www.iana.org/assignments/character-sets";>IANA</a>.
* </p>
*
- * @param input the CharSequence to convert
- * @param charsetName the name of the requested charset, null means
platform default
- * @return an input stream
- * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
+ * @param input the CharSequence to convert.
+ * @param charsetName the name of the requested charset, null means
platform default.
+ * @return an input stream.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported.
* @since 2.0
*/
public static InputStream toInputStream(final CharSequence input, final
String charsetName) {
@@ -3022,10 +2993,10 @@ public static InputStream toInputStream(final
CharSequence input, final String c
* Converts the specified string to an input stream, encoded as bytes
* using the virtual machine's {@link Charset#defaultCharset() default
charset}.
*
- * @param input the string to convert
- * @return an input stream
+ * @param input the string to convert.
+ * @return an input stream.
* @since 1.1
- * @deprecated Use {@link #toInputStream(String, Charset)} instead
+ * @deprecated Use {@link #toInputStream(String, Charset)} instead.
*/
@Deprecated
public static InputStream toInputStream(final String input) {
@@ -3036,9 +3007,9 @@ public static InputStream toInputStream(final String
input) {
* Converts the specified string to an input stream, encoded as bytes
* using the specified character encoding.
*
- * @param input the string to convert
- * @param charset the charset to use, null means platform default
- * @return an input stream
+ * @param input the string to convert.
+ * @param charset the charset to use, null means platform default.
+ * @return an input stream.
* @since 2.3
*/
public static InputStream toInputStream(final String input, final Charset
charset) {
@@ -3053,10 +3024,10 @@ public static InputStream toInputStream(final String
input, final Charset charse
* <a href="http://www.iana.org/assignments/character-sets";>IANA</a>.
* </p>
*
- * @param input the string to convert
- * @param charsetName the name of the requested charset, null means
platform default
- * @return an input stream
- * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
+ * @param input the string to convert.
+ * @param charsetName the name of the requested charset, null means
platform default.
+ * @return an input stream.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported.
* @since 1.1
*/
public static InputStream toInputStream(final String input, final String
charsetName) {
@@ -3067,10 +3038,10 @@ public static InputStream toInputStream(final String
input, final String charset
* Gets the contents of a {@code byte[]} as a String
* using the virtual machine's {@link Charset#defaultCharset() default
charset}.
*
- * @param input the byte array to read
- * @return the requested String
- * @throws NullPointerException if the input is null
- * @deprecated Use {@link String#String(byte[])} instead
+ * @param input the byte array to read.
+ * @return the requested String.
+ * @throws NullPointerException if the input is null.
+ * @deprecated Use {@link String#String(byte[])} instead.
*/
@Deprecated
public static String toString(final byte[] input) {
@@ -3086,10 +3057,10 @@ public static String toString(final byte[] input) {
* <a href="http://www.iana.org/assignments/character-sets";>IANA</a>.
* </p>
*
- * @param input the byte array to read
- * @param charsetName the name of the requested charset, null means
platform default
- * @return the requested String
- * @throws NullPointerException if the input is null
+ * @param input the byte array to read.
+ * @param charsetName the name of the requested charset, null means
platform default.
+ * @return the requested String.
+ * @throws NullPointerException if the input is null.
*/
public static String toString(final byte[] input, final String
charsetName) {
return new String(input, Charsets.toCharset(charsetName));
@@ -3103,11 +3074,11 @@ public static String toString(final byte[] input, final
String charsetName) {
* {@link BufferedInputStream}.
* </p>
*
- * @param input the {@link InputStream} to read
- * @return the requested String
- * @throws NullPointerException if the input is null
- * @throws IOException if an I/O error occurs
- * @deprecated Use {@link #toString(InputStream, Charset)} instead
+ * @param input the {@link InputStream} to read.
+ * @return the requested String.
+ * @throws NullPointerException if the input is null.
+ * @throws IOException if an I/O error occurs.
+ * @deprecated Use {@link #toString(InputStream, Charset)} instead.
*/
@Deprecated
public static String toString(final InputStream input) throws IOException {
@@ -3122,11 +3093,11 @@ public static String toString(final InputStream input)
throws IOException {
* {@link BufferedInputStream}.
* </p>
*
- * @param input the {@link InputStream} to read
- * @param charset the charset 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
+ * @param input the {@link InputStream} to read.
+ * @param charset the charset 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
charset) throws IOException {
@@ -3148,12 +3119,12 @@ public static String toString(final InputStream input,
final Charset charset) th
* {@link BufferedInputStream}.
* </p>
*
- * @param input the {@link InputStream} to read
- * @param charsetName the name of the requested charset, 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 if the encoding is
not supported
+ * @param input the {@link InputStream} to read.
+ * @param charsetName the name of the requested charset, 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 if the encoding is
not supported.
*/
public static String toString(final InputStream input, final String
charsetName)
throws IOException {
@@ -3168,11 +3139,11 @@ public static String toString(final InputStream input,
final String charsetName)
* {@link BufferedInputStream}.
* </p>
*
- * @param input supplies the {@link InputStream} to read
- * @param charset the charset 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
+ * @param input supplies the {@link InputStream} to read.
+ * @param charset the charset 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.12.0
*/
public static String toString(final IOSupplier<InputStream> input, final
Charset charset) throws IOException {
@@ -3189,12 +3160,12 @@ public static String toString(final
IOSupplier<InputStream> input, final Charset
* {@link BufferedInputStream}.
* </p>
*
- * @param input supplies the {@link InputStream} to read
- * @param charset the charset to use, null means platform default
+ * @param input supplies the {@link InputStream} to read.
+ * @param charset the charset to use, null means platform default.
* @param defaultString the default return value if the supplier or its
value is null.
- * @return the requested String
- * @throws NullPointerException if the input is null
- * @throws IOException if an I/O error occurs
+ * @return the requested String.
+ * @throws NullPointerException if the input is null.
+ * @throws IOException if an I/O error occurs.
* @since 2.12.0
*/
public static String toString(final IOSupplier<InputStream> input, final
Charset charset, final IOSupplier<String> defaultString) throws IOException {
@@ -3213,10 +3184,10 @@ public static String toString(final
IOSupplier<InputStream> input, final Charset
* {@link BufferedReader}.
* </p>
*
- * @param reader the {@link Reader} to read
- * @return the requested String
- * @throws NullPointerException if the input is null
- * @throws IOException if an I/O error occurs
+ * @param reader the {@link Reader} to read.
+ * @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 reader) throws IOException {
try (StringBuilderWriter sw = new StringBuilderWriter()) {
@@ -3232,7 +3203,7 @@ public static String toString(final Reader reader) throws
IOException {
* @return The contents of the URL as a String.
* @throws IOException if an I/O exception occurs.
* @since 2.1
- * @deprecated Use {@link #toString(URI, Charset)} instead
+ * @deprecated Use {@link #toString(URI, Charset)} instead.
*/
@Deprecated
public static String toString(final URI uri) throws IOException {
@@ -3259,7 +3230,7 @@ public static String toString(final URI uri, final
Charset encoding) throws IOEx
* @param charsetName 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 if the encoding is
not supported
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported.
* @since 2.1
*/
public static String toString(final URI uri, final String charsetName)
throws IOException {
@@ -3273,7 +3244,7 @@ public static String toString(final URI uri, final String
charsetName) throws IO
* @return The contents of the URL as a String.
* @throws IOException if an I/O exception occurs.
* @since 2.1
- * @deprecated Use {@link #toString(URL, Charset)} instead
+ * @deprecated Use {@link #toString(URL, Charset)} instead.
*/
@Deprecated
public static String toString(final URL url) throws IOException {
@@ -3300,7 +3271,7 @@ public static String toString(final URL url, final
Charset encoding) throws IOEx
* @param charsetName 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 if the encoding is
not supported
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported.
* @since 2.1
*/
public static String toString(final URL url, final String charsetName)
throws IOException {
@@ -3310,11 +3281,10 @@ public static String toString(final URL url, final
String charsetName) throws IO
/**
* Writes bytes from a {@code byte[]} to an {@link OutputStream}.
*
- * @param data the byte array to write, do not modify during output,
- * null ignored
- * @param output the {@link OutputStream} to write to
- * @throws NullPointerException if output is null
- * @throws IOException if an I/O error occurs
+ * @param data the byte array to write, do not modify during output,
null ignored.
+ * @param output the {@link 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)
@@ -3333,11 +3303,11 @@ public static void write(final byte[] data, final
OutputStream output)
*
* @param data the byte array to write, do not modify during output,
* null ignored
- * @param writer the {@link Writer} to write to
- * @throws NullPointerException if output is null
- * @throws IOException if an I/O error occurs
+ * @param writer the {@link Writer} to write to.
+ * @throws NullPointerException if output is null.
+ * @throws IOException if an I/O error occurs.
* @since 1.1
- * @deprecated Use {@link #write(byte[], Writer, Charset)} instead
+ * @deprecated Use {@link #write(byte[], Writer, Charset)} instead.
*/
@Deprecated
public static void write(final byte[] data, final Writer writer) throws
IOException {
@@ -3353,10 +3323,10 @@ public static void write(final byte[] data, final
Writer writer) throws IOExcept
*
* @param data the byte array to write, do not modify during output,
* null ignored
- * @param writer the {@link Writer} to write to
- * @param charset the charset to use, null means platform default
- * @throws NullPointerException if output is null
- * @throws IOException if an I/O error occurs
+ * @param writer the {@link Writer} to write to.
+ * @param charset the charset 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 writer, final
Charset charset) throws IOException {
@@ -3366,23 +3336,20 @@ public static void write(final byte[] data, final
Writer writer, final Charset c
}
/**
- * Writes bytes from a {@code byte[]} to chars on a {@link Writer}
- * using the specified character encoding.
+ * Writes bytes from a {@code byte[]} to chars on a {@link Writer} using
the specified character encoding.
* <p>
- * Character encoding names can be found at
- * <a href="http://www.iana.org/assignments/character-sets";>IANA</a>.
+ * Character encoding names can be found at <a
href="http://www.iana.org/assignments/character-sets";>IANA</a>.
* </p>
* <p>
* This method uses {@link String#String(byte[], String)}.
* </p>
*
- * @param data the byte array to write, do not modify during output,
- * null ignored
- * @param writer the {@link Writer} to write to
- * @param charsetName the name of the requested charset, null means
platform default
- * @throws NullPointerException if output is null
- * @throws IOException if an I/O error
occurs
- * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
+ * @param data the byte array to write, do not modify during
output, null ignored.
+ * @param writer the {@link Writer} to write to.
+ * @param charsetName the name of the requested charset, null means
platform default.
+ * @throws NullPointerException if output is null.
+ * @throws IOException if an I/O error
occurs.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported.
* @since 1.1
*/
public static void write(final byte[] data, final Writer writer, final
String charsetName) throws IOException {
@@ -3390,19 +3357,17 @@ public static void write(final byte[] data, final
Writer writer, final String ch
}
/**
- * Writes chars from a {@code char[]} to bytes on an
- * {@link OutputStream}.
+ * Writes chars from a {@code char[]} to bytes on an {@link OutputStream}.
* <p>
* This method uses the virtual machine's {@link Charset#defaultCharset()
default charset}.
* </p>
*
- * @param data the char array to write, do not modify during output,
- * null ignored
- * @param output the {@link OutputStream} to write to
- * @throws NullPointerException if output is null
- * @throws IOException if an I/O error occurs
+ * @param data the char array to write, do not modify during output,
null ignored.
+ * @param output the {@link OutputStream} to write to.
+ * @throws NullPointerException if output is null.
+ * @throws IOException if an I/O error occurs.
* @since 1.1
- * @deprecated Use {@link #write(char[], OutputStream, Charset)} instead
+ * @deprecated Use {@link #write(char[], OutputStream, Charset)} instead.
*/
@Deprecated
public static void write(final char[] data, final OutputStream output)
@@ -3411,19 +3376,16 @@ public static void write(final char[] data, final
OutputStream output)
}
/**
- * Writes chars from a {@code char[]} to bytes on an
- * {@link OutputStream} using the specified character encoding.
+ * Writes chars from a {@code char[]} to bytes on an {@link OutputStream}
using the specified character encoding.
* <p>
- * This method uses {@link String#String(char[])} and
- * {@link String#getBytes(String)}.
+ * This method uses {@link String#String(char[])} and {@link
String#getBytes(String)}.
* </p>
*
- * @param data the char array to write, do not modify during output,
- * null ignored
- * @param output the {@link OutputStream} to write to
- * @param charset the charset to use, null means platform default
- * @throws NullPointerException if output is null
- * @throws IOException if an I/O error occurs
+ * @param data the char array to write, do not modify during output,
null ignored.
+ * @param output the {@link OutputStream} to write to.
+ * @param charset the charset 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 charset) throws IOException {
@@ -3433,24 +3395,20 @@ public static void write(final char[] data, final
OutputStream output, final Cha
}
/**
- * Writes chars from a {@code char[]} to bytes on an
- * {@link OutputStream} using the specified character encoding.
+ * Writes chars from a {@code char[]} to bytes on an {@link OutputStream}
using the specified character encoding.
* <p>
- * Character encoding names can be found at
- * <a href="http://www.iana.org/assignments/character-sets";>IANA</a>.
+ * Character encoding names can be found at <a
href="http://www.iana.org/assignments/character-sets";>IANA</a>.
* </p>
* <p>
- * This method uses {@link String#String(char[])} and
- * {@link String#getBytes(String)}.
+ * This method uses {@link String#String(char[])} and {@link
String#getBytes(String)}.
* </p>
*
- * @param data the char array to write, do not modify during output,
- * null ignored
- * @param output the {@link OutputStream} to write to
- * @param charsetName the name of the requested charset, null means
platform default
- * @throws NullPointerException if output is null
- * @throws IOException if an I/O error
occurs
- * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
+ * @param data the char array to write, do not modify during
output, null ignored.
+ * @param output the {@link OutputStream} to write to.
+ * @param charsetName the name of the requested charset, null means
platform default.
+ * @throws NullPointerException if output is null.
+ * @throws IOException if an I/O error
occurs.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported.
* @since 1.1
*/
public static void write(final char[] data, final OutputStream output,
final String charsetName)
@@ -3461,11 +3419,10 @@ public static void write(final char[] data, final
OutputStream output, final Str
/**
* Writes chars from a {@code char[]} to a {@link Writer}
*
- * @param data the char array to write, do not modify during output,
- * null ignored
- * @param writer the {@link Writer} to write to
- * @throws NullPointerException if output is null
- * @throws IOException if an I/O error occurs
+ * @param data the char array to write, do not modify during output,
null ignored.
+ * @param writer the {@link 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 writer) throws
IOException {
@@ -3475,18 +3432,18 @@ public static void write(final char[] data, final
Writer writer) throws IOExcept
}
/**
- * Writes chars from a {@link CharSequence} to bytes on an
- * {@link OutputStream} using the virtual machine's {@link
Charset#defaultCharset() default charset}.
+ * Writes chars from a {@link CharSequence} to bytes on an {@link
OutputStream} using the virtual machine's {@link Charset#defaultCharset()
default
+ * charset}.
* <p>
* This method uses {@link String#getBytes()}.
* </p>
*
- * @param data the {@link CharSequence} to write, null ignored
- * @param output the {@link OutputStream} to write to
- * @throws NullPointerException if output is null
- * @throws IOException if an I/O error occurs
+ * @param data the {@link CharSequence} to write, null ignored.
+ * @param output the {@link OutputStream} to write to.
+ * @throws NullPointerException if output is null.
+ * @throws IOException if an I/O error occurs.
* @since 2.0
- * @deprecated Use {@link #write(CharSequence, OutputStream, Charset)}
instead
+ * @deprecated Use {@link #write(CharSequence, OutputStream, Charset)}
instead.
*/
@Deprecated
public static void write(final CharSequence data, final OutputStream
output)
@@ -3495,17 +3452,16 @@ public static void write(final CharSequence data, final
OutputStream output)
}
/**
- * Writes chars from a {@link CharSequence} to bytes on an
- * {@link OutputStream} using the specified character encoding.
+ * Writes chars from a {@link CharSequence} to bytes on an {@link
OutputStream} using the specified character encoding.
* <p>
* This method uses {@link String#getBytes(String)}.
* </p>
*
- * @param data the {@link CharSequence} to write, null ignored
- * @param output the {@link OutputStream} to write to
- * @param charset the charset to use, null means platform default
- * @throws NullPointerException if output is null
- * @throws IOException if an I/O error occurs
+ * @param data the {@link CharSequence} to write, null ignored.
+ * @param output the {@link OutputStream} to write to.
+ * @param charset the charset 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 charset)
@@ -3516,22 +3472,20 @@ public static void write(final CharSequence data, final
OutputStream output, fin
}
/**
- * Writes chars from a {@link CharSequence} to bytes on an
- * {@link OutputStream} using the specified character encoding.
+ * Writes chars from a {@link CharSequence} to bytes on an {@link
OutputStream} using the specified character encoding.
* <p>
- * Character encoding names can be found at
- * <a href="http://www.iana.org/assignments/character-sets";>IANA</a>.
+ * Character encoding names can be found at <a
href="http://www.iana.org/assignments/character-sets";>IANA</a>.
* </p>
* <p>
* This method uses {@link String#getBytes(String)}.
* </p>
*
- * @param data the {@link CharSequence} to write, null ignored
- * @param output the {@link OutputStream} to write to
- * @param charsetName the name of the requested charset, null means
platform default
- * @throws NullPointerException if output is null
- * @throws IOException if an I/O error occurs
- * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
+ * @param data the {@link CharSequence} to write, null ignored.
+ * @param output the {@link OutputStream} to write to.
+ * @param charsetName the name of the requested charset, null means
platform default.
+ * @throws NullPointerException if output is null.
+ * @throws IOException if an I/O error
occurs.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported.
* @since 2.0
*/
public static void write(final CharSequence data, final OutputStream
output, final String charsetName)
@@ -3542,10 +3496,10 @@ public static void write(final CharSequence data, final
OutputStream output, fin
/**
* Writes chars from a {@link CharSequence} to a {@link Writer}.
*
- * @param data the {@link CharSequence} to write, null ignored
- * @param writer the {@link Writer} to write to
- * @throws NullPointerException if output is null
- * @throws IOException if an I/O error occurs
+ * @param data the {@link CharSequence} to write, null ignored.
+ * @param writer the {@link 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 writer)
throws IOException {
@@ -3561,10 +3515,10 @@ public static void write(final CharSequence data, final
Writer writer) throws IO
* This method uses {@link String#getBytes()}.
* </p>
*
- * @param data the {@link String} to write, null ignored
- * @param output the {@link OutputStream} to write to
- * @throws NullPointerException if output is null
- * @throws IOException if an I/O error occurs
+ * @param data the {@link String} to write, null ignored.
+ * @param output the {@link OutputStream} to write to.
+ * @throws NullPointerException if output is null.
+ * @throws IOException if an I/O error occurs.
* @since 1.1
* @deprecated Use {@link #write(String, OutputStream, Charset)} instead
*/
@@ -3581,11 +3535,11 @@ public static void write(final String data, final
OutputStream output)
* This method uses {@link String#getBytes(String)}.
* </p>
*
- * @param data the {@link String} to write, null ignored
- * @param output the {@link OutputStream} to write to
- * @param charset the charset to use, null means platform default
- * @throws NullPointerException if output is null
- * @throws IOException if an I/O error occurs
+ * @param data the {@link String} to write, null ignored.
+ * @param output the {@link OutputStream} to write to.
+ * @param charset the charset to use, null means platform default.
+ * @throws NullPointerException if output is null.
+ * @throws IOException if an I/O error occurs.
* @since 2.3
*/
@SuppressWarnings("resource")
@@ -3609,12 +3563,12 @@ public static void write(final String data, final
OutputStream output, final Cha
* This method uses {@link String#getBytes(String)}.
* </p>
*
- * @param data the {@link String} to write, null ignored
- * @param output the {@link OutputStream} to write to
- * @param charsetName the name of the requested charset, null means
platform default
- * @throws NullPointerException if output is null
- * @throws IOException if an I/O error occurs
- * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
+ * @param data the {@link String} to write, null ignored.
+ * @param output the {@link OutputStream} to write to.
+ * @param charsetName the name of the requested charset, null means
platform default.
+ * @throws NullPointerException if output is null.
+ * @throws IOException if an I/O error occurs.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported.
* @since 1.1
*/
public static void write(final String data, final OutputStream output,
final String charsetName)
@@ -3625,10 +3579,10 @@ public static void write(final String data, final
OutputStream output, final Str
/**
* Writes chars from a {@link String} to a {@link Writer}.
*
- * @param data the {@link String} to write, null ignored
- * @param writer the {@link Writer} to write to
- * @throws NullPointerException if output is null
- * @throws IOException if an I/O error occurs
+ * @param data the {@link String} to write, null ignored.
+ * @param writer the {@link 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 writer) throws
IOException {
@@ -3645,12 +3599,12 @@ public static void write(final String data, final
Writer writer) throws IOExcept
* This method uses {@link String#getBytes()}.
* </p>
*
- * @param data the {@link StringBuffer} to write, null ignored
- * @param output the {@link OutputStream} to write to
- * @throws NullPointerException if output is null
+ * @param data the {@link StringBuffer} to write, null ignored.
+ * @param output the {@link OutputStream} to write to.
+ * @throws NullPointerException if output is null.
* @throws IOException if an I/O error occurs
* @since 1.1
- * @deprecated Use {@link #write(CharSequence, OutputStream)}
+ * @deprecated Use {@link #write(CharSequence, OutputStream)}.
*/
@Deprecated
public static void write(final StringBuffer data, final OutputStream
output) //NOSONAR
@@ -3669,12 +3623,12 @@ public static void write(final StringBuffer data, final
OutputStream output) //N
* This method uses {@link String#getBytes(String)}.
* </p>
*
- * @param data the {@link StringBuffer} to write, null ignored
- * @param output the {@link OutputStream} to write to
- * @param charsetName the name of the requested charset, null means
platform default
- * @throws NullPointerException if output is null
- * @throws IOException if an I/O error occurs
- * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
+ * @param data the {@link StringBuffer} to write, null ignored.
+ * @param output the {@link OutputStream} to write to.
+ * @param charsetName the name of the requested charset, null means
platform default.
+ * @throws NullPointerException if output is null.
+ * @throws IOException if an I/O error occurs.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported.
* @since 1.1
* @deprecated Use {@link #write(CharSequence, OutputStream, String)}.
*/
@@ -3689,12 +3643,12 @@ public static void write(final StringBuffer data, final
OutputStream output, fin
/**
* Writes chars from a {@link StringBuffer} to a {@link Writer}.
*
- * @param data the {@link StringBuffer} to write, null ignored
- * @param writer the {@link Writer} to write to
- * @throws NullPointerException if output is null
- * @throws IOException if an I/O error occurs
+ * @param data the {@link StringBuffer} to write, null ignored.
+ * @param writer the {@link Writer} to write to.
+ * @throws NullPointerException if output is null.
+ * @throws IOException if an I/O error occurs.
* @since 1.1
- * @deprecated Use {@link #write(CharSequence, Writer)}
+ * @deprecated Use {@link #write(CharSequence, Writer)}.
*/
@Deprecated
public static void write(final StringBuffer data, final Writer writer)
//NOSONAR
@@ -3710,10 +3664,10 @@ public static void write(final StringBuffer data, final
Writer writer) //NOSONAR
* 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 {@link OutputStream} to write to
- * @throws NullPointerException if output is null
- * @throws IOException if an I/O error occurs
+ * null ignored.
+ * @param output the {@link 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)
@@ -3731,15 +3685,13 @@ public static void writeChunked(final byte[] data,
final OutputStream output)
}
/**
- * Writes chars from a {@code char[]} to a {@link 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.
+ * Writes chars from a {@code char[]} to a {@link 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 writer the {@link Writer} to write to
- * @throws NullPointerException if output is null
- * @throws IOException if an I/O error occurs
+ * @param data the char array to write, do not modify during output,
null ignored.
+ * @param writer the {@link 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 writer)
throws IOException {
@@ -3756,44 +3708,38 @@ public static void writeChunked(final char[] data,
final Writer writer) throws I
}
/**
- * Writes the {@link #toString()} value of each item in a collection to
- * an {@link OutputStream} line by line, using the virtual machine's
{@link Charset#defaultCharset() default charset}
- * and the specified line ending.
+ * Writes the {@link #toString()} value of each item in a collection to an
{@link OutputStream} line by line, using the virtual machine's
+ * {@link Charset#defaultCharset() default charset} 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 {@link OutputStream} to write to, not null, not closed
- * @throws NullPointerException if the output is null
- * @throws IOException if an I/O error occurs
+ * @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 {@link 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 Use {@link #writeLines(Collection, String, OutputStream,
Charset)} instead
*/
@Deprecated
- public static void writeLines(final Collection<?> lines, final String
lineEnding,
- final OutputStream output) throws
IOException {
+ public static void writeLines(final Collection<?> lines, final String
lineEnding, final OutputStream output) throws IOException {
writeLines(lines, lineEnding, output, Charset.defaultCharset());
}
/**
- * Writes the {@link #toString()} value of each item in a collection to
- * an {@link OutputStream} line by line, using the specified character
- * encoding and the specified line ending.
+ * Writes the {@link #toString()} value of each item in a collection to an
{@link OutputStream} line by line, using the specified character encoding and
the
+ * specified line ending.
* <p>
- * UTF-16 is written big-endian with no byte order mark.
- * For little-endian, use UTF-16LE. For a BOM, write it to the stream
- * before calling this method.
+ * UTF-16 is written big-endian with no byte order mark. For
little-endian, use UTF-16LE. For a BOM, write it to the stream before calling
this method.
* </p>
*
- * @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 {@link OutputStream} to write to, not null, not closed
- * @param charset the charset to use, null means platform default
- * @throws NullPointerException if output is null
- * @throws IOException if an I/O error occurs
+ * @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 {@link OutputStream} to write to, not null, not
closed.
+ * @param charset the charset 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 writeLines(final Collection<?> lines, String
lineEnding, final OutputStream output,
- Charset charset) throws IOException {
+ public static void writeLines(final Collection<?> lines, String
lineEnding, final OutputStream output, Charset charset) throws IOException {
if (lines == null) {
return;
}
@@ -3814,41 +3760,36 @@ public static void writeLines(final Collection<?>
lines, String lineEnding, fina
}
/**
- * Writes the {@link #toString()} value of each item in a collection to
- * an {@link OutputStream} line by line, using the specified character
- * encoding and the specified line ending.
+ * Writes the {@link #toString()} value of each item in a collection to an
{@link OutputStream} line by line, using the specified character encoding and
the
+ * specified line ending.
* <p>
- * Character encoding names can be found at
- * <a href="http://www.iana.org/assignments/character-sets";>IANA</a>.
+ * Character encoding names can be found at <a
href="http://www.iana.org/assignments/character-sets";>IANA</a>.
* </p>
*
- * @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 {@link OutputStream} to write to, not null, not closed
- * @param charsetName the name of the requested charset, null means
platform default
- * @throws NullPointerException if the output is
null
- * @throws IOException if an I/O error
occurs
- * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported
+ * @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 {@link OutputStream} to write to, not null, not
closed.
+ * @param charsetName the name of the requested charset, null means
platform default.
+ * @throws NullPointerException if the output is
null.
+ * @throws IOException if an I/O error
occurs.
+ * @throws java.nio.charset.UnsupportedCharsetException if the encoding is
not supported.
* @since 1.1
*/
- public static void writeLines(final Collection<?> lines, final String
lineEnding,
- final OutputStream output, final String
charsetName) throws IOException {
+ public static void writeLines(final Collection<?> lines, final String
lineEnding, final OutputStream output, final String charsetName) throws
IOException {
writeLines(lines, lineEnding, output, Charsets.toCharset(charsetName));
}
/**
- * Writes the {@link #toString()} value of each item in a collection to
- * a {@link Writer} line by line, using the specified line ending.
+ * Writes the {@link #toString()} value of each item in a collection to a
{@link 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 {@link Writer} to write to, not null, not closed
- * @throws NullPointerException if the input is null
- * @throws IOException if an I/O error occurs
+ * @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 {@link 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 {
+ public static void writeLines(final Collection<?> lines, String
lineEnding, final Writer writer) throws IOException {
if (lines == null) {
return;
}
@@ -3867,9 +3808,9 @@ public static void writeLines(final Collection<?> lines,
String lineEnding,
* Returns the given Appendable if it is already a {@link Writer},
otherwise creates a Writer wrapper around the
* given Appendable.
*
- * @param appendable the Appendable to wrap or return (not null)
- * @return the given Appendable or a Writer wrapper around the given
Appendable
- * @throws NullPointerException if the input parameter is null
+ * @param appendable the Appendable to wrap or return (not null).
+ * @return the given Appendable or a Writer wrapper around the given
Appendable.
+ * @throws NullPointerException if the input parameter is null.
* @since 2.7
*/
public static Writer writer(final Appendable appendable) {
