CharSource
Date: 2016-05-24

com.google.common.io

## Class CharSource

- java.lang.Object
- - com.google.common.io.CharSource

-     public abstract class CharSource
      extends java.lang.Object

  A readable source of characters, such as a text file. Unlike a `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:

  - 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 `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)`.

  Since:
    14.0

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `CharSource()` Constructor for use by subclasses.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static CharSource` | `concat(CharSource... sources)` Concatenates multiple `CharSource` instances into a single source.
    `static CharSource` | `concat(java.lang.Iterable<? extends CharSource> sources)` Concatenates multiple `CharSource` instances into a single source.
    `static CharSource` | `concat(java.util.Iterator<? extends CharSource> sources)` Concatenates multiple `CharSource` instances into a single source.
    `long` | `copyTo(java.lang.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.
    `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<java.lang.Long>` | `lengthIfKnown()` Returns the size of this source in chars, if the size can be easily determined without actually opening the data stream.
    `java.io.BufferedReader` | `openBufferedStream()` Opens a new `BufferedReader` for reading from this source.
    `abstract java.io.Reader` | `openStream()` Opens a new `Reader` for reading from this source.
    `java.lang.String` | `read()` Reads the contents of this source as a string.
    `java.lang.String` | `readFirstLine()` Reads the first link of this source as a string.
    `ImmutableList<java.lang.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(java.lang.CharSequence charSequence)` Returns a view of the given character sequence as a `CharSource`.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### CharSource

          protected CharSource()

      Constructor for use by subclasses.

  - ### Method Detail

    - #### openStream

          public abstract java.io.Reader openStream()
                                             throws java.io.IOException

      Opens a new `Reader` for reading from this source. This method should return a new, independent reader each time it is called.

      The caller is responsible for ensuring that the returned reader is closed.

      Throws:
        `java.io.IOException` - if an I/O error occurs in the process of opening the reader

    - #### openBufferedStream

          public java.io.BufferedReader openBufferedStream()
                                                    throws java.io.IOException

      Opens a new `BufferedReader` for reading from this source. This method should return a new, independent reader each time it is called.

      The caller is responsible for ensuring that the returned reader is closed.

      Throws:
        `java.io.IOException` - if an I/O error occurs in the process of opening the reader

    - #### lengthIfKnown

          @Beta
          public Optional<java.lang.Long> 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 `StringBuilder`s, a subsequent read may return a different number of chars if the contents are changed.

      Since:
        19.0

    - #### length

          @Beta
          public long length()
                      throws java.io.IOException

      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, `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.

      Throws:
        `java.io.IOException` - if an I/O error occurs in the process of reading the length of this source
      Since:
        19.0

    - #### copyTo

          public long copyTo(java.lang.Appendable appendable)
                      throws java.io.IOException

      Appends the contents of this source to the given `Appendable` (such as a `Writer`). Does not close `appendable` if it is `Closeable`.
      Throws:
        `java.io.IOException` - if an I/O error occurs in the process of reading from this source or writing to `appendable`

    - #### copyTo

          public long copyTo(CharSink sink)
                      throws java.io.IOException

      Copies the contents of this source to the given sink.
      Throws:
        `java.io.IOException` - if an I/O error occurs in the process of reading from this source or writing to `sink`

    - #### read

          public java.lang.String read()
                                throws java.io.IOException

      Reads the contents of this source as a string.
      Throws:
        `java.io.IOException` - if an I/O error occurs in the process of reading from this source

    - #### readFirstLine

          @Nullable
          public java.lang.String readFirstLine()
                                         throws java.io.IOException

      Reads the first link of this source as a string. Returns `null` if this source is empty.

      Like `BufferedReader`, this method breaks lines on any of `\n`, `\r` or `\r\n`, does not include the line separator in the returned line and does not consider there to be an extra empty line at the end if the content is terminated with a line separator.

      Throws:
        `java.io.IOException` - if an I/O error occurs in the process of reading from this source

    - #### readLines

          public ImmutableList<java.lang.String> readLines()
                                                    throws java.io.IOException

      Reads all the lines of this source as a list of strings. The returned list will be empty if this source is empty.

      Like `BufferedReader`, this method breaks lines on any of `\n`, `\r` or `\r\n`, does not include the line separator in the returned lines and does not consider there to be an extra empty line at the end if the content is terminated with a line separator.

      Throws:
        `java.io.IOException` - if an I/O error occurs in the process of reading from this source

    - #### readLines

          @Beta
          public <T> T readLines(LineProcessor<T> processor)
                      throws java.io.IOException

      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 `BufferedReader`, this method breaks lines on any of `\n`, `\r` or `\r\n`, does not include the line separator in the lines passed to the `processor` and does not consider there to be an extra empty line at the end if the content is terminated with a line separator.

      Throws:
        `java.io.IOException` - if an I/O error occurs in the process of reading from this source or if `processor` throws an `IOException`
      Since:
        16.0

    - #### isEmpty

          public boolean isEmpty()
                          throws java.io.IOException

      Returns whether the source has zero chars. The default implementation returns true if `lengthIfKnown()` returns zero, falling back to opening a stream and checking for EOF if the length is not known.

      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:
        `java.io.IOException` - if an I/O error occurs
      Since:
        15.0

    - #### concat

          public static CharSource concat(java.lang.Iterable<? 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 CharSource concat(java.util.Iterator<? 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:
        `java.lang.NullPointerException` - 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:
        `java.lang.NullPointerException` - if any of `sources` is `null`
      Since:
        15.0

    - #### wrap

          public static CharSource wrap(java.lang.CharSequence 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