com.google.gdata.util.common.io
Class Characters

java.lang.Object
  com.google.gdata.util.common.io.Characters

public final class Characters
extends java.lang.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.

Method Summary

static <R extends java.lang.Readable & java.io.Closeable> long	copy(InputSupplier<R> from, java.lang.Appendable to) Opens a Readable object from the supplier, copies all characters to the Appendable object, and closes the input.
static <R extends java.lang.Readable & java.io.Closeable,W extends java.lang.Appendable & java.io.Closeable> long	copy(InputSupplier<R> from, OutputSupplier<W> to) Opens Readable and Appendable objects from the given factories, copies all characters between the two, and closes them.
static long	copy(java.lang.Readable from, java.lang.Appendable to) Copies all characters between the Readable and Appendable objects.
static InputSupplier<java.io.Reader>	join(InputSupplier<? extends java.io.Reader>... suppliers) Varargs form of join(Iterable).
static InputSupplier<java.io.Reader>	join(java.lang.Iterable<? extends InputSupplier<? extends java.io.Reader>> suppliers) Joins multiple Reader suppliers into a single supplier.
static InputSupplier<java.io.InputStreamReader>	newReaderSupplier(InputSupplier<? extends java.io.InputStream> in, java.nio.charset.Charset charset) Returns a factory that will supply instances of InputStreamReader, using the given InputStream factory and character set.
static InputSupplier<java.io.StringReader>	newReaderSupplier(java.lang.String value) Returns a factory that will supply instances of StringReader that read a string value.
static OutputSupplier<java.io.OutputStreamWriter>	newWriterSupplier(OutputSupplier<? extends java.io.OutputStream> out, java.nio.charset.Charset charset) Returns a factory that will supply instances of OutputStreamWriter, using the given OutputStream factory and character set.
static <R extends java.lang.Readable & java.io.Closeable> java.lang.String	readFirstLine(InputSupplier<R> supplier) Reads the first line from a Readable & Closeable object supplied by a factory.
static <R extends java.lang.Readable & java.io.Closeable> java.util.List<java.lang.String>	readLines(InputSupplier<R> supplier) Reads all of the lines from a Readable & Closeable object supplied by a factory.
static java.util.List<java.lang.String>	readLines(java.lang.Readable r) Reads all of the lines from a Readable object.
static void	skipFully(java.io.Reader reader, long n) Discards n characters of data from the reader.
static <R extends java.lang.Readable & java.io.Closeable> java.lang.String	toString(InputSupplier<R> supplier) Returns the characters from a Readable & Closeable object supplied by a factory as a String.
static java.lang.String	toString(java.lang.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 Detail

newReaderSupplier

public static InputSupplier<java.io.StringReader> newReaderSupplier(java.lang.String value)

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

Parameters:

value - the string to read

Returns:

the factory

newReaderSupplier

public static InputSupplier<java.io.InputStreamReader> newReaderSupplier(InputSupplier<? extends java.io.InputStream> in,
                                                                         java.nio.charset.Charset charset)

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 character set used to decode the input stream

Returns:

the factory

newWriterSupplier

public static OutputSupplier<java.io.OutputStreamWriter> newWriterSupplier(OutputSupplier<? extends java.io.OutputStream> out,
                                                                           java.nio.charset.Charset charset)

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 character set used to encode the output stream

Returns:

the factory

copy

public static <R extends java.lang.Readable & java.io.Closeable,W extends java.lang.Appendable & java.io.Closeable> long copy(InputSupplier<R> from,
                                                                                                                            OutputSupplier<W> to)
                 throws java.io.IOException

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:

java.io.IOException - if an I/O error occurs

copy

public static <R extends java.lang.Readable & java.io.Closeable> long copy(InputSupplier<R> from,
                                                                          java.lang.Appendable to)
                 throws java.io.IOException

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:

java.io.IOException - if an I/O error occurs

copy

public static long copy(java.lang.Readable from,
                        java.lang.Appendable to)
                 throws java.io.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:

java.io.IOException - if an I/O error occurs

toString

public static java.lang.String toString(java.lang.Readable r)
                                 throws java.io.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:

java.io.IOException - if an I/O error occurs

toString

public static <R extends java.lang.Readable & java.io.Closeable> java.lang.String toString(InputSupplier<R> supplier)
                                 throws java.io.IOException

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:

java.io.IOException - if an I/O error occurs

readFirstLine

public static <R extends java.lang.Readable & java.io.Closeable> java.lang.String readFirstLine(InputSupplier<R> supplier)
                                      throws java.io.IOException

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:

java.io.IOException - if an I/O error occurs

readLines

public static <R extends java.lang.Readable & java.io.Closeable> java.util.List<java.lang.String> readLines(InputSupplier<R> supplier)
                                                  throws java.io.IOException

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:

java.io.IOException - if an I/O error occurs

readLines

public static java.util.List<java.lang.String> readLines(java.lang.Readable r)
                                                  throws java.io.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 and Resources#readLines methods.

Parameters:

r - the object to read from

Returns:

a mutable List containing all the lines

Throws:

java.io.IOException - if an I/O error occurs

join

public static InputSupplier<java.io.Reader> join(java.lang.Iterable<? extends InputSupplier<? extends java.io.Reader>> suppliers)

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

public static InputSupplier<java.io.Reader> join(InputSupplier<? extends java.io.Reader>... suppliers)

Varargs form of join(Iterable).

skipFully

public static void skipFully(java.io.Reader reader,
                             long n)
                      throws java.io.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:

java.io.EOFException - if this stream reaches the end before skipping all the bytes

java.io.IOException - if an I/O error occurs