Skip to content

Most visited

Recently visited

navigation
Added in API level 1

CollationElementIterator

public final class CollationElementIterator
extends Object

java.lang.Object
   ↳ java.text.CollationElementIterator


Created by a RuleBasedCollator to iterate through a string. The 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 example below returns one collation element for the two characters 'c' and 'h':

"cha": the first collation element is collation_element('ch') and the second one is collation_element('a').

In German, since the character '\u0086' is a composed character of 'a' and 'e', the iterator returns two collation elements for the single character '\u0086':

"\u0086b": the first collation element is collation_element('a'), the second one is collation_element('e'), and the third collation element is collation_element('b').

Note that calls to next and previous can not be mixed. To change iteration direction, reset, setOffset or setText must be called to reset the iterator. If a change of direction is done without one of these calls, the result is undefined.

Summary

Constants

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

int getMaxExpansion(int order)

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

Returns the next collation element in the source string or NULLORDER if the end of the iteration has been reached.

int previous()

Returns the previous collation element in the source string or NULLORDER if the start of the iteration has been reached.

final static int primaryOrder(int order)

Returns the primary order of the specified collation element, i.e.

void reset()

Repositions the cursor to point at the first element of the current string.

final static short secondaryOrder(int order)

Returns the secondary order of the specified collation element, i.e.

void setOffset(int newOffset)

Points the iterator at the collation element associated with the character in the source string which is found at the supplied offset.

void setText(CharacterIterator source)

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

void setText(String source)

Sets a new source string for iteration, and resets the offset to the beginning of the text.

final static short tertiaryOrder(int order)

Returns the tertiary order of the specified collation element, i.e.

Inherited methods

From class java.lang.Object

Constants

NULLORDER

Added in API level 1
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.

Constant Value: -1 (0xffffffff)

Public methods

getMaxExpansion

Added in API level 1
int getMaxExpansion (int order)

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

Parameters
order int: a collation element that has been previously obtained from a call to either the next() or previous() method.
Returns
int

getOffset

Added in API level 1
int getOffset ()

Returns the character offset in the source string corresponding to the next collation element. This value could be any of:

  • The index of the first character in the source string that matches the value of 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

next

Added in API level 1
int next ()

Returns the next collation element in the source string or NULLORDER if the end of the iteration has been reached.

Returns
int

previous

Added in API level 1
int previous ()

Returns the previous collation element in the source string or NULLORDER if the start of the iteration has been reached.

Returns
int

primaryOrder

Added in API level 1
int primaryOrder (int order)

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

Parameters
order int: the element of the collation.
Returns
int

reset

Added in API level 1
void reset ()

Repositions the cursor to point at the first element of the current 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() reinitializes the iterator to use the new attributes.

secondaryOrder

Added in API level 1
short secondaryOrder (int order)

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

Parameters
order int: the element of the collator.
Returns
short

setOffset

Added in API level 1
void setOffset (int newOffset)

Points the iterator at the collation element associated with the character in the source string which is found at the supplied offset. After this call completes, an invocation of the next() method will return this collation element.

If newOffset corresponds to a character which is part of a sequence that maps to a single collation element then the iterator is adjusted to the start of that sequence. As a result of this, any subsequent call made to getOffset() may not return the same value set by this method.

If the decomposition mode is on, and offset is in the middle of a decomposable 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 decomposable 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.

setText

Added in API level 1
void setText (CharacterIterator source)

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

Parameters
source CharacterIterator: the new source string iterator for iteration.

setText

Added in API level 1
void setText (String source)

Sets a new source string for iteration, and resets the offset to the beginning of the text.

Parameters
source String: the new source string for iteration.

tertiaryOrder

Added in API level 1
short tertiaryOrder (int order)

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

Parameters
order int: the element of the collation.
Returns
short
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.