org.apache.commons.io.input

## Class UnsynchronizedBufferedReader

- java.lang.Object
- - java.io.Reader
  - - org.apache.commons.io.input.UnsynchronizedReader
    - - org.apache.commons.io.input.UnsynchronizedBufferedReader

- All Implemented Interfaces:
    Closeable, AutoCloseable, Readable

      public class UnsynchronizedBufferedReader
      extends UnsynchronizedReader

  Wraps an existing `Reader` and buffers the input without any synchronization. Expensive interaction with the underlying reader is minimized, since most (smaller) requests can be satisfied by accessing the buffer alone. The drawback is that some extra space is required to hold the buffer and that copying takes place when filling that buffer, but this is usually outweighed by the performance benefits.

  A typical application pattern for the class looks like this:

       UnsynchronizedBufferedReader buf = new UnsynchronizedBufferedReader(new FileReader("file"));

  Provenance: Apache Harmony's java.io.BufferedReader, renamed, and modified.

  See Also:
    `BufferedReader`, `BufferedWriter`

- - ### Field Summary

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

      `lock`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `UnsynchronizedBufferedReader(Reader in)` Constructs a new BufferedReader on the Reader `in`.
    `UnsynchronizedBufferedReader(Reader in, int size)` Constructs a new BufferedReader on the Reader `in`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `(package private) void` | `chompNewline()` Peeks at the next input character, refilling the buffer if necessary.
    `void` | `close()` Closes this reader.
    `void` | `mark(int markLimit)` Sets a mark position in this reader.
    `boolean` | `markSupported()` Tests whether this reader supports the `mark(int)` and `reset()` methods.
    `int` | `peek()` Returns the next character in the current reader without consuming it.
    `int` | `peek(char[] buf)` Populates the buffer with the next `buf.length` characters in the current reader without consuming them.
    `int` | `read()` Reads a single character from this reader and returns it with the two higher-order bytes set to 0.
    `int` | `read(char[] buffer, int offset, int length)` Reads at most `length` characters from this reader and stores them at `offset` in the character array `buffer`.
    `String` | `readLine()` Returns the next line of text available from this reader.
    `boolean` | `ready()` Tests whether this reader is ready to be read without blocking.
    `void` | `reset()` Resets this reader's position to the last `mark()` location.
    `long` | `skip(long amount)` Skips `amount` characters in this reader.

    - ### Methods inherited from class org.apache.commons.io.input.UnsynchronizedReader

      `checkOpen, isClosed, setClosed`

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

      `read, read`

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

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

- - ### Constructor Detail

    - #### UnsynchronizedBufferedReader

          public UnsynchronizedBufferedReader(Reader in)

      Constructs a new BufferedReader on the Reader `in`. The buffer gets the default size (8 KB).
      Parameters:
        `in` - the Reader that is buffered.

    - #### UnsynchronizedBufferedReader

          public UnsynchronizedBufferedReader(Reader in,
                                              int size)

      Constructs a new BufferedReader on the Reader `in`. The buffer size is specified by the parameter `size`.
      Parameters:
        `in` - the Reader that is buffered.
        `size` - the size of the buffer to allocate.
      Throws:
        `IllegalArgumentException` - if `size <= 0`.

  - ### Method Detail

    - #### chompNewline

          final void chompNewline()
                           throws IOException

      Peeks at the next input character, refilling the buffer if necessary. If this character is a newline character ("\n"), it is discarded.
      Throws:
        `IOException`

    - #### close

          public void close()
                     throws IOException

      Closes this reader. This implementation closes the buffered source reader and releases the buffer. Nothing is done if this reader has already been closed.
      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`
      Overrides:
        `close` in class `UnsynchronizedReader`
      Throws:
        `IOException` - if an error occurs while closing this reader.

    - #### mark

          public void mark(int markLimit)
                    throws IOException

      Sets a mark position in this reader. The parameter `markLimit` indicates how many characters can be read before the mark is invalidated. Calling `reset()` will reposition the reader back to the marked position if `markLimit` has not been surpassed.
      Overrides:
        `mark` in class `Reader`
      Parameters:
        `markLimit` - the number of characters that can be read before the mark is invalidated.
      Throws:
        `IllegalArgumentException` - if `markLimit < 0`.
        `IOException` - if an error occurs while setting a mark in this reader.
      See Also:
        `markSupported()`, `reset()`

    - #### markSupported

          public boolean markSupported()

      Tests whether this reader supports the `mark(int)` and `reset()` methods. This implementation returns `true`.
      Overrides:
        `markSupported` in class `Reader`
      Returns:
        `true` for `BufferedReader`.
      See Also:
        `mark(int)`, `reset()`

    - #### peek

          public int peek()
                   throws IOException

      Returns the next character in the current reader without consuming it. So the next call to `read()` will still return this value.
      Returns:
        the next character
      Throws:
        `IOException` - If an I/O error occurs

    - #### peek

          public int peek(char[] buf)
                   throws IOException

      Populates the buffer with the next `buf.length` characters in the current reader without consuming them. The next call to `read()` will still return the next value.
      Parameters:
        `buf` - the buffer to fill for the look ahead.
      Returns:
        the buffer itself
      Throws:
        `IOException` - If an I/O error occurs

    - #### read

          public int read()
                   throws IOException

      Reads a single character from this reader and returns it with the two higher-order bytes set to 0. If possible, BufferedReader returns a character from the buffer. If there are no characters available in the buffer, it fills the buffer and then returns a character. It returns -1 if there are no more characters in the source reader.
      Overrides:
        `read` in class `Reader`
      Returns:
        the character read or -1 if the end of the source reader has been reached.
      Throws:
        `IOException` - if this reader is closed or some other I/O error occurs.

    - #### read

          public int read(char[] buffer,
                          int offset,
                          int length)
                   throws IOException

      Reads at most `length` characters from this reader and stores them at `offset` in the character array `buffer`. Returns the number of characters actually read or -1 if the end of the source reader has been reached. If all the buffered characters have been used, a mark has not been set and the requested number of characters is larger than this readers buffer size, BufferedReader bypasses the buffer and simply places the results directly into `buffer`.
      Specified by:
        `read` in class `Reader`
      Parameters:
        `buffer` - the character array to store the characters read.
        `offset` - the initial position in `buffer` to store the bytes read from this reader.
        `length` - the maximum number of characters to read, must be non-negative.
      Returns:
        number of characters read or -1 if the end of the source reader has been reached.
      Throws:
        `IndexOutOfBoundsException` - if `offset < 0` or `length < 0`, or if `offset + length` is greater than the size of `buffer`.
        `IOException` - if this reader is closed or some other I/O error occurs.

    - #### readLine

          public String readLine()
                          throws IOException

      Returns the next line of text available from this reader. A line is represented by zero or more characters followed by `LF`, `CR`, `"\r\n"` or the end of the reader. The string does not include the newline sequence.
      Returns:
        the contents of the line or `null` if no characters were read before the end of the reader has been reached.
      Throws:
        `IOException` - if this reader is closed or some other I/O error occurs.

    - #### ready

          public boolean ready()
                        throws IOException

      Tests whether this reader is ready to be read without blocking.
      Overrides:
        `ready` in class `Reader`
      Returns:
        `true` if this reader will not block when `read` is called, `false` if unknown or blocking will occur.
      Throws:
        `IOException` - if this reader is closed or some other I/O error occurs.
      See Also:
        `read()`, `read(char[], int, int)`, `readLine()`

    - #### reset

          public void reset()
                     throws IOException

      Resets this reader's position to the last `mark()` location. Invocations of `read()` and `skip()` will occur from this new location.
      Overrides:
        `reset` in class `Reader`
      Throws:
        `IOException` - if this reader is closed or no mark has been set.
      See Also:
        `mark(int)`, `markSupported()`

    - #### skip

          public long skip(long amount)
                    throws IOException

      Skips `amount` characters in this reader. Subsequent `read()`s will not return these characters unless `reset()` is used. Skipping characters may invalidate a mark if `markLimit` is surpassed.
      Overrides:
        `skip` in class `UnsynchronizedReader`
      Parameters:
        `amount` - the maximum number of characters to skip.
      Returns:
        the number of characters actually skipped.
      Throws:
        `IllegalArgumentException` - if `amount < 0`.
        `IOException` - if this reader is closed or some other I/O error occurs.
      See Also:
        `mark(int)`, `markSupported()`, `reset()`