org.freecompany.util.text
Class State

java.lang.Object
  extended by org.freecompany.util.text.State
All Implemented Interfaces:
java.lang.CharSequence, java.lang.Iterable<java.lang.Character>, java.util.Iterator<java.lang.Character>
Direct Known Subclasses:
TokenizerState

public class State
extends java.lang.Object
implements java.lang.CharSequence, java.util.Iterator<java.lang.Character>, java.lang.Iterable<java.lang.Character>

Encompases the state of a text processor. This includes a view of the currently available input data, complete with automatic management functions, as well as a position and mark variable. The position is the position of the last character processed, and the mark is a place holder for recalling the start of the current input chunk.

It should be noted that in general the performance of text operations on this state object will be slightly higher when the entirety of the input sequence is held within a single buffer. In other words, when possible it is preferrable to provide the complete input sequence with a single append( CharSequence sequence) invocation.

By utilizing the CharSequence interface exclusively, this scanner can natively supports String, CharBuffer, StringBuilder and StringBuffer objects as input sequences, as well as specially wrapped ByteBuffer instances.


Field Summary
protected  int mark
           
protected  int position
           
protected  java.lang.CharSequence sequence
           
 
Constructor Summary
State()
           
 
Method Summary
 void append(java.nio.ByteBuffer buffer)
          The buffer is assumed to be US-ASCII encoded text (with undefined behavior if this is not the case) and is simply wrapped to look like a character sequence.
 void append(java.nio.ByteBuffer buffer, java.nio.charset.CharsetDecoder decoder)
          Appends a new buffer to the target using the provided decoder.
 void append(java.lang.CharSequence sequence)
          Appends a new sequence to the end of the existing one, allowing the sequence to grow in place.
 char charAt(int index)
           
 void clear()
           
 java.lang.CharSequence expunge()
          Performs a soft expunge which only removes the first sequences that have been exhausted.
 java.lang.CharSequence expunge(boolean force)
          Removes the next unneeded sequence from this parser, if one is available.
 int getMark()
           
 boolean hasNext()
           
 java.util.Iterator<java.lang.Character> iterator()
           
 int length()
           
 void mark()
           
 boolean marked()
           
 java.lang.Character next()
           
 char peek()
          Examines the next character without advancing the position.
 char peekPlus(int advance)
          Examines the character at the position plus the argument without advancing the position.
 int position()
           
 void position(int position)
           
 char previous()
          Returns the character immediately preceeding the current character in this sate object.
 int remaining()
           
 void remove()
           
 void reset()
           
 java.lang.CharSequence rest()
           
 java.lang.CharSequence sequence()
           
 java.lang.CharSequence slice()
          Slices the most recently processed logical characters sequence by capturing and returning the sequence of characters between the mark and the current position and then marking the new position.
 java.lang.CharSequence subSequence(int from, int to)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface java.lang.CharSequence
toString
 

Field Detail

sequence

protected java.lang.CharSequence sequence

position

protected int position

mark

protected int mark
Constructor Detail

State

public State()
Method Detail

clear

public void clear()

append

public void append(java.lang.CharSequence sequence)
Appends a new sequence to the end of the existing one, allowing the sequence to grow in place. This is handled by wrapping the old and new sequences in an aggregating object. If no sequence exists this sequence is set as the new sequence and no wrapping occurs.


append

public void append(java.nio.ByteBuffer buffer)
The buffer is assumed to be US-ASCII encoded text (with undefined behavior if this is not the case) and is simply wrapped to look like a character sequence. In particular, this method will not work if the buffer contains character data encoded in any other character set, including UTF-8.

The buffer is used as is and must be preserved until this state object is no longer needed, and any sub-sequences or slices have been discarded.


append

public void append(java.nio.ByteBuffer buffer,
                   java.nio.charset.CharsetDecoder decoder)
            throws java.nio.charset.CharacterCodingException
Appends a new buffer to the target using the provided decoder. A new CharBuffer is allocated from the pool and the buffer is decoded into it in it's entirety. The caller is free to reuse or dispose of the passed buffer immediately.

Throws:
java.nio.charset.CharacterCodingException

expunge

public java.lang.CharSequence expunge()
Performs a soft expunge which only removes the first sequences that have been exhausted. This is the same as calling expunge( boolean force) with the argument false.


expunge

public java.lang.CharSequence expunge(boolean force)
Removes the next unneeded sequence from this parser, if one is available. If these sequences wrap shared memory they cannot be reused until after all external references have been cleared. If the force flag is specified, then the first CharSequence will be removed regardless of the current position of this scanner.

Returns:
the next <@see ByteBuffer/> if one is available or null if all are still in use or if the parser contains non <@see ByteBuffer/> backed <@see CharSequence/>s.

sequence

public java.lang.CharSequence sequence()

subSequence

public java.lang.CharSequence subSequence(int from,
                                          int to)
Specified by:
subSequence in interface java.lang.CharSequence

charAt

public char charAt(int index)
Specified by:
charAt in interface java.lang.CharSequence

length

public int length()
Specified by:
length in interface java.lang.CharSequence

iterator

public java.util.Iterator<java.lang.Character> iterator()
Specified by:
iterator in interface java.lang.Iterable<java.lang.Character>

slice

public java.lang.CharSequence slice()
Slices the most recently processed logical characters sequence by capturing and returning the sequence of characters between the mark and the current position and then marking the new position. This prepares the state for the next processing operation.


previous

public final char previous()
Returns the character immediately preceeding the current character in this sate object.


peek

public final char peek()
Examines the next character without advancing the position.


peekPlus

public final char peekPlus(int advance)
Examines the character at the position plus the argument without advancing the position.


next

public final java.lang.Character next()
Specified by:
next in interface java.util.Iterator<java.lang.Character>

remaining

public final int remaining()

hasNext

public final boolean hasNext()
Specified by:
hasNext in interface java.util.Iterator<java.lang.Character>

rest

public final java.lang.CharSequence rest()

position

public final void position(int position)

position

public final int position()

marked

public boolean marked()

mark

public final void mark()

getMark

public final int getMark()

reset

public final void reset()

remove

public void remove()
Specified by:
remove in interface java.util.Iterator<java.lang.Character>