@GwtIncompatible public abstract class CharSource extends Object
Reader
, a CharSource
is not an open, stateful stream of characters that can be read and closed. Instead,
it is an immutable supplier of Reader
instances.
CharSource
provides two kinds of methods:
Several methods in this class, such as readLines()
, break the contents of the source
into lines. Like BufferedReader
, these methods break lines on any of \n
, \r
or \r\n
, do not include the line separator in each line and do not consider there to
be an empty line at the end if the contents are terminated with a line separator.
Any ByteSource
containing text encoded with a specific character
encoding may be viewed as a CharSource
using ByteSource.asCharSource(Charset)
.
Modifier | Constructor and Description |
---|---|
protected |
CharSource()
Constructor for use by subclasses.
|
Modifier and Type | Method and Description |
---|---|
ByteSource |
asByteSource(Charset charset)
Returns a
ByteSource view of this char source that encodes chars read from this source
as bytes using the given Charset . |
static CharSource |
concat(CharSource... sources)
Concatenates multiple
CharSource instances into a single source. |
static CharSource |
concat(Iterable<? extends CharSource> sources)
Concatenates multiple
CharSource instances into a single source. |
static CharSource |
concat(Iterator<? extends CharSource> sources)
Concatenates multiple
CharSource instances into a single source. |
long |
copyTo(Appendable appendable)
Appends the contents of this source to the given
Appendable (such as a Writer ). |
long |
copyTo(CharSink sink)
Copies the contents of this source to the given sink.
|
static CharSource |
empty()
Returns an immutable
CharSource that contains no characters. |
void |
forEachLine(Consumer<? super String> action)
Reads all lines of text from this source, running the given
action for each line as it
is read. |
boolean |
isEmpty()
Returns whether the source has zero chars.
|
long |
length()
Returns the length of this source in chars, even if doing so requires opening and traversing an
entire stream.
|
Optional<Long> |
lengthIfKnown()
Returns the size of this source in chars, if the size can be easily determined without actually
opening the data stream.
|
Stream<String> |
lines()
Opens a new
Stream for reading text one line at a time from this source. |
BufferedReader |
openBufferedStream()
Opens a new
BufferedReader for reading from this source. |
abstract Reader |
openStream()
Opens a new
Reader for reading from this source. |
String |
read()
Reads the contents of this source as a string.
|
@Nullable String |
readFirstLine()
Reads the first line of this source as a string.
|
ImmutableList<String> |
readLines()
Reads all the lines of this source as a list of strings.
|
<T> T |
readLines(LineProcessor<T> processor)
Reads lines of text from this source, processing each line as it is read using the given
processor . |
static CharSource |
wrap(CharSequence charSequence)
Returns a view of the given character sequence as a
CharSource . |
protected CharSource()
@Beta public ByteSource asByteSource(Charset charset)
ByteSource
view of this char source that encodes chars read from this source
as bytes using the given Charset
.
If ByteSource.asCharSource(java.nio.charset.Charset)
is called on the returned source with the same charset,
the default implementation of this method will ensure that the original CharSource
is
returned, rather than round-trip encoding. Subclasses that override this method should behave
the same way.
public abstract Reader openStream() throws IOException
Reader
for reading from this source. This method returns a new, independent
reader each time it is called.
The caller is responsible for ensuring that the returned reader is closed.
IOException
- if an I/O error occurs while opening the readerpublic BufferedReader openBufferedStream() throws IOException
BufferedReader
for reading from this source. This method returns a new,
independent reader each time it is called.
The caller is responsible for ensuring that the returned reader is closed.
IOException
- if an I/O error occurs while of opening the reader@Beta @MustBeClosed public Stream<String> lines() throws IOException
Stream
for reading text one line at a time from this source. This method
returns a new, independent stream each time it is called.
The returned stream is lazy and only reads from the source in the terminal operation. If an
I/O error occurs while the stream is reading from the source or when the stream is closed, an
UncheckedIOException
is thrown.
Like BufferedReader.readLine()
, this method considers a line to be a sequence of
text that is terminated by (but does not include) one of \r\n
, \r
or \n
. If the source's content does not end in a line termination sequence, it is treated as if
it does.
The caller is responsible for ensuring that the returned stream is closed. For example:
try (Stream<String> lines = source.lines()) {
lines.map(...)
.filter(...)
.forEach(...);
}
IOException
- if an I/O error occurs while opening the stream@Beta public Optional<Long> lengthIfKnown()
The default implementation returns Optional.absent()
. Some sources, such as a CharSequence
, may return a non-absent value. Note that in such cases, it is possible
that this method will return a different number of chars than would be returned by reading all
of the chars.
Additionally, for mutable sources such as StringBuilder
s, a subsequent read may
return a different number of chars if the contents are changed.
@Beta public long length() throws IOException
lengthIfKnown()
.
The default implementation calls lengthIfKnown()
and returns the value if present. If
absent, it will fall back to a heavyweight operation that will open a stream, skip
to the end of the stream, and return the total number of chars that
were skipped.
Note that for sources that implement lengthIfKnown()
to provide a more efficient
implementation, it is possible that this method will return a different number of chars
than would be returned by reading all of the chars.
In either case, for mutable sources such as files, a subsequent read may return a different number of chars if the contents are changed.
IOException
- if an I/O error occurs while reading the length of this source@CanIgnoreReturnValue public long copyTo(Appendable appendable) throws IOException
Appendable
(such as a Writer
).
Does not close appendable
if it is Closeable
.IOException
- if an I/O error occurs while reading from this source or writing to appendable
@CanIgnoreReturnValue public long copyTo(CharSink sink) throws IOException
IOException
- if an I/O error occurs while reading from this source or writing to sink
public String read() throws IOException
IOException
- if an I/O error occurs while reading from this sourcepublic @Nullable String readFirstLine() throws IOException
null
if this source is empty.
Like BufferedReader.readLine()
, this method considers a line to be a sequence of
text that is terminated by (but does not include) one of \r\n
, \r
or \n
. If the source's content does not end in a line termination sequence, it is treated as if
it does.
IOException
- if an I/O error occurs while reading from this sourcepublic ImmutableList<String> readLines() throws IOException
Like BufferedReader.readLine()
, this method considers a line to be a sequence of
text that is terminated by (but does not include) one of \r\n
, \r
or \n
. If the source's content does not end in a line termination sequence, it is treated as if
it does.
IOException
- if an I/O error occurs while reading from this source@Beta @CanIgnoreReturnValue public <T> T readLines(LineProcessor<T> processor) throws IOException
processor
. Stops when all lines have been processed or the processor returns
false
and returns the result produced by the processor.
Like BufferedReader.readLine()
, this method considers a line to be a sequence of
text that is terminated by (but does not include) one of \r\n
, \r
or \n
. If the source's content does not end in a line termination sequence, it is treated as if
it does.
IOException
- if an I/O error occurs while reading from this source or if processor
throws an IOException
@Beta public void forEachLine(Consumer<? super String> action) throws IOException
action
for each line as it
is read.
Like BufferedReader.readLine()
, this method considers a line to be a sequence of
text that is terminated by (but does not include) one of \r\n
, \r
or \n
. If the source's content does not end in a line termination sequence, it is treated as if
it does.
IOException
- if an I/O error occurs while reading from this source or if action
throws an UncheckedIOException
public boolean isEmpty() throws IOException
lengthIfKnown()
, returning true if it's known to be zero and false if it's known to be
non-zero. If the length is not known, it falls back to opening a stream and checking for EOF.
Note that, in cases where lengthIfKnown
returns zero, it is possible that
chars are actually available for reading. This means that a source may return true
from
isEmpty()
despite having readable content.
IOException
- if an I/O error occurspublic static CharSource concat(Iterable<? extends CharSource> sources)
CharSource
instances into a single source. Streams returned from
the source will contain the concatenated data from the streams of the underlying sources.
Only one underlying stream will be open at a time. Closing the concatenated stream will close the open underlying stream.
sources
- the sources to concatenateCharSource
containing the concatenated datapublic static CharSource concat(Iterator<? extends CharSource> sources)
CharSource
instances into a single source. Streams returned from
the source will contain the concatenated data from the streams of the underlying sources.
Only one underlying stream will be open at a time. Closing the concatenated stream will close the open underlying stream.
Note: The input Iterator
will be copied to an ImmutableList
when this method
is called. This will fail if the iterator is infinite and may cause problems if the iterator
eagerly fetches data for each source when iterated (rather than producing sources that only
load data through their streams). Prefer using the concat(Iterable)
overload if
possible.
sources
- the sources to concatenateCharSource
containing the concatenated dataNullPointerException
- if any of sources
is null
public static CharSource concat(CharSource... sources)
CharSource
instances into a single source. Streams returned from
the source will contain the concatenated data from the streams of the underlying sources.
Only one underlying stream will be open at a time. Closing the concatenated stream will close the open underlying stream.
sources
- the sources to concatenateCharSource
containing the concatenated dataNullPointerException
- if any of sources
is null
public static CharSource wrap(CharSequence charSequence)
CharSource
. The behavior of the
returned CharSource
and any Reader
instances created by it is unspecified if
the charSequence
is mutated while it is being read, so don't do that.CharStreams.asCharSource(String)
)public static CharSource empty()
CharSource
that contains no characters.Copyright © 2010–2019. All rights reserved.