org.freecompany.util.text

Class State

public class State extends Object implements CharSequence, Iterator<Character>, Iterable<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 State 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 java.nio.ByteBuffer instances.

Field Summary
protected intmark
protected intposition
protected CharSequencesequence
Method Summary
voidappend(CharSequence sequence)
Appends a new sequence to the end of the existing one, allowing the sequence to grow in place.
voidappend(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.
voidappend(ByteBuffer buffer, CharsetDecoder decoder)
Appends a new buffer to the target using the provided decoder.
charcharAt(int index)
voidclear()
CharSequenceexpunge()
Performs a soft expunge which only removes the first sequences that have been exhausted.
CharSequenceexpunge(boolean force)
Removes the next unneeded sequence from this parser, if one is available.
intgetMark()
booleanhasNext()
Iterator<Character>iterator()
intlength()
voidmark()
booleanmarked()
Characternext()
charpeek()
Examines the next character without advancing the position.
charpeekPlus(int advance)
Examines the character at the position plus the argument without advancing the position.
voidposition(int position)
intposition()
charprevious()
Returns the character immediately preceeding the current character in this sate object.
intremaining()
voidremove()
voidreset()
CharSequencerest()
CharSequencesequence()
CharSequenceslice()
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.
CharSequencesubSequence(int from, int to)

Field Detail

mark

protected int mark

position

protected int position

sequence

protected CharSequence sequence

Method Detail

append

public void append(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(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(ByteBuffer buffer, CharsetDecoder decoder)
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.

charAt

public char charAt(int index)

clear

public void clear()

expunge

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

expunge

public 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.

getMark

public final int getMark()

hasNext

public final boolean hasNext()

iterator

public Iterator<Character> iterator()

length

public int length()

mark

public final void mark()

marked

public boolean marked()

next

public final Character next()

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.

position

public final void position(int position)

position

public final int position()

previous

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

remaining

public final int remaining()

remove

public void remove()

reset

public final void reset()

rest

public final CharSequence rest()

sequence

public CharSequence sequence()

slice

public 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.

subSequence

public CharSequence subSequence(int from, int to)