Class CharStreams

java.lang.Object

com.google.common.io.CharStreams

@GwtIncompatible
public final class CharStreams
extends Object

Provides utility methods for working with character streams.

Some of the methods in this class take arguments with a generic type of Readable & Closeable. A Reader implements both of those interfaces. Similarly for Appendable & Closeable and Writer.

Since:

1.0

Author:

Chris Nokleberg, Bin Zhu, Colin Decker

Method Summary

Modifier and Type	Method	Description
static Writer	asWriter(Appendable target)	Returns a Writer that sends all output to the given Appendable target.
static long	copy(Readable from, Appendable to)	Copies all characters between the Readable and Appendable objects.
static long	exhaust(Readable readable)	Reads and discards data from the given Readable until the end of the stream is reached.
static Writer	nullWriter()	Returns a Writer that simply discards written chars.
static List<String>	readLines(Readable r)	Reads all of the lines from a Readable object.
static <T extends @Nullable Object> T	readLines(Readable readable, LineProcessor<T> processor)	Streams lines from a Readable object, stopping when the processor returns false or all lines have been read and returning the result produced by the processor.
static void	skipFully(Reader reader, long n)	Discards n characters of data from the reader.
static String	toString(Readable r)	Reads all characters from a Readable object into a String.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

copy

@CanIgnoreReturnValue
public static long copy(Readable from,
 Appendable to)
                 throws IOException

Copies all characters between the Readable and Appendable objects. Does not close or flush either object.

Parameters:

from - the object to read from

to - the object to write to

Returns:

the number of characters copied

Throws:

IOException - if an I/O error occurs

toString

public static String toString(Readable r)
                       throws IOException

Reads all characters from a Readable object into a String. Does not close the Readable.

Parameters:

r - the object to read from

Returns:

a string containing all the characters

Throws:

IOException - if an I/O error occurs

readLines

public static List<String> readLines(Readable r)
                              throws IOException

Reads all of the lines from a Readable object. The lines do not include line-termination characters, but do include other leading and trailing whitespace.

Does not close the Readable. If reading files or resources you should use the Files.readLines(java.io.File, java.nio.charset.Charset) and Resources.readLines(java.net.URL, java.nio.charset.Charset, com.google.common.io.LineProcessor<T>) methods.

Parameters:

r - the object to read from

Returns:

a mutable List containing all the lines

Throws:

IOException - if an I/O error occurs

readLines

@CanIgnoreReturnValue
public static <T extends @Nullable Object> T readLines(Readable readable,
 LineProcessor<T> processor)
                                                throws IOException

Streams lines from a Readable object, stopping when the processor returns false or all lines have been read and returning the result produced by the processor. Does not close readable. Note that this method may not fully consume the contents of readable if the processor stops processing early.

Throws:

IOException - if an I/O error occurs

Since:

14.0

exhaust

@CanIgnoreReturnValue
public static long exhaust(Readable readable)
                    throws IOException

Reads and discards data from the given Readable until the end of the stream is reached. Returns the total number of chars read. Does not close the stream.

Throws:

IOException

Since:

20.0

skipFully

public static void skipFully(Reader reader,
 long n)
                      throws IOException

Discards n characters of data from the reader. This method will block until the full amount has been skipped. Does not close the reader.

Parameters:

reader - the reader to read from

n - the number of characters to skip

Throws:

EOFException - if this stream reaches the end before skipping all the characters

IOException - if an I/O error occurs

nullWriter

public static Writer nullWriter()

Returns a Writer that simply discards written chars.

Java 11+ users: use Writer.nullWriter() instead. Note that the CharStreams method returns a singleton writer whose close method has no effect, while the Writer.nullWriter() method returns a new instance whose methods throw after the instance is closed.

Since:

15.0

asWriter

public static Writer asWriter(Appendable target)

Returns a Writer that sends all output to the given Appendable target. Closing the writer will close the target if it is Closeable, and flushing the writer will flush the target if it is Flushable.

Parameters:

target - the object to which output will be sent

Returns:

a new Writer object, unless target is a Writer, in which case the target is returned