Class CharReadBuffer


  • public class CharReadBuffer
    extends java.lang.Object
    Class used to buffer characters read from an underlying Reader. Characters can be consumed from the buffer, examined without being consumed, and pushed back onto the buffer. The internal bufer is resized as needed.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private char[] buffer
      Character buffer.
      private int count
      The number of valid elements in the buffer.
      private static int DEFAULT_INITIAL_CAPACITY
      Default initial buffer capacity.
      private static int EOF
      Constant indicating that the end of the input has been reached.
      private int head
      The index of the head element in the buffer.
      private static double LOG2
      Log 2 constant.
      private int minRead
      Minimum number of characters to request for each read.
      private boolean reachedEof
      True when the end of reader content is reached.
      private java.io.Reader reader
      Underlying reader instance.
    • Constructor Summary

      Constructors 
      Constructor Description
      CharReadBuffer​(java.io.Reader reader)
      Construct a new instance that buffers characters from the given reader.
      CharReadBuffer​(java.io.Reader reader, int initialCapacity)
      Construct a new instance that buffers characters from the given reader.
      CharReadBuffer​(java.io.Reader reader, int initialCapacity, int minRead)
      Construct a new instance that buffers characters from the given reader.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int charAt​(int index)
      Get the character at the given buffer index or -1 if the index is past the end of the content.
      private void charsAppended​(int n)
      Method called to indicate that characters have been appended to the end of the read buffer.
      private void charsPushed​(int n)
      Method called to indicate that characters have been pushed to the front of the read buffer.
      private void charsRemoved​(int n)
      Method called to indicate that characters have been removed from the front of the read buffer.
      private void ensureCapacity​(int capacity)
      Ensure that the current buffer has at least capacity number of elements.
      boolean hasMoreCharacters()
      Return true if more characters are available from the read buffer.
      int makeAvailable​(int n)
      Attempt to make at least n characters available in the buffer, reading characters from the underlying reader as needed.
      int peek()
      Return the next character in the buffer without removing it.
      java.lang.String peekString​(int len)
      Return a string from the buffer without removing it.
      void push​(char ch)
      Push a character back onto the read buffer.
      private void pushCharInternal​(char ch)
      Internal method to push a single character back onto the read buffer.
      void pushString​(java.lang.String str)
      Push a string back onto the read buffer.
      int read()
      Remove and return the next character in the buffer.
      private void readChars​(int n)
      Read characters from the underlying character stream into the internal buffer.
      java.lang.String readString​(int len)
      Remove and return a string from the buffer.
      int skip​(int n)
      Skip n characters from the stream.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • EOF

        private static final int EOF
        Constant indicating that the end of the input has been reached.
        See Also:
        Constant Field Values
      • DEFAULT_INITIAL_CAPACITY

        private static final int DEFAULT_INITIAL_CAPACITY
        Default initial buffer capacity.
        See Also:
        Constant Field Values
      • LOG2

        private static final double LOG2
        Log 2 constant.
      • reader

        private final java.io.Reader reader
        Underlying reader instance.
      • buffer

        private char[] buffer
        Character buffer.
      • head

        private int head
        The index of the head element in the buffer.
      • count

        private int count
        The number of valid elements in the buffer.
      • reachedEof

        private boolean reachedEof
        True when the end of reader content is reached.
      • minRead

        private final int minRead
        Minimum number of characters to request for each read.
    • Constructor Detail

      • CharReadBuffer

        public CharReadBuffer​(java.io.Reader reader)
        Construct a new instance that buffers characters from the given reader.
        Parameters:
        reader - underlying reader instance
        Throws:
        java.lang.NullPointerException - if reader is null
      • CharReadBuffer

        public CharReadBuffer​(java.io.Reader reader,
                              int initialCapacity)
        Construct a new instance that buffers characters from the given reader.
        Parameters:
        reader - underlying reader instance
        initialCapacity - the initial capacity of the internal buffer; the buffer is resized as needed
        Throws:
        java.lang.NullPointerException - if reader is null
        java.lang.IllegalArgumentException - if initialCapacity is less than one.
      • CharReadBuffer

        public CharReadBuffer​(java.io.Reader reader,
                              int initialCapacity,
                              int minRead)
        Construct a new instance that buffers characters from the given reader.
        Parameters:
        reader - underlying reader instance
        initialCapacity - the initial capacity of the internal buffer; the buffer is resized as needed
        minRead - the minimum number of characters to request from the reader when fetching more characters into the buffer; this can be used to limit the number of calls made to the reader
        Throws:
        java.lang.NullPointerException - if reader is null
        java.lang.IllegalArgumentException - if initialCapacity or minRead are less than one.
    • Method Detail

      • hasMoreCharacters

        public boolean hasMoreCharacters()
        Return true if more characters are available from the read buffer.
        Returns:
        true if more characters are available from the read buffer
        Throws:
        java.io.UncheckedIOException - if an I/O error occurs
      • makeAvailable

        public int makeAvailable​(int n)
        Attempt to make at least n characters available in the buffer, reading characters from the underlying reader as needed. The number of characters available is returned.
        Parameters:
        n - number of characters requested to be available
        Returns:
        number of characters available for immediate use in the buffer
        Throws:
        java.io.UncheckedIOException - if an I/O error occurs
      • read

        public int read()
        Remove and return the next character in the buffer.
        Returns:
        the next character in the buffer or -1 if the end of the content has been reached
        Throws:
        java.io.UncheckedIOException - if an I/O error occurs
        See Also:
        peek()
      • readString

        public java.lang.String readString​(int len)
        Remove and return a string from the buffer. The length of the string will be the number of characters available in the buffer up to len. Null is returned if no more characters are available.
        Parameters:
        len - requested length of the string
        Returns:
        a string from the read buffer or null if no more characters are available
        Throws:
        java.lang.IllegalArgumentException - if len is less than 0
        java.io.UncheckedIOException - if an I/O error occurs
        See Also:
        peekString(int)
      • peek

        public int peek()
        Return the next character in the buffer without removing it.
        Returns:
        the next character in the buffer or -1 if the end of the content has been reached
        Throws:
        java.io.UncheckedIOException - if an I/O error occurs
        See Also:
        read()
      • peekString

        public java.lang.String peekString​(int len)
        Return a string from the buffer without removing it. The length of the string will be the number of characters available in the buffer up to len. Null is returned if no more characters are available.
        Parameters:
        len - requested length of the string
        Returns:
        a string from the read buffer or null if no more characters are available
        Throws:
        java.lang.IllegalArgumentException - if len is less than 0
        java.io.UncheckedIOException - if an I/O error occurs
        See Also:
        readString(int)
      • charAt

        public int charAt​(int index)
        Get the character at the given buffer index or -1 if the index is past the end of the content. The character is not removed from the buffer.
        Parameters:
        index - index of the character to receive relative to the buffer start
        Returns:
        the character at the given index of -1 if the character is past the end of the stream content
        Throws:
        java.io.UncheckedIOException - if an I/O exception occurs
      • skip

        public int skip​(int n)
        Skip n characters from the stream. Characters are first skipped from the buffer and then from the underlying reader using Reader.skip(long) if needed.
        Parameters:
        n - number of character to skip
        Returns:
        the number of characters skipped
        Throws:
        java.lang.IllegalArgumentException - if n is negative
        java.io.UncheckedIOException - if an I/O error occurs
      • push

        public void push​(char ch)
        Push a character back onto the read buffer. The argument will be the next character returned by read() or peek().
        Parameters:
        ch - character to push onto the read buffer
      • pushString

        public void pushString​(java.lang.String str)
        Push a string back onto the read buffer. The first character of the string will be the next character returned by read() or peek().
        Parameters:
        str - string to push onto the read buffer
      • pushCharInternal

        private void pushCharInternal​(char ch)
        Internal method to push a single character back onto the read buffer. The buffer capacity is not checked.
        Parameters:
        ch - character to push onto the read buffer
      • readChars

        private void readChars​(int n)
        Read characters from the underlying character stream into the internal buffer.
        Parameters:
        n - minimum number of characters requested to be placed in the buffer
        Throws:
        java.io.UncheckedIOException - if an I/O error occurs
      • charsRemoved

        private void charsRemoved​(int n)
        Method called to indicate that characters have been removed from the front of the read buffer.
        Parameters:
        n - number of characters removed
      • charsPushed

        private void charsPushed​(int n)
        Method called to indicate that characters have been pushed to the front of the read buffer.
        Parameters:
        n - number of characters pushed
      • charsAppended

        private void charsAppended​(int n)
        Method called to indicate that characters have been appended to the end of the read buffer.
        Parameters:
        n - number of characters appended
      • ensureCapacity

        private void ensureCapacity​(int capacity)
        Ensure that the current buffer has at least capacity number of elements. The number of content elements in the buffer is not changed.
        Parameters:
        capacity - the minimum required capacity of the buffer