javolution.text
Class Cursor

Object
  ParsePosition
      Cursor

All Implemented Interfaces:

Reusable

public class Cursor
extends ParsePosition
implements Reusable

This class represents a parsing cursor over characters. Cursor allows for token iterations over any CharSequence.

     CharSequence csq = "this is a test";
     Cursor cursor = Cursor.newInstance();
     try {
        for (CharSequence token; (token=cursor.nextToken(csq, ' '))!= null;)
            System.out.println(token); 
     } finally {
         Cursor.recycle(cursor);
     }
     

Prints the following output:

        this
        is
        a
        test

Cursors are typically used with TextFormat instances.

     // Parses decimal number (e.g. "xxx.xxxxxExx" or "NaN")
     public Decimal parse(CharSequence csq, Cursor cursor) {
         if (cursor.skip("NaN", csq))
             return Decimal.NaN;
         LargeInteger significand = LargeInteger.TEXT_FORMAT.parse(csq, cursor);
         LargeInteger fraction = cursor.skip('.', csq) ? LargeInteger.TEXT_FORMAT.parse(csq, cursor) : LargeInteger.ZERO;
         int exponent = cursor.skip(CharSet.valueOf('E', 'e'), csq) ? TypeFormat.parseInt(csq, 10, cursor) : 0;
         int fractionDigits = fraction.digitLength();
         return Decimal.valueOf(significand.E(fractionDigits).plus(fraction), exponent - fractionDigits);
     }
     

Version:

5.4, November 19, 2009

Author:

Jean-Marie Dautelle

Constructor Summary

Cursor()
Default constructor.

Method Summary

boolean	at(char c, CharSequence csq) Indicates if this cursor points to the specified character in the specified character sequence.
boolean	at(CharSet charSet, CharSequence csq) Indicates if this cursor points to any of the specified character in the specified character sequence.
boolean	at(String str, CharSequence csq) Indicates if this cursor points to the specified characters in the specified sequence.
boolean	atEnd(CharSequence csq) Indicates if this cursor points to the end of the specified character sequence.
boolean	equals(Object obj) Indicates if this cursor is equals to the specified object.
int	getIndex() Returns this cursor index.
int	hashCode() Returns the hash code for this cursor.
Cursor	increment() Increments the cursor index by one.
Cursor	increment(int i) Increments the cursor index by the specified value.
static Cursor	newInstance() Returns a factory produced instance which can be recycled after usage.
char	nextChar(CharSequence csq) Returns the next character at this cursor position.The cursor position is incremented by one.
CharSequence	nextToken(CharSequence csq, char c) Returns the subsequence from the specified cursor position not holding the specified character.
CharSequence	nextToken(CharSequence csq, CharSet charSet) Returns the subsequence from the specified cursor position not holding any of the characters specified.
static void	recycle(Cursor cursor) Recycles the specified factory produced cursor.
void	reset() Resets this cursor instance.
void	setIndex(int i) Sets the cursor current index.
boolean	skip(char c, CharSequence csq) Moves this cursor forward only if at the specified character.
boolean	skip(CharSet charSet, CharSequence csq) Moves this cursor forward only if at any of the specified character.
boolean	skip(String str, CharSequence csq) Moves this cursor forward only if at the specified string.
boolean	skipAny(char c, CharSequence csq) Moves this cursor forward until it points to a character different from the specified character.
boolean	skipAny(CharSet charSet, CharSequence csq) Moves this cursor forward until it points to a character different from any of the character in the specified set.
String	toString() Returns the string representation of this cursor.

Methods inherited from class ParsePosition

getErrorIndex, setErrorIndex

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Cursor

public Cursor()

Default constructor.

Method Detail

newInstance

public static Cursor newInstance()

Returns a factory produced instance which can be recycled after usage.

Returns:

a recyclable instance.

recycle

public static void recycle(Cursor cursor)

Recycles the specified factory produced cursor.

Parameters:

cursor - the cursor to recycle.

getIndex

public final int getIndex()

Returns this cursor index.

Overrides:

getIndex in class ParsePosition

Returns:

the index of the next character to parse.

setIndex

public void setIndex(int i)

Sets the cursor current index.

Overrides:

setIndex in class ParsePosition

Parameters:

i - the index of the next character to parse.

atEnd

public final boolean atEnd(CharSequence csq)

Indicates if this cursor points to the end of the specified character sequence.

Parameters:

csq - the character sequence iterated by this cursor.

Returns:

getIndex() >= csq.length()

at

public final boolean at(char c,
                        CharSequence csq)

Indicates if this cursor points to the specified character in the specified character sequence.

Parameters:

c - the character to test.

csq - the character sequence iterated by this cursor.

Returns:

csq.charAt(this.getIndex()) == c

at

public final boolean at(CharSet charSet,
                        CharSequence csq)

Indicates if this cursor points to any of the specified character in the specified character sequence.

Parameters:

charSet - any of the character to test.

csq - the character sequence iterated by this cursor.

Returns:

csq.charAt(this.getIndex()) == c

at

public final boolean at(String str,
                        CharSequence csq)

Indicates if this cursor points to the specified characters in the specified sequence.

Parameters:

str - the characters to test.

csq - the character sequence iterated by this cursor.

Returns:

true if this cursor points to the specified characters; false otherwise.

nextChar

public final char nextChar(CharSequence csq)

Returns the next character at this cursor position.The cursor position is incremented by one.

Parameters:

csq - the character sequence iterated by this cursor.

Returns:

the next character this cursor points to.

Throws:

IndexOutOfBoundsException - if this.atEnd(csq)

skipAny

public final boolean skipAny(char c,
                             CharSequence csq)

Moves this cursor forward until it points to a character different from the specified character.

Parameters:

c - the character to skip.

csq - the character sequence iterated by this cursor.

Returns:

true if this cursor has skipped at least one character;false otherwise (e.g. end of sequence reached).

skipAny

public final boolean skipAny(CharSet charSet,
                             CharSequence csq)

Moves this cursor forward until it points to a character different from any of the character in the specified set. For example:

  // Reads numbers separated by tabulations or spaces.
  FastTable<Integer> numbers = new FastTable<Integer>();
  while (cursor.skipAny(CharSet.SPACE_OR_TAB, csq)) {
      numbers.add(TypeFormat.parseInt(csq, cursor));
  }

Parameters:

charSet - the character to skip.

csq - the character sequence iterated by this cursor.

Returns:

true if this cursor has skipped at least one character;false otherwise (e.g. end of sequence reached).

skip

public final boolean skip(char c,
                          CharSequence csq)

Moves this cursor forward only if at the specified character. This method is equivalent to:

     if (at(c, csq))
          increment();
 

Parameters:

c - the character to skip.

csq - the character sequence iterated by this cursor.

Returns:

true if this cursor has skipped the specified character;false otherwise.

skip

public final boolean skip(CharSet charSet,
                          CharSequence csq)

Moves this cursor forward only if at any of the specified character. This method is equivalent to:

     if (at(charSet, csq))
          increment();
 

Parameters:

charSet - holding the characters to skip.

csq - the character sequence iterated by this cursor.

Returns:

true if this cursor has skipped any the specified character;false otherwise.

skip

public final boolean skip(String str,
                          CharSequence csq)

Moves this cursor forward only if at the specified string. This method is equivalent to:

     if (at(str, csq))
          increment(str.length());
 

Parameters:

str - the string to skip.

csq - the character sequence iterated by this cursor.

Returns:

true if this cursor has skipped the specified string;false otherwise (e.g. end of sequence reached).

nextToken

public final CharSequence nextToken(CharSequence csq,
                                    char c)

Returns the subsequence from the specified cursor position not holding the specified character. For example:

    CharSequence csq = "This is a test";
    for (CharSequence token; (token=cursor.nextToken(csq, ' '))!= null;) {
        System.out.println(token); // Prints one word at a time.
    }

Parameters:

csq - the character sequence iterated by this cursor.

c - the character being skipped.

Returns:

the subsequence not holding the specified character or null if none.

nextToken

public final CharSequence nextToken(CharSequence csq,
                                    CharSet charSet)

Returns the subsequence from the specified cursor position not holding any of the characters specified. For example:

    CharSequence csq = "This is a test";
    for (CharSequence token; (token=cursor.nextToken(csq, CharSet.WHITESPACE))!= null;) {
        System.out.println(token); // Prints one word at a time.
    }

Parameters:

csq - the character sequence iterated by this cursor.

charSet - the characters being skipped.

Returns:

the subsequence not holding the specified character or null if none.

increment

public final Cursor increment()

Increments the cursor index by one.

Returns:

this

increment

public final Cursor increment(int i)

Increments the cursor index by the specified value.

Parameters:

i - the increment value.

Returns:

this

toString

public String toString()

Returns the string representation of this cursor.

Overrides:

toString in class ParsePosition

Returns:

the index value as a string.

equals

public boolean equals(Object obj)

Indicates if this cursor is equals to the specified object.

Overrides:

equals in class ParsePosition

Returns:

true if the specified object is a cursor at the same index; false otherwise.

hashCode

public int hashCode()

Returns the hash code for this cursor.

Overrides:

hashCode in class ParsePosition

Returns:

the hash code value for this object

reset

public void reset()

Resets this cursor instance.

Specified by:

reset in interface Reusable

See Also:

Reusable