Top Description Inners Fields Constructors Methods
com.ibm.icu.text

public final Class CollationElementIterator

extends Object
Class Inheritance
Imports
java.text.CharacterIterator, java.util.HashMap, .Map, com.ibm.icu.impl.CharacterIteratorWrapper, com.ibm.icu.impl.coll.Collation, .CollationData, .CollationIterator, .ContractionsAndExpansions, .FCDIterCollationIterator, .FCDUTF16CollationIterator, .IterCollationIterator, .UTF16CollationIterator, .UVector32
CollationElementIterator is an iterator created by a RuleBasedCollator to walk through a string. The return result of each iteration is a 32-bit collation element (CE) that defines the ordering priority of the next character or sequence of characters in the source string.

For illustration, consider the following in Slovak and in traditional Spanish collation: 

"ca" -> the first collation element is CE('c') and the second
        collation element is CE('a').
"cha" -> the first collation element is CE('ch') and the second
         collation element is CE('a').
And in German phonebook collation, 
Since the character 'æ' is a composed character of 'a' and 'e', the
iterator returns two collation elements for the single character 'æ'

"æb" -> the first collation element is collation_element('a'), the
             second collation element is collation_element('e'), and the
             third collation element is collation_element('b').

For collation ordering comparison, the collation element results can not be compared simply by using basic arithmetic operators, e.g. <, == or >, further processing has to be done. Details can be found in the ICU User Guide. An example of using the CollationElementIterator for collation ordering comparison is the class com.ibm.icu.text.StringSearch.

To construct a CollationElementIterator object, users call the method getCollationElementIterator() on a RuleBasedCollator that defines the desired sorting order.

Example: 

 String testString = "This is a test";
 RuleBasedCollator rbc = new RuleBasedCollator("&a<b");
 CollationElementIterator iterator = rbc.getCollationElementIterator(testString);
 int primaryOrder = iterator.IGNORABLE;
 while (primaryOrder != iterator.NULLORDER) {
     int order = iterator.next();
     if (order != iterator.IGNORABLE &&
         order != iterator.NULLORDER) {
         // order is valid, not ignorable and we have not passed the end
         // of the iteration, we do something
         primaryOrder = CollationElementIterator.primaryOrder(order);
         System.out.println("Next primary order 0x" +
                            Integer.toHexString(primaryOrder));
     }
 }

The method next() returns the collation order of the next character based on the comparison level of the collator. The method previous() returns the collation order of the previous character based on the comparison level of the collator. The Collation Element Iterator moves only in one direction between calls to reset(), setOffset(), or setText(). That is, next() and previous() can not be inter-used. Whenever previous() is to be called after next() or vice versa, reset(), setOffset() or setText() has to be called first to reset the status, shifting current position to either the end or the start of the string (reset() or setText()), or the specified position (setOffset()). Hence at the next call of next() or previous(), the first or last collation order, or collation order at the specified position will be returned. If a change of direction is done without one of these calls, the result is undefined.

This class is not subclassable.

Author
Syn Wee Quek
ICU Status
Stable since ICU 2.8.
See Also
Collator, RuleBasedCollator, StringSearch

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
CollationElementIterator.MaxExpSink

Field Summary

Modifier and TypeField and Description
private byte
dir_

<0: backwards; 0: just after reset() (previous() begins from end); 1: just after setOffset(); >1: forward

public static final int
IGNORABLE

This constant is returned by the iterator in the methods next() and previous() when a collation element result is to be ignored.

private CollationIterator
iter_

public static final int
NULLORDER

This constant is returned by the iterator in the methods next() and previous() when the end or the beginning of the source string has been reached, and there are no more valid collation elements to return.

private UVector32
offsets_

Stores offsets from expansions and from unsafe-backwards iteration, so that getOffset() returns intermediate offsets for the CEs that are consistent with forward iteration.

private int
otherHalf_

private RuleBasedCollator
rbc_

private String
string_

Constructor Summary

AccessConstructor and Description
private
CollationElementIterator(RuleBasedCollator collator)

pack-priv
CollationElementIterator(String
the source string.
source, RuleBasedCollator
the RuleBasedCollator
collator)

CollationElementIterator constructor.

pack-priv
CollationElementIterator(CharacterIterator
the source string iterator.
source, RuleBasedCollator
the RuleBasedCollator
collator)

CollationElementIterator constructor.

pack-priv
CollationElementIterator(UCharacterIterator
the source string iterator.
source, RuleBasedCollator
the RuleBasedCollator
collator)

CollationElementIterator constructor.

Method Summary

Modifier and TypeMethod and Description
private static final boolean
ceNeedsTwoParts(long ce)

pack-priv static final Map<Integer, Integer>
computeMaxExpansions(CollationData data)

public boolean
equals(Object
object to test if it is equals to this CollationElementIterator
that)

Overrides java.lang.Object.equals.

Tests that argument object is equals to this CollationElementIterator.
private static final int
getFirstHalf(long p, int lower32)

public int

Returns:

the maximum length of any expansion sequence ending with the specified collation element.
getMaxExpansion(int
a collation element returned by previous() or next().
ce)

Returns the maximum length of any expansion sequence that ends with the specified collation element.

pack-priv static int
getMaxExpansion(Map<Integer, Integer> maxExpansions, int order)

public int

Returns:

The character offset in the source string corresponding to the collation element that will be returned by the next call to next() or previous().
getOffset()

Returns the character offset in the source string corresponding to the next collation element.

public RuleBasedCollator
getRuleBasedCollator()

Deprecated This API is ICU internal only.
private static final int
getSecondHalf(long p, int lower32)

public int
hashCode()

Overrides java.lang.Object.hashCode.

Mock implementation of hashCode().
public int

Returns:

the next collation element or NULLORDER if the end of the iteration has been reached.
next()

Get the next collation element in the source string.

private byte
normalizeDir()

Normalizes dir_=1 (just after setOffset()) to dir_=0 (just after reset()).

public int

Returns:

the previous collation element, or NULLORDER when the start of the iteration has been reached.
previous()

Get the previous collation element in the source string.

public static final int

Returns:

the element's 16 bits primary order.
primaryOrder(int
the collation element
ce)

Return the primary order of the specified collation element, i.e. the first 16 bits.

public void
reset()

Resets the cursor to the beginning of the string.

public static final int

Returns:

the element's 8 bits secondary order
secondaryOrder(int
the collation element
ce)

Return the secondary order of the specified collation element, i.e. the 16th to 23th bits, inclusive.

public void
setOffset(int
the character offset into the original source string to set. Note that this is not an offset into the corresponding sequence of collation elements.
newOffset)

Sets the iterator to point to the collation element corresponding to the character at the specified offset.

public void
setText(String
the new source string for iteration.
source)

Set a new source string for iteration, and reset the offset to the beginning of the text.

public void
setText(UCharacterIterator
the new source string iterator for iteration.
source)

Set a new source string iterator for iteration, and reset the offset to the beginning of the text.

public void
setText(CharacterIterator
the new source string iterator for iteration.
source)

Set a new source string iterator for iteration, and reset the offset to the beginning of the text.

public static final int

Returns:

the element's 8 bits tertiary order
tertiaryOrder(int
the collation element
ce)

Return the tertiary order of the specified collation element, i.e. the last 8 bits.

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAlltoStringwaitwaitwait

Field Detail

dir_back to summary
private byte dir_

<0: backwards; 0: just after reset() (previous() begins from end); 1: just after setOffset(); >1: forward

IGNORABLEback to summary
public static final int IGNORABLE

This constant is returned by the iterator in the methods next() and previous() when a collation element result is to be ignored.

See class documentation for an example of use.

ICU Status
Stable since ICU 2.8.
See Also
next, previous
iter_back to summary
private CollationIterator iter_
NULLORDERback to summary
public static final int NULLORDER

This constant is returned by the iterator in the methods next() and previous() when the end or the beginning of the source string has been reached, and there are no more valid collation elements to return.

See class documentation for an example of use.

ICU Status
Stable since ICU 2.8.
See Also
next, previous
offsets_back to summary
private UVector32 offsets_

Stores offsets from expansions and from unsafe-backwards iteration, so that getOffset() returns intermediate offsets for the CEs that are consistent with forward iteration.

otherHalf_back to summary
private int otherHalf_
rbc_back to summary
private RuleBasedCollator rbc_
string_back to summary
private String string_

Constructor Detail

CollationElementIteratorback to summary
private CollationElementIterator(RuleBasedCollator collator)
CollationElementIteratorback to summary
pack-priv CollationElementIterator(String source, RuleBasedCollator collator)

CollationElementIterator constructor. This takes a source string and a RuleBasedCollator. The iterator will walk through the source string based on the rules defined by the collator. If the source string is empty, NULLORDER will be returned on the first call to next().

Parameters
source:String

the source string.

collator:RuleBasedCollator

the RuleBasedCollator

ICU Status
Stable since ICU 2.8.
CollationElementIteratorback to summary
pack-priv CollationElementIterator(CharacterIterator source, RuleBasedCollator collator)

CollationElementIterator constructor. This takes a source character iterator and a RuleBasedCollator. The iterator will walk through the source string based on the rules defined by the collator. If the source string is empty, NULLORDER will be returned on the first call to next().

Parameters
source:CharacterIterator

the source string iterator.

collator:RuleBasedCollator

the RuleBasedCollator

ICU Status
Stable since ICU 2.8.
CollationElementIteratorback to summary
pack-priv CollationElementIterator(UCharacterIterator source, RuleBasedCollator collator)

CollationElementIterator constructor. This takes a source character iterator and a RuleBasedCollator. The iterator will walk through the source string based on the rules defined by the collator. If the source string is empty, NULLORDER will be returned on the first call to next().

Parameters
source:UCharacterIterator

the source string iterator.

collator:RuleBasedCollator

the RuleBasedCollator

ICU Status
Stable since ICU 2.8.

Method Detail

ceNeedsTwoPartsback to summary
private static final boolean ceNeedsTwoParts(long ce)
computeMaxExpansionsback to summary
pack-priv static final Map<Integer, Integer> computeMaxExpansions(CollationData data)
equalsback to summary
public boolean equals(Object that)

Overrides java.lang.Object.equals.

Tests that argument object is equals to this CollationElementIterator. Iterators are equal if the objects uses the same RuleBasedCollator, the same source text and have the same current position in iteration.

Parameters
that:Object

object to test if it is equals to this CollationElementIterator

Returns:boolean

Doc from java.lang.Object.equals.

true if this object is the same as the obj argument; false otherwise.

Annotations
@Override
ICU Status
Stable since ICU 2.8.
getFirstHalfback to summary
private static final int getFirstHalf(long p, int lower32)
getMaxExpansionback to summary
public int getMaxExpansion(int ce)

Returns the maximum length of any expansion sequence that ends with the specified collation element. If there is no expansion with this collation element as the last element, returns 1.

Parameters
ce:int

a collation element returned by previous() or next().

Returns:int

the maximum length of any expansion sequence ending with the specified collation element.

ICU Status
Stable since ICU 2.8.
getMaxExpansionback to summary
pack-priv static int getMaxExpansion(Map<Integer, Integer> maxExpansions, int order)
getOffsetback to summary
public int getOffset()

Returns the character offset in the source string corresponding to the next collation element. I.e., getOffset() returns the position in the source string corresponding to the collation element that will be returned by the next call to next() or previous(). This value could be any of:

  • The index of the first character corresponding to the next collation element. (This means that if setOffset(offset) sets the index in the middle of a contraction, getOffset() returns the index of the first character in the contraction, which may not be equal to the original offset that was set. Hence calling getOffset() immediately after setOffset(offset) does not guarantee that the original offset set will be returned.)
  • If normalization is on, the index of the immediate subsequent character, or composite character with the first character, having a combining class of 0.
  • The length of the source string, if iteration has reached the end.
Returns:int

The character offset in the source string corresponding to the collation element that will be returned by the next call to next() or previous().

ICU Status
Stable since ICU 2.8.
getRuleBasedCollatorback to summary
public RuleBasedCollator getRuleBasedCollator()

Deprecated

This API is ICU internal only.

Annotations
@Deprecated
ICU Status
Internal ICU component.
getSecondHalfback to summary
private static final int getSecondHalf(long p, int lower32)
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Mock implementation of hashCode(). This implementation always returns a constant value. When Java assertion is enabled, this method triggers an assertion failure.

Returns:int

Doc from java.lang.Object.hashCode.

a hash code value for this object.

Annotations
@Override
ICU Status
Stable since ICU 2.8.
nextback to summary
public int next()

Get the next collation element in the source string.

This iterator iterates over a sequence of collation elements that were built from the string. Because there isn't necessarily a one-to-one mapping from characters to collation elements, this doesn't mean the same thing as "return the collation element [or ordering priority] of the next character in the string".

This function returns the collation element that the iterator is currently pointing to, and then updates the internal pointer to point to the next element.

Returns:int

the next collation element or NULLORDER if the end of the iteration has been reached.

ICU Status
Stable since ICU 2.8.
normalizeDirback to summary
private byte normalizeDir()

Normalizes dir_=1 (just after setOffset()) to dir_=0 (just after reset()).

previousback to summary
public int previous()

Get the previous collation element in the source string.

This iterator iterates over a sequence of collation elements that were built from the string. Because there isn't necessarily a one-to-one mapping from characters to collation elements, this doesn't mean the same thing as "return the collation element [or ordering priority] of the previous character in the string".

This function updates the iterator's internal pointer to point to the collation element preceding the one it's currently pointing to and then returns that element, while next() returns the current element and then updates the pointer.

Returns:int

the previous collation element, or NULLORDER when the start of the iteration has been reached.

ICU Status
Stable since ICU 2.8.
primaryOrderback to summary
public static final int primaryOrder(int ce)

Return the primary order of the specified collation element, i.e. the first 16 bits. This value is unsigned.

Parameters
ce:int

the collation element

Returns:int

the element's 16 bits primary order.

ICU Status
Stable since ICU 2.8.
resetback to summary
public void reset()

Resets the cursor to the beginning of the string. The next call to next() or previous() will return the first and last collation element in the string, respectively.

If the RuleBasedCollator used by this iterator has had its attributes changed, calling reset() will reinitialize the iterator to use the new attributes.

ICU Status
Stable since ICU 2.8.
secondaryOrderback to summary
public static final int secondaryOrder(int ce)

Return the secondary order of the specified collation element, i.e. the 16th to 23th bits, inclusive. This value is unsigned.

Parameters
ce:int

the collation element

Returns:int

the element's 8 bits secondary order

ICU Status
Stable since ICU 2.8.
setOffsetback to summary
public void setOffset(int newOffset)

Sets the iterator to point to the collation element corresponding to the character at the specified offset. The value returned by the next call to next() will be the collation element corresponding to the characters at offset.

If offset is in the middle of a contracting character sequence, the iterator is adjusted to the start of the contracting sequence. This means that getOffset() is not guaranteed to return the same value set by this method.

If the decomposition mode is on, and offset is in the middle of a decomposible range of source text, the iterator may not return a correct result for the next forwards or backwards iteration. The user must ensure that the offset is not in the middle of a decomposible range.

Parameters
newOffset:int

the character offset into the original source string to set. Note that this is not an offset into the corresponding sequence of collation elements.

ICU Status
Stable since ICU 2.8.
setTextback to summary
public void setText(String source)

Set a new source string for iteration, and reset the offset to the beginning of the text.

Parameters
source:String

the new source string for iteration.

ICU Status
Stable since ICU 2.8.
setTextback to summary
public void setText(UCharacterIterator source)

Set a new source string iterator for iteration, and reset the offset to the beginning of the text.

The source iterator's integrity will be preserved since a new copy will be created for use.

Parameters
source:UCharacterIterator

the new source string iterator for iteration.

ICU Status
Stable since ICU 2.8.
setTextback to summary
public void setText(CharacterIterator source)

Set a new source string iterator for iteration, and reset the offset to the beginning of the text.

Parameters
source:CharacterIterator

the new source string iterator for iteration.

ICU Status
Stable since ICU 2.8.
tertiaryOrderback to summary
public static final int tertiaryOrder(int ce)

Return the tertiary order of the specified collation element, i.e. the last 8 bits. This value is unsigned.

Parameters
ce:int

the collation element

Returns:int

the element's 8 bits tertiary order

ICU Status
Stable since ICU 2.8.
com.ibm.icu.text back to summary

private final Class CollationElementIterator.MaxExpSink

extends Object
implements CESink
Class Inheritance
All Implemented Interfaces
com.ibm.icu.impl.coll.ContractionsAndExpansions.CESink

Field Summary

Modifier and TypeField and Description
private Map<Integer, Integer>
maxExpansions

Constructor Summary

AccessConstructor and Description
pack-priv
MaxExpSink(Map<Integer, Integer> h)

Method Summary

Modifier and TypeMethod and Description
public void
handleCE(long ce)

Implements com.ibm.icu.impl.coll.ContractionsAndExpansions.CESink.handleCE.

public void
handleExpansion(long[] ces, int start, int length)

Implements com.ibm.icu.impl.coll.ContractionsAndExpansions.CESink.handleExpansion.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

maxExpansionsback to summary
private Map<Integer, Integer> maxExpansions

Constructor Detail

MaxExpSinkback to summary
pack-priv MaxExpSink(Map<Integer, Integer> h)

Method Detail

handleCEback to summary
public void handleCE(long ce)

Implements com.ibm.icu.impl.coll.ContractionsAndExpansions.CESink.handleCE.

Annotations
@Override
handleExpansionback to summary
public void handleExpansion(long[] ces, int start, int length)

Implements com.ibm.icu.impl.coll.ContractionsAndExpansions.CESink.handleExpansion.

Annotations
@Override