com.ibm.icu.util

Class CharsTrie

java.lang.Object

com.ibm.icu.util.CharsTrie

All Implemented Interfaces:

Cloneable, Iterable<CharsTrie.Entry>

public final class CharsTrie
extends Object
implements Cloneable, Iterable<CharsTrie.Entry>

Light-weight, non-const reader class for a CharsTrie. Traverses a char-serialized data structure with minimal state, for mapping strings (16-bit-unit sequences) to non-negative integer values.

This class is not intended for public subclassing.

Author:

Markus W. Scherer

Status:

Stable ICU 4.8.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CharsTrie.Entry Return value type for the Iterator.
static class	CharsTrie.Iterator Iterator for all of the (string, value) pairs in a CharsTrie.
static class	CharsTrie.State CharsTrie state object, for saving a trie's current state and resetting the trie back to this state later.

Constructor Summary

Constructors

Constructor and Description
CharsTrie(CharSequence trieChars, int offset) Constructs a CharsTrie reader instance.
CharsTrie(CharsTrie other) Copy constructor.

Method Summary

Modifier and Type	Method and Description
CharsTrie	clone() Clones this trie reader object and its state, but not the char array which will be shared.
BytesTrie.Result	current() Determines whether the string so far matches, whether it has a value, and whether another input char can continue a matching string.
BytesTrie.Result	first(int inUnit) Traverses the trie from the initial state for this input char.
BytesTrie.Result	firstForCodePoint(int cp) Traverses the trie from the initial state for the one or two UTF-16 code units for this input code point.
int	getNextChars(Appendable out) Finds each char which continues the string from the current state.
long	getState64() Returns the state of this trie as a 64-bit integer.
long	getUniqueValue() Determines whether all strings reachable from the current state map to the same value, and if so, returns that value.
int	getValue() Returns a matching string's value if called immediately after current()/first()/next() returned Result.INTERMEDIATE_VALUE or Result.FINAL_VALUE.
CharsTrie.Iterator	iterator() Iterates from the current state of this trie.
static CharsTrie.Iterator	iterator(CharSequence trieChars, int offset, int maxStringLength) Iterates from the root of a char-serialized BytesTrie.
CharsTrie.Iterator	iterator(int maxStringLength) Iterates from the current state of this trie.
BytesTrie.Result	next(CharSequence s, int sIndex, int sLimit) Traverses the trie from the current state for this string.
BytesTrie.Result	next(int inUnit) Traverses the trie from the current state for this input char.
BytesTrie.Result	nextForCodePoint(int cp) Traverses the trie from the current state for the one or two UTF-16 code units for this input code point.
CharsTrie	reset() Resets this trie to its initial state.
CharsTrie	resetToState(CharsTrie.State state) Resets this trie to the saved state.
CharsTrie	resetToState64(long state) Resets this trie to the saved state.
CharsTrie	saveState(CharsTrie.State state) Saves the state of this trie.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

CharsTrie

public CharsTrie(CharSequence trieChars,
                 int offset)

Constructs a CharsTrie reader instance.

The CharSequence must contain a copy of a char sequence from the CharsTrieBuilder, with the offset indicating the first char of that sequence. The CharsTrie object will not read more chars than the CharsTrieBuilder generated in the corresponding build() call.

The CharSequence is not copied/cloned and must not be modified while the CharsTrie object is in use.

Parameters:

trieChars - CharSequence that contains the serialized trie.

offset - Root offset of the trie in the CharSequence.

Status:

Stable ICU 4.8.

CharsTrie

public CharsTrie(CharsTrie other)

Copy constructor. Makes a shallow copy of the other trie reader object and its state. Does not copy the char array which will be shared. Same as clone() but without the throws clause.

Status:

Stable ICU 64.

Method Detail

clone

public CharsTrie clone()
                throws CloneNotSupportedException

Clones this trie reader object and its state, but not the char array which will be shared.

Overrides:

clone in class Object

Returns:

A shallow clone of this trie.

Throws:

CloneNotSupportedException

Status:

Stable ICU 4.8.

reset

public CharsTrie reset()

Resets this trie to its initial state.

Returns:

this

Status:

Stable ICU 4.8.

getState64

public long getState64()

Returns the state of this trie as a 64-bit integer. The state value is never 0.

Returns:

opaque state value

See Also:

resetToState64(long)

Status:

Stable ICU 64.

resetToState64

public CharsTrie resetToState64(long state)

Resets this trie to the saved state. Unlike resetToState(State), the 64-bit state value must be from getState64() from the same trie object or from one initialized the exact same way. Because of no validation, this method is faster.

Parameters:

state - The opaque trie state value from getState64().

Returns:

this

See Also:

getState64(), resetToState(com.ibm.icu.util.CharsTrie.State), reset()

Status:

Stable ICU 64.

saveState

public CharsTrie saveState(CharsTrie.State state)

Saves the state of this trie.

Parameters:

state - The State object to hold the trie's state.

Returns:

this

See Also:

resetToState(com.ibm.icu.util.CharsTrie.State)

Status:

Stable ICU 4.8.

resetToState

public CharsTrie resetToState(CharsTrie.State state)

Resets this trie to the saved state. Slower than resetToState64(long) which does not validate the state value.

Parameters:

state - The State object which holds a saved trie state.

Returns:

this

Throws:

IllegalArgumentException - if the state object contains no state, or the state of a different trie

See Also:

saveState(com.ibm.icu.util.CharsTrie.State), reset()

Status:

Stable ICU 4.8.

current

public BytesTrie.Result current()

Determines whether the string so far matches, whether it has a value, and whether another input char can continue a matching string.

Returns:

The match/value Result.

Status:

Stable ICU 4.8.

first

public BytesTrie.Result first(int inUnit)

Traverses the trie from the initial state for this input char. Equivalent to reset().next(inUnit).

Parameters:

inUnit - Input char value. Values below 0 and above 0xffff will never match.

Returns:

The match/value Result.

Status:

Stable ICU 4.8.

firstForCodePoint

public BytesTrie.Result firstForCodePoint(int cp)

Traverses the trie from the initial state for the one or two UTF-16 code units for this input code point. Equivalent to reset().nextForCodePoint(cp).

Parameters:

cp - A Unicode code point 0..0x10ffff.

Returns:

The match/value Result.

Status:

Stable ICU 4.8.

next

public BytesTrie.Result next(int inUnit)

Traverses the trie from the current state for this input char.

Parameters:

inUnit - Input char value. Values below 0 and above 0xffff will never match.

Returns:

The match/value Result.

Status:

Stable ICU 4.8.

nextForCodePoint

public BytesTrie.Result nextForCodePoint(int cp)

Traverses the trie from the current state for the one or two UTF-16 code units for this input code point.

Parameters:

cp - A Unicode code point 0..0x10ffff.

Returns:

The match/value Result.

Status:

Stable ICU 4.8.

next

public BytesTrie.Result next(CharSequence s,
                             int sIndex,
                             int sLimit)

Traverses the trie from the current state for this string. Equivalent to

 Result result=current();
 for(each c in s)
   if(!result.hasNext()) return Result.NO_MATCH;
   result=next(c);
 return result;
 

Parameters:

s - Contains a string.

sIndex - The start index of the string in s.

sLimit - The (exclusive) end index of the string in s.

Returns:

The match/value Result.

Status:

Stable ICU 4.8.

getValue

public int getValue()

Returns a matching string's value if called immediately after current()/first()/next() returned Result.INTERMEDIATE_VALUE or Result.FINAL_VALUE. getValue() can be called multiple times. Do not call getValue() after Result.NO_MATCH or Result.NO_VALUE!

Returns:

The value for the string so far.

Status:

Stable ICU 4.8.

getUniqueValue

public long getUniqueValue()

Determines whether all strings reachable from the current state map to the same value, and if so, returns that value.

Returns:

The unique value in bits 32..1 with bit 0 set, if all strings reachable from the current state map to the same value; otherwise returns 0.

Status:

Stable ICU 4.8.

getNextChars

public int getNextChars(Appendable out)

Finds each char which continues the string from the current state. That is, each char c for which it would be next(c)!=Result.NO_MATCH now.

Parameters:

out - Each next char is appended to this object. (Only uses the out.append(c) method.)

Returns:

The number of chars which continue the string from here.

Status:

Stable ICU 4.8.

iterator

public CharsTrie.Iterator iterator()

Iterates from the current state of this trie.

Specified by:

iterator in interface Iterable<CharsTrie.Entry>

Returns:

A new CharsTrie.Iterator.

Status:

Stable ICU 4.8.

iterator

public CharsTrie.Iterator iterator(int maxStringLength)

Iterates from the current state of this trie.

Parameters:

maxStringLength - If 0, the iterator returns full strings. Otherwise, the iterator returns strings with this maximum length.

Returns:

A new CharsTrie.Iterator.

Status:

Stable ICU 4.8.

iterator

public static CharsTrie.Iterator iterator(CharSequence trieChars,
                                          int offset,
                                          int maxStringLength)

Iterates from the root of a char-serialized BytesTrie.

Parameters:

trieChars - CharSequence that contains the serialized trie.

offset - Root offset of the trie in the CharSequence.

maxStringLength - If 0, the iterator returns full strings. Otherwise, the iterator returns strings with this maximum length.

Returns:

A new CharsTrie.Iterator.

Status:

Stable ICU 4.8.