Java Doc for CollationElementIterator.java in  » Internationalization-Localization » icu4j » com » ibm » icu » text » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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 that defines the ordering priority of the next character or sequence of characters in the source string.

For illustration, consider the following in Spanish:

 "ca" -> the first collation element is collation_element('c') and second
 collation element is collation_element('a').
 Since "ch" in Spanish sorts as one entity, the below example returns one
 collation element for the two characters 'c' and 'h'
 "cha" -> the first collation element is collation_element('ch') and second
 collation element is collation_element('a').
 

 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 arithmetric 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));
 }
 }
 

This class is not subclassable

CollationElementIterator constructor.

CollationElementIterator constructor.

CollationElementIterator constructor.

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

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

Get the next collation element in the source string.

This iterator iterates over a sequence of collation elements that were built from the string.

Get the previous collation element in the source string.

This iterator iterates over a sequence of collation elements that were built from the string.

Resets the cursor to the beginning of the string.

Sets the iterator to point to the collation element corresponding to the specified character (the parameter is a CHARACTER offset in the original string, not an offset into its corresponding sequence of collation elements).

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

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

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

Sets the iterator to point to the collation element corresponding to the specified character (the parameter is a CHARACTER offset in the original string, not an offset into its corresponding sequence of collation elements).

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.

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.

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().

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().

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().

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.

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(). 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.

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. Previous() updates the pointer first, and then returns the element. This means that when you change direction while iterating (i.e., call next() and then call previous(), or call previous() and then call next()), you'll get back the same element twice.

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. This means that when you change direction while iterating (i.e., call next() and then call previous(), or call previous() and then call next()), you'll get back the same element twice.

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.

Sets the iterator to point to the collation element corresponding to the specified character (the parameter is a CHARACTER offset in the original string, not an offset into its corresponding sequence of collation elements). The value returned by the next call to next() will be the collation element corresponding to the specified position in the text. Unlike the public method setOffset(int), this method does not try to readjust the offset to the start of a contracting sequence. getOffset() is guaranteed to return the same value as was passed to a preceding call to setOffset().

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.

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

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.

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

Sets the iterator to point to the collation element corresponding to the specified character (the parameter is a CHARACTER offset in the original string, not an offset into its corresponding sequence of collation elements). The value returned by the next call to next() will be the collation element corresponding to the specified position in the text. Unlike the public method setOffset(int), this method does not try to readjust the offset to the start of a contracting sequence. getOffset() is guaranteed to return the same value as was passed to a preceding call to setOffset().