CollationElementIterator

Kotlin |Java

class CollationElementIterator

kotlin.Any
↳	android.icu.text.CollationElementIterator

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 android.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.

Summary

Constants
static Int	`IGNORABLE` This constant is returned by the iterator in the methods next() and previous() when a collation element result is to be ignored.
static 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.

Public methods
Boolean	`equals(other: Any?)` Tests that argument object is equals to this CollationElementIterator.
Int	`getMaxExpansion(ce: Int)` Returns the maximum length of any expansion sequence that ends with the specified collation element.
Int	`getOffset()` Returns the character offset in the source string corresponding to the next collation element.
Int	`next()` Get the next collation element in the source string.
Int	`previous()` Get the previous collation element in the source string.
static Int	`primaryOrder(ce: Int)` Return the primary order of the specified collation element, i.
Unit	`reset()` Resets the cursor to the beginning of the string.
static Int	`secondaryOrder(ce: Int)` Return the secondary order of the specified collation element, i.
Unit	`setOffset(newOffset: Int)` Sets the iterator to point to the collation element corresponding to the character at the specified offset.
Unit	`setText(source: UCharacterIterator!)` Set a new source string iterator for iteration, and reset the offset to the beginning of the text.
Unit	`setText(source: String!)` Set a new source string for iteration, and reset the offset to the beginning of the text.
Unit	`setText(source: CharacterIterator!)` Set a new source string iterator for iteration, and reset the offset to the beginning of the text.
static Int	`tertiaryOrder(ce: Int)` Return the tertiary order of the specified collation element, i.

Parameters
`obj`	the reference object with which to compare.
`that`	object to test if it is equals to this CollationElementIterator

CollationElementIterator

Summary

Constants

IGNORABLE

NULLORDER

Public methods

equals

getMaxExpansion

getOffset

next

previous

primaryOrder

reset

secondaryOrder

setOffset

setText

setText

setText

tertiaryOrder