com.google.common.io

Class CharStreams

java.lang.Object

com.google.common.io.CharStreams

@Beta
public final class CharStreams
extends Object

Provides utility methods for working with character streams.

All method parameters must be non-null unless documented otherwise.

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

Methods

Modifier and Type	Method and Description
static CharSink	asCharSink(OutputSupplier<? extends Appendable> supplier) Deprecated. Convert all OutputSupplier<? extends Appendable> implementations to extend CharSink or provide a method for viewing the object as a CharSink. This method is scheduled for removal in Guava 18.0.
static CharSource	asCharSource(InputSupplier<? extends Readable> supplier) Deprecated. Convert all InputSupplier<? extends Readable> implementations to extend CharSource or provide a method for viewing the object as a CharSource. This method is scheduled for removal in Guava 18.0.
static Writer	asWriter(Appendable target) Returns a Writer that sends all output to the given Appendable target.
static <R extends Readable & Closeable> long	copy(InputSupplier<R> from, Appendable to) Deprecated. Use CharSource.copyTo(Appendable) instead. This method is scheduled for removal in Guava 18.0.
static <R extends Readable & Closeable,W extends Appendable & Closeable> long	copy(InputSupplier<R> from, OutputSupplier<W> to) Deprecated. Use {@link CharSource#copyTo(CharSink) instead. This method is scheduled for removal in Guava 18.0.
static long	copy(Readable from, Appendable to) Copies all characters between the Readable and Appendable objects.
static InputSupplier<Reader>	join(InputSupplier<? extends Reader>... suppliers) Deprecated. Use CharSource.concat(CharSource[]) instead. This method is scheduled for removal in Guava 18.0.
static InputSupplier<Reader>	join(Iterable<? extends InputSupplier<? extends Reader>> suppliers) Deprecated. Use CharSource.concat(Iterable) instead. This method is scheduled for removal in Guava 18.0.
static InputSupplier<InputStreamReader>	newReaderSupplier(InputSupplier<? extends InputStream> in, Charset charset) Deprecated. Use ByteSource.asCharSource(Charset) instead. This method is scheduled for removal in Guava 18.0.
static InputSupplier<StringReader>	newReaderSupplier(String value) Deprecated. Use CharSource#wrap(CharSequence} instead. This method is scheduled for removal in Guava 18.0.
static OutputSupplier<OutputStreamWriter>	newWriterSupplier(OutputSupplier<? extends OutputStream> out, Charset charset) Deprecated. Use ByteSink.asCharSink(Charset) instead. This method is scheduled for removal in Guava 18.0.
static Writer	nullWriter() Returns a Writer that simply discards written chars.
static <R extends Readable & Closeable> String	readFirstLine(InputSupplier<R> supplier) Deprecated. Use CharSource.readFirstLine() instead. This method is scheduled for removal in Guava 18.0.
static <R extends Readable & Closeable> List<String>	readLines(InputSupplier<R> supplier) Deprecated. Use CharSource.readLines() instead, but note that it returns an ImmutableList. This method is scheduled for removal in Guava 18.0.
static <R extends Readable & Closeable,T> T	readLines(InputSupplier<R> supplier, LineProcessor<T> callback) Deprecated. Use CharSource.readLines(LineProcessor) instead. This method is scheduled for removal in Guava 18.0.
static List<String>	readLines(Readable r) Reads all of the lines from a Readable object.
static <T> 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 <R extends Readable & Closeable> String	toString(InputSupplier<R> supplier) Deprecated. Use CharSource.read() instead. This method is scheduled for removal in Guava 18.0.
static String	toString(Readable r) Reads all characters from a Readable object into a String.
static <W extends Appendable & Closeable> void	write(CharSequence from, OutputSupplier<W> to) Deprecated. Use CharSink.write(CharSequence) instead. This method is scheduled for removal in Guava 18.0.

Methods inherited from class java.lang.Object

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

Method Detail

newReaderSupplier

@Deprecated
public static InputSupplier<StringReader> newReaderSupplier(String value)

Deprecated. Use CharSource#wrap(CharSequence} instead. This method is scheduled for removal in Guava 18.0.

Returns a factory that will supply instances of StringReader that read a string value.

Parameters:

value - the string to read

Returns:

the factory

newReaderSupplier

@Deprecated
public static InputSupplier<InputStreamReader> newReaderSupplier(InputSupplier<? extends InputStream> in,
                                                            Charset charset)

Deprecated. Use ByteSource.asCharSource(Charset) instead. This method is scheduled for removal in Guava 18.0.

Returns a factory that will supply instances of InputStreamReader, using the given InputStream factory and character set.

Parameters:

in - the factory that will be used to open input streams

charset - the charset used to decode the input stream; see Charsets for helpful predefined constants

Returns:

the factory

newWriterSupplier

@Deprecated
public static OutputSupplier<OutputStreamWriter> newWriterSupplier(OutputSupplier<? extends OutputStream> out,
                                                              Charset charset)

Deprecated. Use ByteSink.asCharSink(Charset) instead. This method is scheduled for removal in Guava 18.0.

Returns a factory that will supply instances of OutputStreamWriter, using the given OutputStream factory and character set.

Parameters:

out - the factory that will be used to open output streams

charset - the charset used to encode the output stream; see Charsets for helpful predefined constants

Returns:

the factory

write

@Deprecated
public static <W extends Appendable & Closeable> void write(CharSequence from,
                                                      OutputSupplier<W> to)
                  throws IOException

Deprecated. Use CharSink.write(CharSequence) instead. This method is scheduled for removal in Guava 18.0.

Writes a character sequence (such as a string) to an appendable object from the given supplier.

Parameters:

from - the character sequence to write

to - the output supplier

Throws:

IOException - if an I/O error occurs

copy

@Deprecated
public static <R extends Readable & Closeable,W extends Appendable & Closeable> long copy(InputSupplier<R> from,
                                                                                   OutputSupplier<W> to)
                 throws IOException

Deprecated. Use {@link CharSource#copyTo(CharSink) instead. This method is scheduled for removal in Guava 18.0.

Opens Readable and Appendable objects from the given factories, copies all characters between the two, and closes them.

Parameters:

from - the input factory

to - the output factory

Returns:

the number of characters copied

Throws:

IOException - if an I/O error occurs

copy

@Deprecated
public static <R extends Readable & Closeable> long copy(InputSupplier<R> from,
                                                   Appendable to)
                 throws IOException

Deprecated. Use CharSource.copyTo(Appendable) instead. This method is scheduled for removal in Guava 18.0.

Opens a Readable object from the supplier, copies all characters to the Appendable object, and closes the input. Does not close or flush the output.

Parameters:

from - the input factory

to - the object to write to

Returns:

the number of characters copied

Throws:

IOException - if an I/O error occurs

copy

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

toString

@Deprecated
public static <R extends Readable & Closeable> String toString(InputSupplier<R> supplier)
                       throws IOException

Deprecated. Use CharSource.read() instead. This method is scheduled for removal in Guava 18.0.

Returns the characters from a Readable & Closeable object supplied by a factory as a String.

Parameters:

supplier - the factory to read from

Returns:

a string containing all the characters

Throws:

IOException - if an I/O error occurs

readFirstLine

@Deprecated
public static <R extends Readable & Closeable> String readFirstLine(InputSupplier<R> supplier)
                            throws IOException

Deprecated. Use CharSource.readFirstLine() instead. This method is scheduled for removal in Guava 18.0.

Reads the first line from a Readable & Closeable object supplied by a factory. The line does not include line-termination characters, but does include other leading and trailing whitespace.

Parameters:

supplier - the factory to read from

Returns:

the first line, or null if the reader is empty

Throws:

IOException - if an I/O error occurs

readLines

@Deprecated
public static <R extends Readable & Closeable> List<String> readLines(InputSupplier<R> supplier)
                              throws IOException

Deprecated. Use CharSource.readLines() instead, but note that it returns an ImmutableList. This method is scheduled for removal in Guava 18.0.

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

Parameters:

supplier - the factory to read from

Returns:

a mutable List containing all the lines

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

public static <T> 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

readLines

@Deprecated
public static <R extends Readable & Closeable,T> T readLines(InputSupplier<R> supplier,
                                                       LineProcessor<T> callback)
                   throws IOException

Deprecated. Use CharSource.readLines(LineProcessor) instead. This method is scheduled for removal in Guava 18.0.

Streams lines from a Readable and Closeable object supplied by a factory, stopping when our callback returns false, or we have read all of the lines.

Parameters:

supplier - the factory to read from

callback - the LineProcessor to use to handle the lines

Returns:

the output of processing the lines

Throws:

IOException - if an I/O error occurs

join

@Deprecated
public static InputSupplier<Reader> join(Iterable<? extends InputSupplier<? extends Reader>> suppliers)

Deprecated. Use CharSource.concat(Iterable) instead. This method is scheduled for removal in Guava 18.0.

Joins multiple Reader suppliers into a single supplier. Reader returned from the supplier will contain the concatenated data from the readers of the underlying suppliers.

Reading from the joined reader will throw a NullPointerException if any of the suppliers are null or return null.

Only one underlying reader will be open at a time. Closing the joined reader will close the open underlying reader.

Parameters:

suppliers - the suppliers to concatenate

Returns:

a supplier that will return a reader containing the concatenated data

join

@Deprecated
public static InputSupplier<Reader> join(InputSupplier<? extends Reader>... suppliers)

Deprecated. Use CharSource.concat(CharSource[]) instead. This method is scheduled for removal in Guava 18.0.

Varargs form of join(Iterable).

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.

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

asCharSource

@Deprecated
public static CharSource asCharSource(InputSupplier<? extends Readable> supplier)

Deprecated. Convert all InputSupplier<? extends Readable> implementations to extend CharSource or provide a method for viewing the object as a CharSource. This method is scheduled for removal in Guava 18.0.

Returns a view of the given Readable supplier as a CharSource.

This method is a temporary method provided for easing migration from suppliers to sources and sinks.

Since:

15.0

asCharSink

@Deprecated
public static CharSink asCharSink(OutputSupplier<? extends Appendable> supplier)

Deprecated. Convert all OutputSupplier<? extends Appendable> implementations to extend CharSink or provide a method for viewing the object as a CharSink. This method is scheduled for removal in Guava 18.0.

Returns a view of the given Appendable supplier as a CharSink.

This method is a temporary method provided for easing migration from suppliers to sources and sinks.

Since:

15.0