CharSink
Date: 2016-05-24

com.google.common.io

## Class CharSink

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

-     public abstract class CharSink
      extends java.lang.Object

  A destination to which characters can be written, such as a text file. Unlike a `Writer`, a `CharSink` is not an open, stateful stream that can be written to and closed. Instead, it is an immutable supplier of `Writer` instances.

  `CharSink` provides two kinds of methods:

  - Methods that return a writer: These methods should return a new, independent instance each time they are called. The caller is responsible for ensuring that the returned writer is closed.
  - Convenience methods: These are implementations of common operations that are typically implemented by opening a writer using one of the methods in the first category, doing something and finally closing the writer that was opened.

  Any `ByteSink` may be viewed as a `CharSink` with a specific character encoding using `ByteSink.asCharSink(Charset)`. Characters written to the resulting `CharSink` will written to the `ByteSink` as encoded bytes.

  Since:
    14.0

- - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.io.Writer` | `openBufferedStream()` Opens a new buffered `Writer` for writing to this sink.
    `abstract java.io.Writer` | `openStream()` Opens a new `Writer` for writing to this sink.
    `void` | `write(java.lang.CharSequence charSequence)` Writes the given character sequence to this sink.
    `long` | `writeFrom(java.lang.Readable readable)` Writes all the text from the given `Readable` (such as a `Reader`) to this sink.
    `void` | `writeLines(java.lang.Iterable<? extends java.lang.CharSequence> lines)` Writes the given lines of text to this sink with each line (including the last) terminated with the operating system's default line separator.
    `void` | `writeLines(java.lang.Iterable<? extends java.lang.CharSequence> lines, java.lang.String lineSeparator)` Writes the given lines of text to this sink with each line (including the last) terminated with the given line separator.

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

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

- - ### Constructor Detail

    - #### CharSink

          protected CharSink()

      Constructor for use by subclasses.

  - ### Method Detail

    - #### openStream

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

      Opens a new `Writer` for writing to this sink. This method should return a new, independent writer each time it is called.

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

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

    - #### openBufferedStream

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

      Opens a new buffered `Writer` for writing to this sink. The returned stream is not required to be a `BufferedWriter` in order to allow implementations to simply delegate to `openStream()` when the stream returned by that method does not benefit from additional buffering. This method should return a new, independent writer each time it is called.

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

      Throws:
        `java.io.IOException` - if an I/O error occurs in the process of opening the writer
      Since:
        15.0 (in 14.0 with return type `BufferedWriter`)

    - #### write

          public void write(java.lang.CharSequence charSequence)
                     throws java.io.IOException

      Writes the given character sequence to this sink.
      Throws:
        `java.io.IOException` - if an I/O error in the process of writing to this sink

    - #### writeLines

          public void writeLines(java.lang.Iterable<? extends java.lang.CharSequence> lines)
                          throws java.io.IOException

      Writes the given lines of text to this sink with each line (including the last) terminated with the operating system's default line separator. This method is equivalent to `writeLines(lines, System.getProperty("line.separator"))`.
      Throws:
        `java.io.IOException` - if an I/O error occurs in the process of writing to this sink

    - #### writeLines

          public void writeLines(java.lang.Iterable<? extends java.lang.CharSequence> lines,
                        java.lang.String lineSeparator)
                          throws java.io.IOException

      Writes the given lines of text to this sink with each line (including the last) terminated with the given line separator.
      Throws:
        `java.io.IOException` - if an I/O error occurs in the process of writing to this sink

    - #### writeFrom

          public long writeFrom(java.lang.Readable readable)
                         throws java.io.IOException

      Writes all the text from the given `Readable` (such as a `Reader`) to this sink. Does not close `readable` if it is `Closeable`.
      Throws:
        `java.io.IOException` - if an I/O error occurs in the process of reading from `readable` or writing to this sink