GXPARSE hosted by SourceForge.net Logo

ca.gorman.util.scan
Interface ScanBuffer

All Superinterfaces:
CharSequence, Expandable
All Known Subinterfaces:
InputScanBuffer
All Known Implementing Classes:
AbstractScanBuffer

public interface ScanBuffer
extends CharSequence, Expandable

A view into the a subsequence of the sequence of characters that are currently available for pattern matching.

Some implementations of ScanBuffer may hold much more data than will fit in memory. In such cases, copying very large numbers of characters to memory or invoking the toString() method on the ScanBuffer (or on a large subsequence of the ScanBuffer) may cause an OutOfMemoryError.

The content of a ScanBuffer, and any of its subsquences or sub-buffers, is undefined outside an instance of ScanMatch, ScanAction, or ScanRule. When persistent data is required, the data should be obtained by copying the characters or by invoking the toString method of the appropriate ScanBuffer, subsequence or sub-buffer.


Method Summary
 MatchedText accept(int length)
           Remove a prefix of the ScanBuffer from the ScanBuffer and create a MatchedText containing the same characters.
 MatchedText act(ScanRule scanRule)
           Test a ScanRule for a match against a leading prefix of the ScanBuffer and invoke the corresponding action if the match succeeds.
 CharSequence put(String key, CharSequence charSequence)
           Save a CharSequence for later retrieval in an action.
 ScanBuffer subBuffer(int offset)
           Get a new buffer, beginning at the specified offset from the beginning of the buffer, and continuing to the end of the parent buffer.
 
Methods inherited from interface java.lang.CharSequence
charAt, length, subSequence, toString
 
Methods inherited from interface ca.gorman.util.scan.Expandable
expand
 

Method Detail

accept

MatchedText accept(int length)

Remove a prefix of the ScanBuffer from the ScanBuffer and create a MatchedText containing the same characters.

Although the prefix is no longer available in this ScanBuffer any ancestors of this ScanBuffer will remain unchanged.

Parameters:
length - the number (zero or more) of characters to accept and remove.
Returns:
an instance of MatchedText, containing the accepted characters
Throws:
IndexOutOfBoundsException - if the length argument is negative or greater than length()

subBuffer

ScanBuffer subBuffer(int offset)

Get a new buffer, beginning at the specified offset from the beginning of the buffer, and continuing to the end of the parent buffer.

The new buffer shares the characters from the offset to the end of the parent buffer.

Throws:
IndexOutOfBoundsException - if the offset argument is negative or greater than length()

put

CharSequence put(String key,
                 CharSequence charSequence)

Save a CharSequence for later retrieval in an action. The data will be discarded when the Scanner completes the next action.

Returns:
Previous value, or null if no value has been set since the completion of the last action.
Throws:
NullPointerException - if key is null

act

MatchedText act(ScanRule scanRule)
                throws IOException

Test a ScanRule for a match against a leading prefix of the ScanBuffer and invoke the corresponding action if the match succeeds.

Returns:
the sequence of characters matched (zero or more) or null if the match did not succeed.
Throws:
IllegalStateException - if a reference to the scanner state has not been set to a non-null value
IOException
See Also:
InputScanBuffer.setScanState(ScanState)

GXPARSE download

GXPARSE Generic XML Stream Parser API and supporting tools.   Release $Name: gxparse-sf-alpha-2_0 $
Copyright 2003-2004 Ian E. Gorman
Released under GNU Lesser General Public License