CharStreams
Date: 2016-05-24

com.google.common.io

## Class CharStreams

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

-     @Beta
      public final class CharStreams
      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`.

  Since:
    1.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.io.Writer` | `asWriter(java.lang.Appendable target)` Returns a Writer that sends all output to the given `Appendable` target.
    `static long` | `copy(java.lang.Readable from, java.lang.Appendable to)` Copies all characters between the `Readable` and `Appendable` objects.
    `static java.io.Writer` | `nullWriter()` Returns a `Writer` that simply discards written chars.
    `static java.util.List<java.lang.String>` | `readLines(java.lang.Readable r)` Reads all of the lines from a `Readable` object.
    `static <T> T` | `readLines(java.lang.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(java.io.Reader reader, long n)` Discards `n` characters of data from the reader.
    `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

    - #### 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

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

    - #### readLines

          public static <T> T readLines(java.lang.Readable readable,
                        LineProcessor<T> processor)
                             throws java.io.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:
        `java.io.IOException` - if an I/O error occurs
      Since:
        14.0

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

    - #### nullWriter

          public static java.io.Writer nullWriter()

      Returns a `Writer` that simply discards written chars.
      Since:
        15.0

    - #### asWriter

          public static java.io.Writer asWriter(java.lang.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