net.sf.mmm.util.scanner.base
Class CharSequenceScanner

java.lang.Object
  net.sf.mmm.util.scanner.base.CharSequenceScanner

All Implemented Interfaces:

CharStreamScanner

public class CharSequenceScanner
extends Object
implements CharStreamScanner

This class represents a String or better a sequence of characters ( char[]) together with a position in that sequence.
It has various useful methods for scanning the sequence. This scanner is designed to be fast on long sequences and therefore internally converts Strings to a char array instead of frequently calling String.charAt(int).
ATTENTION:
This implementation is NOT and has no intention to be thread-safe.

Since:

1.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Field Summary

private char[]	chars the string to parse as char array
private int	endIndex The exclusive end-index in chars.
private int	length The length of the char-sequence: endIndex - startIndex.
private int	pos
private int	startIndex The start-index in chars.
private String	str

Constructor Summary

CharSequenceScanner(char[] characters)
The constructor.

CharSequenceScanner(char[] characters, int offset, int length)
The constructor.

CharSequenceScanner(CharSequence charSequence)
The constructor.

CharSequenceScanner(String string)
The constructor.

Method Summary

void	appendSubstring(StringBuffer buffer, int start, int end) This method appends the substring specified by start and end to the given buffer.
char	charAt(int index)
boolean	expect(char expected) This method checks that the current character is equal to the given expected character.
boolean	expect(String expected, boolean ignoreCase) This method skips all next characters as long as they equal to the according character of the expected string.
boolean	expectStrict(String expected, boolean ignoreCase) This method acts as CharStreamScanner.expect(String, boolean) but if the expected String is NOT completely present, no character is consumed and the state of the scanner remains unchanged.
char	forceNext() Like CharStreamScanner.next() this method reads the current character and increments the index.
char	forcePeek() This method reads the current character without incrementing the index.
int	getCurrentIndex() This method gets the current position in the stream to scan.
int	getLength()
String	getOriginalString() This method gets the original string to parse.
String	getReplaced(String substitute, int start, int end) This method gets the original string where the substring specified by start and end is replaced by substitute.
boolean	hasNext() This method determines if there is at least one more character available.
char	next() This method reads the current character and increments the index stepping to the next character.
char	peek() This method reads the current character without incrementing the index.
String	read(int count) This method reads the number of next characters given by count and returns them as string.
int	readDigit() This method reads the next character if it is a digit.
long	readLong(int maxDigits) This method reads the long starting at the current position by reading as many Latin digits as available but at maximum the given maxDigits and returns its parsed value.
String	readUntil(char stop, boolean acceptEof) This method reads all next characters until the given stop character or the end is reached.
String	readUntil(char stop, boolean acceptEof, char escape) This method reads all next characters until the given (un-escaped) stop character or the end is reached.
String	readUntil(char stop, boolean acceptEof, CharScannerSyntax syntax) This method reads all next characters until the given stop character or the end of the string to parse is reached.
String	readWhile(CharFilter filter) This method reads all next characters that are accepted by the given filter.
String	readWhile(CharFilter filter, int max) This method reads all next characters that are accepted by the given filter.
void	setCurrentIndex(int index) This method sets the current index.
boolean	skipOver(String substring, boolean ignoreCase) This method reads all next characters until the given substring has been detected.
boolean	skipOver(String substring, boolean ignoreCase, CharFilter stopFilter) This method reads all next characters until the given substring has been detected.
boolean	skipUntil(char stop) This method skips all next characters until the given stop character or the end is reached.
boolean	skipUntil(char stop, char escape) This method reads all next characters until the given stop character or the end of the string to parse is reached.
int	skipWhile(char c) This method reads all next characters that are identical to the character given by c.
int	skipWhile(CharFilter filter) This method reads all next characters that are accepted by the given filter.
int	skipWhile(CharFilter filter, int max) This method reads all next characters that are accepted by the given filter.
void	stepBack() This method decrements the index by one.
String	substring(int start, int end)
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

str

private String str

See Also:

getOriginalString()

chars

private char[] chars

the string to parse as char array

pos

private int pos

See Also:

getCurrentIndex()

startIndex

private final int startIndex

The start-index in chars.

endIndex

private final int endIndex

The exclusive end-index in chars.

length

private final int length

The length of the char-sequence: endIndex - startIndex.

Constructor Detail

CharSequenceScanner

public CharSequenceScanner(CharSequence charSequence)

The constructor.

Parameters:

charSequence - is the string to scan.

CharSequenceScanner

public CharSequenceScanner(String string)

The constructor.

Parameters:

string - is the string to parse.

CharSequenceScanner

public CharSequenceScanner(char[] characters)

The constructor.

Parameters:

characters - is an array containing the characters to scan.

CharSequenceScanner

public CharSequenceScanner(char[] characters,
                           int offset,
                           int length)

The constructor.

Parameters:

characters - is an array containing the characters to scan.

offset - is the index of the first char to scan in characters (typically 0 to start at the beginning of the array).

length - is the number of characters to scan from characters starting at offset (typically characters.length - offset).

Method Detail

charAt

public char charAt(int index)

Parameters:

index - is the index of the requested character.

Returns:

the character at the given index.

See Also:

CharSequence.charAt(int)

getLength

public int getLength()

Returns:

the total length of the string to parse.

See Also:

CharSequence.length()

substring

public String substring(int start,
                        int end)

Parameters:

start - the start index, inclusive.

end - the end index, exclusive.

Returns:

the specified substring.

See Also:

String.substring(int, int), appendSubstring(StringBuffer, int, int)

getReplaced

public String getReplaced(String substitute,
                          int start,
                          int end)

This method gets the original string where the substring specified by start and end is replaced by substitute.

Parameters:

substitute - is the string used as replacement.

start - is the inclusive start index of the substring to replace.

end - is the exclusive end index of the substring to replace.

Returns:

the original string with the specified substring replaced by substitute.

appendSubstring

public void appendSubstring(StringBuffer buffer,
                            int start,
                            int end)

This method appends the substring specified by start and end to the given buffer.
This avoids the overhead of creating a new string and copying the char array.

Parameters:

buffer - is the buffer where to append the substring to.

start - the start index, inclusive.

end - the end index, exclusive.

getCurrentIndex

public int getCurrentIndex()

This method gets the current position in the stream to scan. It will initially be 0. In other words this method returns the number of characters that have already been consumed.

Specified by:

getCurrentIndex in interface CharStreamScanner

Returns:

the current index position.

setCurrentIndex

public void setCurrentIndex(int index)

This method sets the current index.

Parameters:

index - is the next index position to set. The value has to be greater or equal to 0 and less or equal to getLength() .

hasNext

public boolean hasNext()

This method determines if there is at least one more character available.

Specified by:

hasNext in interface CharStreamScanner

Returns:

true if there is at least one character available, false if the end has been reached.

next

public char next()

This method reads the current character and increments the index stepping to the next character. You need to check if a character is available before calling this method.

Specified by:

next in interface CharStreamScanner

Returns:

the current character.

forceNext

public char forceNext()

Like CharStreamScanner.next() this method reads the current character and increments the index. If there is no character available this method will do nothing and returns 0 (the NULL character and NOT '0').

Specified by:

forceNext in interface CharStreamScanner

Returns:

the current character or 0 if none is available.

peek

public char peek()

This method reads the current character without incrementing the index. You need to check if a character is available before calling this method.

Specified by:

peek in interface CharStreamScanner

Returns:

the current character.

forcePeek

public char forcePeek()

This method reads the current character without incrementing the index. If there is no character available this method will return 0 (the NULL character and NOT '0').

Specified by:

forcePeek in interface CharStreamScanner

Returns:

the current character or 0 if none is available.

stepBack

public void stepBack()

This method decrements the index by one. If the index is 0 this method will have no effect.
E.g. use this method if you read a character too much.

skipUntil

public boolean skipUntil(char stop)

This method skips all next characters until the given stop character or the end is reached. If the stop character was reached, this scanner will point to the next character after stop when this method returns.

Specified by:

skipUntil in interface CharStreamScanner

Parameters:

stop - is the character to read until.

Returns:

true if the first occurrence of the given stop character has been passed, false if there is no such character.

readUntil

public String readUntil(char stop,
                        boolean acceptEof)

This method reads all next characters until the given stop character or the end is reached.
After the call of this method, the current index will point to the next character after the (first) stop character or to the end if NO such character exists.

Specified by:

readUntil in interface CharStreamScanner

Parameters:

stop - is the character to read until.

acceptEof - if true EOF will be treated as stop, too.

Returns:

the string with all read characters excluding the stop character or null if there was no stop character and acceptEof is false.

readUntil

public String readUntil(char stop,
                        boolean acceptEof,
                        char escape)

This method reads all next characters until the given (un-escaped) stop character or the end is reached.
In advance to CharStreamScanner.readUntil(char, boolean), this method allows that the stop character may be used in the input-string by adding the given escape character. After the call of this method, the current index will point to the next character after the (first) stop character or to the end if NO such character exists.
This method is especially useful when quoted strings should be parsed. E.g.:

 CharStreamScanner scanner = getScanner();
 doSomething();
 char c = scanner.CharStreamScanner.forceNext();
 if ((c == '"') || (c == '\'')) {
   char escape = c; // may also be something like '\'
   String quote = scanner.readUntil(c, false, escape)
 } else {
   doOtherThings();
 }
 

Specified by:

readUntil in interface CharStreamScanner

Parameters:

stop - is the character to read until.

acceptEof - if true EOF will be treated as stop, too.

escape - is the character used to escape the stop character. To add an occurrence of the escape character it has to be duplicated (occur twice). The escape character may also be equal to the stop character. If other regular characters are escaped the escape character is simply ignored.

Returns:

the string with all read characters excluding the stop character or null if there was no stop character and acceptEof is false.

readUntil

public String readUntil(char stop,
                        boolean acceptEof,
                        CharScannerSyntax syntax)

This method reads all next characters until the given stop character or the end of the string to parse is reached. In advance to CharStreamScanner.readUntil(char, boolean), this method will scan the input using the given syntax which e.g. allows to escape the stop character.
After the call of this method, the current index will point to the next character after the (first) stop character or to the end of the string if NO such character exists.

Specified by:

readUntil in interface CharStreamScanner

Parameters:

stop - is the character to read until.

acceptEof - if true EOF will be treated as stop, too.

syntax - contains the characters specific for the syntax to read.

Returns:

the string with all read characters excluding the stop character or null if there was no stop character.

read

public String read(int count)

This method reads the number of next characters given by count and returns them as string. If there are less characters available the returned string will be shorter than count and only contain the available characters.

Specified by:

read in interface CharStreamScanner

Parameters:

count - is the number of characters to read. You may use Integer.MAX_VALUE to read until the end of data if the data-size is suitable.

Returns:

a string with the given number of characters or all available characters if less than count. Will be the empty string if no character is available at all.

readDigit

public int readDigit()

This method reads the next character if it is a digit. Else the state remains unchanged.

Specified by:

readDigit in interface CharStreamScanner

Returns:

the numeric value of the next Latin digit (e.g. 0 if '0') or -1 if the current character is no Latin digit.

readLong

public long readLong(int maxDigits)
              throws NumberFormatException

This method reads the long starting at the current position by reading as many Latin digits as available but at maximum the given maxDigits and returns its parsed value.
ATTENTION:
This method does NOT treat signs (+ or -) to do so, scan them yourself before and negate the result as needed.

Specified by:

readLong in interface CharStreamScanner

Parameters:

maxDigits - is the maximum number of digits that will be read. The value has to be positive (greater than zero).

Returns:

the parsed number.

Throws:

NumberFormatException - if the current current position does NOT point to a number.

skipOver

public boolean skipOver(String substring,
                        boolean ignoreCase)

This method reads all next characters until the given substring has been detected.
After the call of this method, the current index will point to the next character after the first occurrence of substring or to the end of the string if the given substring was NOT found.

Specified by:

skipOver in interface CharStreamScanner

Parameters:

substring - is the substring to search and skip over starting at the current index.

ignoreCase - - if true the case of the characters is ignored when compared with characters from substring.

Returns:

true if the given substring occurred and has been passed and false if the end of the string has been reached without any occurrence of the given substring.

skipOver

public boolean skipOver(String substring,
                        boolean ignoreCase,
                        CharFilter stopFilter)

This method reads all next characters until the given substring has been detected.
If a stop character is detected by the given stopFilter this method returns false pointing to the character next to that stop character. Otherwise after this method, the current index will point to the next character after the first occurrence of substring or to the end of the string if the given substring was NOT found.

Specified by:

skipOver in interface CharStreamScanner

Parameters:

substring - is the substring to search and skip over starting at the current index.

ignoreCase - - if true the case of the characters is ignored when compared with characters from substring.

stopFilter - is the filter used to detect stop characters. If such character was detected, the skip is stopped and the parser points to the character after the stop character. The substring should NOT contain a stop character.

Returns:

true if the given substring occurred and has been passed and false if a stop character has been detected or the end of the string has been reached without any occurrence of the given substring or stop character.

expect

public boolean expect(String expected,
                      boolean ignoreCase)

This method skips all next characters as long as they equal to the according character of the expected string.
If a character differs this method stops and the parser points to the first character that differs from expected. Except for the latter circumstance, this method behaves like the following code:

 read(expected.length).equals[IgnoreCase](expected)
 

ATTENTION:
Be aware that if already the first character differs, this method will NOT change the state of the scanner. So take care NOT to produce infinity loops.

Specified by:

expect in interface CharStreamScanner

Parameters:

expected - is the expected string.

ignoreCase - - if true the case of the characters is ignored when compared.

Returns:

true if the expected string was successfully consumed from this scanner, false otherwise.

expectStrict

public boolean expectStrict(String expected,
                            boolean ignoreCase)

This method acts as CharStreamScanner.expect(String, boolean) but if the expected String is NOT completely present, no character is consumed and the state of the scanner remains unchanged.

Specified by:

expectStrict in interface CharStreamScanner

Parameters:

expected - is the expected string.

ignoreCase - - if true the case of the characters is ignored when compared.

Returns:

true if the expected string was successfully consumed from this scanner, false otherwise.

expect

public boolean expect(char expected)

This method checks that the current character is equal to the given expected character.
If the current character was as expected, the parser points to the next character. Otherwise its position will remain unchanged.

Specified by:

expect in interface CharStreamScanner

Parameters:

expected - is the expected character.

Returns:

true if the current character is the same as expected, false otherwise.

skipUntil

public boolean skipUntil(char stop,
                         char escape)

This method reads all next characters until the given stop character or the end of the string to parse is reached. In advance to CharStreamScanner.skipUntil(char), this method will read over the stop character if it is escaped with the given escape character.

Specified by:

skipUntil in interface CharStreamScanner

Parameters:

stop - is the character to read until.

escape - is the character used to escape the stop character (e.g. '\').

Returns:

true if the first occurrence of the given stop character has been passed, false if there is no such character.

skipWhile

public int skipWhile(char c)

This method reads all next characters that are identical to the character given by c.
E.g. use readWhile(' ') to skip all blanks from the current index. After the call of this method, the current index will point to the next character that is different to c or to the end if NO such character exists.

Specified by:

skipWhile in interface CharStreamScanner

Parameters:

c - is the character to read over.

Returns:

the number of characters that have been skipped.

skipWhile

public int skipWhile(CharFilter filter)

This method reads all next characters that are accepted by the given filter.
After the call of this method, the current index will point to the next character that was NOT accepted by the given filter or to the end if NO such character exists.

Specified by:

skipWhile in interface CharStreamScanner

Parameters:

filter - is used to decide which characters should be accepted.

Returns:

the number of characters accepted by the given filter that have been skipped.

See Also:

CharStreamScanner.skipWhile(char)

skipWhile

public int skipWhile(CharFilter filter,
                     int max)

This method reads all next characters that are accepted by the given filter.
After the call of this method, the current index will point to the next character that was NOT accepted by the given filter. If the next max characters or the characters left until the end of this scanner are accepted, only that amount of characters are skipped.

Specified by:

skipWhile in interface CharStreamScanner

Parameters:

filter - is used to decide which characters should be accepted.

max - is the maximum number of characters that should be skipped.

Returns:

the number of skipped characters.

See Also:

CharStreamScanner.skipWhile(char)

readWhile

public String readWhile(CharFilter filter)

This method reads all next characters that are accepted by the given filter.
After the call of this method, the current index will point to the next character that was NOT accepted by the given filter or to the end if NO such character exists.

Specified by:

readWhile in interface CharStreamScanner

Parameters:

filter - is used to decide which characters should be accepted.

Returns:

a string with all characters accepted by the given filter. Will be the empty string if no character was accepted.

See Also:

CharStreamScanner.skipWhile(CharFilter)

readWhile

public String readWhile(CharFilter filter,
                        int max)

This method reads all next characters that are accepted by the given filter.
After the call of this method, the current index will point to the next character that was NOT accepted by the given filter. If the next max characters or the characters left until the end of this scanner are accepted, only that amount of characters are skipped.

Specified by:

readWhile in interface CharStreamScanner

Parameters:

filter - is used to decide which characters should be accepted.

max - is the maximum number of characters that should be read.

Returns:

a string with all characters accepted by the given filter limited to the length of max and the end of this scanner. Will be the empty string if no character was accepted.

See Also:

CharStreamScanner.skipWhile(char)

getOriginalString

public String getOriginalString()

This method gets the original string to parse.

Returns:

the original string.

See Also:

CharSequenceScanner(String)

toString

public String toString()

Overrides:

toString in class Object