- com.google.common.io.CharSource

```
@GwtIncompatible
public abstract class CharSource
extends 
```
A readable source of characters, such as a text file. Unlike a , 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:
- Methods that return a reader: These methods should return a new, independent instance each time they are called. The caller is responsible for ensuring that the returned reader is closed.
- Convenience methods: These are implementations of common operations that are typically implemented by opening a reader using one of the methods in the first category, doing something and finally closing the reader that was opened.
Several methods in this class, such as readLines(), break the contents of the source into lines. Like , 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 may be viewed as a CharSource using ByteSource.asCharSource(Charset).
Since:

14.0

Author:

Colin Decker

Constructor Summary

Constructors
Modifier Constructor Description

protected CharSource()
Constructor for use by subclasses.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method	Description
`ByteSource`	`charset)`	Returns a `ByteSource` view of this char source that encodes chars read from this source as bytes using the given .
`static CharSource`	`concat(CharSource... sources)`	Concatenates multiple `CharSource` instances into a single source.
`static CharSource`	`<? extends CharSource> sources)`	Concatenates multiple `CharSource` instances into a single source.
`static CharSource`	`<? extends CharSource> sources)`	Concatenates multiple `CharSource` instances into a single source.
`long`	`copyTo(CharSink sink)`	Copies the contents of this source to the given sink.
`long`	`appendable)`	Appends the contents of this source to the given (such as a ).
`static CharSource`	`empty()`	Returns an immutable `CharSource` that contains no characters.
`void`	`<? super > 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.
`>`	`lengthIfKnown()`	Returns the size of this source in chars, if the size can be easily determined without actually opening the data stream.
`<>`	`lines()`	Opens a new for reading text one line at a time from this source.
	`openBufferedStream()`	Opens a new for reading from this source.
`abstract`	`openStream()`	Opens a new for reading from this source.
	`read()`	Reads the contents of this source as a string.
	`readFirstLine()`	Reads the first line of this source as a 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`	`charSequence)`	Returns a view of the given character sequence as a `CharSource`.

Methods inherited from class java.lang.
, , , , , , , , , ,

- Constructor Detail
  - CharSource
```
protected CharSource()
```
    Constructor for use by subclasses.
- Method Detail
  - asByteSource
```
@Beta
public  charset)
```
    Returns a ByteSource view of this char source that encodes chars read from this source as bytes using the given .
    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.
    
    Since:
    
    20.0
  - openStream
```
public abstract  openStream()
                           throws 
```
    Opens a new 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.
    
    Throws:
    
    - if an I/O error occurs while opening the reader
  - openBufferedStream
```
public  openBufferedStream()
                                  throws 
```
    Opens a new 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.
    
    Throws:
    
    - if an I/O error occurs while of opening the reader
  - lines
```
@Beta

public <> lines()
                     throws 
```
    Opens a new 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 is thrown.
    Like , 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(...); }
    Throws:
    
    - if an I/O error occurs while opening the stream
    
    Since:
    
    22.0
  - lengthIfKnown
```
@Beta
public > lengthIfKnown()
```
    Returns the size of this source in chars, if the size can be easily determined without actually opening the data stream.
    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 StringBuilders, a subsequent read may return a different number of chars if the contents are changed.
    
    Since:
    
    19.0
  - length
```
@Beta
public long length()
            throws 
```
    Returns the length of this source in chars, even if doing so requires opening and traversing an entire stream. To avoid a potentially expensive operation, see 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, 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.
    
    Throws:
    
    - if an I/O error occurs while reading the length of this source
    
    Since:
    
    19.0
  - copyTo
```
public long  appendable)
            throws 
```
    Appends the contents of this source to the given (such as a ). Does not close appendable if it is Closeable.
    
    Returns:
    
    the number of characters copied
    
    Throws:
    
    - if an I/O error occurs while reading from this source or writing to appendable
  - copyTo
```
public long copyTo(CharSink sink)
            throws 
```
    Copies the contents of this source to the given sink.
    
    Returns:
    
    the number of characters copied
    
    Throws:
    
    - if an I/O error occurs while reading from this source or writing to sink
  - read
```
public  read()
            throws 
```
    Reads the contents of this source as a string.
    
    Throws:
    
    - if an I/O error occurs while reading from this source
  - readFirstLine
```
public   readFirstLine()
                               throws 
```
    Reads the first line of this source as a string. Returns null if this source is empty.
    Like , 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.
    
    Throws:
    
    - if an I/O error occurs while reading from this source
  - readLines
```
public > readLines()
                                throws 
```
    Reads all the lines of this source as a list of strings. The returned list will be empty if this source is empty.
    Like , 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.
    
    Throws:
    
    - if an I/O error occurs while reading from this source
  - readLines
```
@Beta

public <T> T readLines(LineProcessor<T> processor)
                throws 
```
    Reads lines of text from this source, processing each line as it is read using the given processor. Stops when all lines have been processed or the processor returns false and returns the result produced by the processor.
    Like , 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.
    
    Throws:
    
    - if an I/O error occurs while reading from this source or if processor throws an IOException
    
    Since:
    
    16.0
  - forEachLine
```
@Beta
public void <? super > action)
                 throws 
```
    Reads all lines of text from this source, running the given action for each line as it is read.
    Like , 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.
    
    Throws:
    
    - if an I/O error occurs while reading from this source or if action throws an UncheckedIOException
    
    Since:
    
    22.0
  - isEmpty
```
public boolean isEmpty()
                throws 
```
    Returns whether the source has zero chars. The default implementation first checks 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.
    
    Throws:
    
    - if an I/O error occurs
    
    Since:
    
    15.0
  - concat
```
public static <? extends CharSource> sources)
```
    Concatenates multiple 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.
    
    Parameters:
    
    sources - the sources to concatenate
    
    Returns:
    
    a CharSource containing the concatenated data
    
    Since:
    
    15.0
  - concat
```
public static <? extends CharSource> sources)
```
    Concatenates multiple 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.
    
    Parameters:
    
    sources - the sources to concatenate
    
    Returns:
    
    a CharSource containing the concatenated data
    
    Throws:
    
    - if any of sources is null
    
    Since:
    
    15.0
  - concat
```
public static CharSource concat(CharSource... sources)
```
    Concatenates multiple 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.
    
    Parameters:
    
    sources - the sources to concatenate
    
    Returns:
    
    a CharSource containing the concatenated data
    
    Throws:
    
    - if any of sources is null
    
    Since:
    
    15.0
  - wrap
```
public static  charSequence)
```
    Returns a view of the given character sequence as a 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.
    
    Since:
    
    15.0 (since 14.0 as CharStreams.asCharSource(String))
  - empty
```
public static CharSource empty()
```
    Returns an immutable CharSource that contains no characters.
    
    Since:
    
    15.0

Class CharSource

Constructor Summary

Method Summary

Methods inherited from class java.lang.

Constructor Detail

CharSource

Method Detail

asByteSource

openStream

openBufferedStream

lines

lengthIfKnown

length

copyTo

copyTo

read

readFirstLine

readLines

readLines

forEachLine

isEmpty

concat

concat

concat

wrap

empty