UnicodeReader
Date: 2017-02-11

org.fife.io

## Class UnicodeReader

- java.lang.Object
- - java.io.Reader
  - - org.fife.io.UnicodeReader

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

      public class UnicodeReader
      extends java.io.Reader

  A reader capable of identifying Unicode streams by their BOMs. This class will recognize the following encodings:
  - UTF-8
  - UTF-16LE
  - UTF-16BE
  - UTF-32LE
  - UTF-32BE
  If the stream is not found to be any of the above, then a default encoding is used for reading. The user can specify this default encoding, or a system default will be used.

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

  This class is mostly ripped off from the workaround in the description of Java Bug 4508058.

- - ### Field Summary

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

      `lock`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `UnicodeReader(java.io.File file)` This utility constructor is here because you will usually use a `UnicodeReader` on files.
    `UnicodeReader(java.io.File file, java.lang.String defaultEncoding)` This utility constructor is here because you will usually use a `UnicodeReader` on files.
    `UnicodeReader(java.io.InputStream in)` Creates a reader using the encoding specified by the BOM in the file; if there is no recognized BOM, then a system default encoding is used.
    `UnicodeReader(java.io.InputStream in, java.lang.String defaultEncoding)` Creates a reader using the encoding specified by the BOM in the file; if there is no recognized BOM, then `defaultEncoding` is used.
    `UnicodeReader(java.lang.String file)` This utility constructor is here because you will usually use a `UnicodeReader` on files.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Closes this reader.
    `java.lang.String` | `getEncoding()` Returns the encoding being used to read this input stream (i.e., the encoding of the file).
    `protected void` | `init(java.io.InputStream in, java.lang.String defaultEncoding)` Read-ahead four bytes and check for BOM marks.
    `int` | `read(char[] cbuf, int off, int len)` Read characters into a portion of an array.

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

      `mark, markSupported, read, read, read, ready, reset, skip`

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

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

- - ### Constructor Detail

    - #### UnicodeReader

          public UnicodeReader(java.lang.String file)
                        throws java.io.IOException,
                               java.io.FileNotFoundException,
                               java.lang.SecurityException

      This utility constructor is here because you will usually use a `UnicodeReader` on files.

      Creates a reader using the encoding specified by the BOM in the file; if there is no recognized BOM, then a system default encoding is used.

      Parameters:
        `file` - The file from which you want to read.
      Throws:
        `java.io.IOException` - If an error occurs when checking for/reading the BOM.
        `java.io.FileNotFoundException` - If the file does not exist, is a directory, or cannot be opened for reading.
        `java.lang.SecurityException` - If a security manager exists and its checkRead method denies read access to the file.

    - #### UnicodeReader

          public UnicodeReader(java.io.File file)
                        throws java.io.IOException,
                               java.io.FileNotFoundException,
                               java.lang.SecurityException

      This utility constructor is here because you will usually use a `UnicodeReader` on files.

      Creates a reader using the encoding specified by the BOM in the file; if there is no recognized BOM, then a system default encoding is used.

      Parameters:
        `file` - The file from which you want to read.
      Throws:
        `java.io.IOException` - If an error occurs when checking for/reading the BOM.
        `java.io.FileNotFoundException` - If the file does not exist, is a directory, or cannot be opened for reading.
        `java.lang.SecurityException` - If a security manager exists and its checkRead method denies read access to the file.

    - #### UnicodeReader

          public UnicodeReader(java.io.File file,
                       java.lang.String defaultEncoding)
                        throws java.io.IOException,
                               java.io.FileNotFoundException,
                               java.lang.SecurityException

      This utility constructor is here because you will usually use a `UnicodeReader` on files.

      Creates a reader using the encoding specified by the BOM in the file; if there is no recognized BOM, then a specified default encoding is used.

      Parameters:
        `file` - The file from which you want to read.
        `defaultEncoding` - The encoding to use if no BOM is found. If this value is `null`, a system default is used.
      Throws:
        `java.io.IOException` - If an error occurs when checking for/reading the BOM.
        `java.io.FileNotFoundException` - If the file does not exist, is a directory, or cannot be opened for reading.
        `java.lang.SecurityException` - If a security manager exists and its checkRead method denies read access to the file.

    - #### UnicodeReader

          public UnicodeReader(java.io.InputStream in)
                        throws java.io.IOException

      Creates a reader using the encoding specified by the BOM in the file; if there is no recognized BOM, then a system default encoding is used.
      Parameters:
        `in` - The input stream from which to read.
      Throws:
        `java.io.IOException` - If an error occurs when checking for/reading the BOM.

    - #### UnicodeReader

          public UnicodeReader(java.io.InputStream in,
                       java.lang.String defaultEncoding)
                        throws java.io.IOException

      Creates a reader using the encoding specified by the BOM in the file; if there is no recognized BOM, then `defaultEncoding` is used.
      Parameters:
        `in` - The input stream from which to read.
        `defaultEncoding` - The encoding to use if no recognized BOM is found. If this value is `null`, a system default is used.
      Throws:
        `java.io.IOException` - If an error occurs when checking for/reading the BOM.

  - ### Method Detail

    - #### close

          public void close()
                     throws java.io.IOException

      Closes this reader.
      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Specified by:
        `close` in class `java.io.Reader`
      Throws:
        `java.io.IOException`

    - #### getEncoding

          public java.lang.String getEncoding()

      Returns the encoding being used to read this input stream (i.e., the encoding of the file). If a BOM was recognized, then the specific Unicode type is returned; otherwise, either the default encoding passed into the constructor or the system default is returned.
      Returns:
        The encoding of the stream.

    - #### init

          protected void init(java.io.InputStream in,
                  java.lang.String defaultEncoding)
                       throws java.io.IOException

      Read-ahead four bytes and check for BOM marks. Extra bytes are unread back to the stream, only BOM bytes are skipped.
      Parameters:
        `defaultEncoding` - The encoding to use if no BOM was recognized. If this value is `null`, then a system default is used.
      Throws:
        `java.io.IOException` - If an error occurs when trying to read a BOM.

    - #### read

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

      Read characters into a portion of an array. This method will block until some input is available, an I/O error occurs, or the end of the stream is reached.
      Specified by:
        `read` in class `java.io.Reader`
      Parameters:
        `cbuf` - The buffer into which to read.
        `off` - The offset at which to start storing characters.
        `len` - The maximum number of characters to read.
      Returns:
        The number of characters read, or `-1` if the end of the stream has been reached.
      Throws:
        `java.io.IOException`