UnicodeWriter
Date: 2017-02-11

org.fife.io

## Class UnicodeWriter

- java.lang.Object
- - java.io.Writer
  - - org.fife.io.UnicodeWriter

- All Implemented Interfaces:
    java.io.Closeable, java.io.Flushable, java.lang.Appendable, java.lang.AutoCloseable

      public class UnicodeWriter
      extends java.io.Writer

  Writes Unicode text to an output stream. If the specified encoding is a Unicode, then the text is preceded by the proper Unicode BOM. If it is any other encoding, this class behaves just like `OutputStreamWriter`. This class is here because Java's `OutputStreamWriter` apparently doesn't believe in writing BOMs.

  For optimum performance, it is recommended that you wrap all instances of `UnicodeWriter` with a `java.io.BufferedWriter`.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `PROPERTY_WRITE_UTF8_BOM` If this system property evaluates to "`false`", ignoring case, files written out as UTF-8 will not have a BOM written for them.

    - ### Fields inherited from class java.io.Writer

      `lock`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `UnicodeWriter(java.io.File file, java.lang.String encoding)` This is a utility constructor since the vast majority of the time, this class will be used to write Unicode files.
    `UnicodeWriter(java.io.OutputStream out, java.lang.String encoding)` Creates a new writer.
    `UnicodeWriter(java.lang.String fileName, java.lang.String encoding)` This is a utility constructor since the vast majority of the time, this class will be used to write Unicode files.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Closes this writer.
    `void` | `flush()` Flushes the stream.
    `java.lang.String` | `getEncoding()` Returns the encoding being used to write this output stream (i.e., the encoding of the file).
    `static boolean` | `getWriteUtf8BOM()` Returns whether UTF-8 files should have a BOM in them when written.
    `static void` | `setWriteUtf8BOM(boolean write)` Sets whether UTF-8 files should have a BOM written in them.
    `void` | `write(char[] cbuf, int off, int len)` Writes a portion of an array of characters.
    `void` | `write(int c)` Writes a single character.
    `void` | `write(java.lang.String str, int off, int len)` Writes a portion of a string.

    - ### Methods inherited from class java.io.Writer

      `append, append, append, write, write`

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

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

- - ### Field Detail

    - #### PROPERTY_WRITE_UTF8_BOM

          public static final java.lang.String PROPERTY_WRITE_UTF8_BOM

      If this system property evaluates to "`false`", ignoring case, files written out as UTF-8 will not have a BOM written for them. Otherwise (even if the property is not set), UTF-8 files will have a BOM written.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### UnicodeWriter

          public UnicodeWriter(java.lang.String fileName,
                       java.lang.String encoding)
                        throws java.io.UnsupportedEncodingException,
                               java.io.IOException

      This is a utility constructor since the vast majority of the time, this class will be used to write Unicode files.
      Parameters:
        `fileName` - The file to which to write the Unicode output.
        `encoding` - The encoding to use.
      Throws:
        `java.io.UnsupportedEncodingException` - If the specified encoding is not supported.
        `java.io.IOException` - If an IO exception occurs.

    - #### UnicodeWriter

          public UnicodeWriter(java.io.File file,
                       java.lang.String encoding)
                        throws java.io.UnsupportedEncodingException,
                               java.io.IOException

      This is a utility constructor since the vast majority of the time, this class will be used to write Unicode files.
      Parameters:
        `file` - The file to which to write the Unicode output.
        `encoding` - The encoding to use.
      Throws:
        `java.io.UnsupportedEncodingException` - If the specified encoding is not supported.
        `java.io.IOException` - If an IO exception occurs.

    - #### UnicodeWriter

          public UnicodeWriter(java.io.OutputStream out,
                       java.lang.String encoding)
                        throws java.io.UnsupportedEncodingException,
                               java.io.IOException

      Creates a new writer.
      Parameters:
        `out` - The output stream to write.
        `encoding` - The encoding to use.
      Throws:
        `java.io.UnsupportedEncodingException` - If the specified encoding is not supported.
        `java.io.IOException` - If an IO exception occurs.

  - ### Method Detail

    - #### close

          public void close()
                     throws java.io.IOException

      Closes this writer.
      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Specified by:
        `close` in class `java.io.Writer`
      Throws:
        `java.io.IOException` - If an IO exception occurs.

    - #### flush

          public void flush()
                     throws java.io.IOException

      Flushes the stream.
      Specified by:
        `flush` in interface `java.io.Flushable`
      Specified by:
        `flush` in class `java.io.Writer`
      Throws:
        `java.io.IOException` - If an IO exception occurs.

    - #### getEncoding

          public java.lang.String getEncoding()

      Returns the encoding being used to write this output stream (i.e., the encoding of the file).
      Returns:
        The encoding of the stream.

    - #### getWriteUtf8BOM

          public static boolean getWriteUtf8BOM()

      Returns whether UTF-8 files should have a BOM in them when written.
      Returns:
        Whether to write a BOM for UTF-8 files.
      See Also:
        `setWriteUtf8BOM(boolean)`, `UnicodeWriter`

    - #### setWriteUtf8BOM

          public static void setWriteUtf8BOM(boolean write)

      Sets whether UTF-8 files should have a BOM written in them.
      Parameters:
        `write` - Whether to write a BOM.
      See Also:
        `getWriteUtf8BOM()`, `UnicodeWriter`

    - #### write

          public void write(char[] cbuf,
                   int off,
                   int len)
                     throws java.io.IOException

      Writes a portion of an array of characters.
      Specified by:
        `write` in class `java.io.Writer`
      Parameters:
        `cbuf` - The buffer of characters.
        `off` - The offset from which to start writing characters.
        `len` - The number of characters to write.
      Throws:
        `java.io.IOException` - If an I/O error occurs.

    - #### write

          public void write(int c)
                     throws java.io.IOException

      Writes a single character.
      Overrides:
        `write` in class `java.io.Writer`
      Parameters:
        `c` - An integer specifying the character to write.
      Throws:
        `java.io.IOException` - If an IO error occurs.

    - #### write

          public void write(java.lang.String str,
                   int off,
                   int len)
                     throws java.io.IOException

      Writes a portion of a string.
      Overrides:
        `write` in class `java.io.Writer`
      Parameters:
        `str` - The string from which to write.
        `off` - The offset from which to start writing characters.
        `len` - The number of characters to write.
      Throws:
        `java.io.IOException` - If an IO error occurs.