How to use

CollationElementIteratorICU

in

libcore.icu

public static CollationElementIteratorICU getInstance(long collatorAddress, String source) {
  long iteratorAddress = NativeCollation.getCollationElementIterator(collatorAddress, source);
  return new CollationElementIteratorICU(iteratorAddress);
}

public CollationElementIteratorICU getCollationElementIterator(String source) {
  return CollationElementIteratorICU.getInstance(address, source);
}

/**
 * Obtains the maximum length of any expansion sequence that ends with the
 * specified collation element. Returns {@code 1} if there is no expansion
 * with this collation element as the last element.
 *
 * @param order
 *            a collation element that has been previously obtained from a
 *            call to either the {@link #next()} or {@link #previous()}
 *            method.
 * @return the maximum length of any expansion sequence ending with the
 *         specified collation element.
 */
public int getMaxExpansion(int order) {
  return this.icuIterator.getMaxExpansion(order);
}

/**
 * Obtains the primary order of the specified collation element, i.e. the
 * first 16 bits. This value is unsigned.
 *
 * @param order
 *            the element of the collation.
 * @return the element's 16 bit primary order.
 */
public static final int primaryOrder(int order) {
  return CollationElementIteratorICU.primaryOrder(order);
}

/**
 * Obtains the secondary order of the specified collation element, i.e. the
 * 16th to 23th bits, inclusive. This value is unsigned.
 *
 * @param order
 *            the element of the collator.
 * @return the 8 bit secondary order of the element.
 */
public static final short secondaryOrder(int order) {
  return (short) CollationElementIteratorICU.secondaryOrder(order);
}

/**
 * Obtains the next collation element in the source string.
 *
 * @return the next collation element or {@code NULLORDER} if the end
 *         of the iteration has been reached.
 */
public int next() {
  return this.icuIterator.next();
}

/**
 * Repositions the cursor to point at the first element of the current
 * string. The next call to {@link #next()} or {@link #previous()} will
 * return the first and last collation element in the string, respectively.
 * <p>
 * If the {@code RuleBasedCollator} used by this iterator has had its
 * attributes changed, calling {@code reset()} reinitializes the iterator to
 * use the new attributes.
 */
public void reset() {
  this.icuIterator.reset();
}

/**
 * Obtains the previous collation element in the source string.
 *
 * @return the previous collation element, or {@code NULLORDER} when
 *         the start of the iteration has been reached.
 */
public int previous() {
  return this.icuIterator.previous();
}

/**
 * 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 {@link #next()} method
 * will return this collation element.
 * <p>
 * If {@code 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 {@code getOffset()} may not return the same value
 * set by this method.
 * <p>
 * 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.
 *
 * @param newOffset
 *            the character offset into the original source string to set.
 *            Note that this is not an offset into the corresponding
 *            sequence of collation elements.
 */
public void setOffset(int newOffset) {
  this.icuIterator.setOffset(newOffset);
}

/**
 * Obtains the character offset in the source string corresponding to the
 * next collation element. This value could be any of:
 * <ul>
 * <li>The index of the first character in the source string that matches
 * the value of the next collation element. This means that if
 * {@code setOffset(offset)} sets the index in the middle of a contraction,
 * {@code 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 {@code getOffset()} immediately after
 * {@code setOffset(offset)} does not guarantee that the original offset set
 * will be returned.</li>
 * <li>If normalization is on, the index of the immediate subsequent
 * character, or composite character with the first character, having a
 * combining class of 0.</li>
 * <li>The length of the source string, if iteration has reached the end.
 * </li>
 * </ul>
 *
 * @return The position of the collation element in the source string that
 *         will be returned by the next invocation of the {@link #next()}
 *         method.
 */
public int getOffset() {
  return this.icuIterator.getOffset();
}

/**
 * Obtains the primary order of the specified collation element, i.e. the
 * first 16 bits. This value is unsigned.
 *
 * @param order
 *            the element of the collation.
 * @return the element's 16 bit primary order.
 */
public static final int primaryOrder(int order) {
  return CollationElementIteratorICU.primaryOrder(order);
}

/**
 * Obtains the secondary order of the specified collation element, i.e. the
 * 16th to 23th bits, inclusive. This value is unsigned.
 *
 * @param order
 *            the element of the collator.
 * @return the 8 bit secondary order of the element.
 */
public static final short secondaryOrder(int order) {
  return (short) CollationElementIteratorICU.secondaryOrder(order);
}

/**
 * Obtains the next collation element in the source string.
 *
 * @return the next collation element or {@code NULLORDER} if the end
 *         of the iteration has been reached.
 */
public int next() {
  return this.icuIterator.next();
}

/**
 * Repositions the cursor to point at the first element of the current
 * string. The next call to {@link #next()} or {@link #previous()} will
 * return the first and last collation element in the string, respectively.
 * <p>
 * If the {@code RuleBasedCollator} used by this iterator has had its
 * attributes changed, calling {@code reset()} reinitializes the iterator to
 * use the new attributes.
 */
public void reset() {
  this.icuIterator.reset();
}

/**
 * Obtains the previous collation element in the source string.
 *
 * @return the previous collation element, or {@code NULLORDER} when
 *         the start of the iteration has been reached.
 */
public int previous() {
  return this.icuIterator.previous();
}

/**
 * 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 {@link #next()} method
 * will return this collation element.
 * <p>
 * If {@code 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 {@code getOffset()} may not return the same value
 * set by this method.
 * <p>
 * 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.
 *
 * @param newOffset
 *            the character offset into the original source string to set.
 *            Note that this is not an offset into the corresponding
 *            sequence of collation elements.
 */
public void setOffset(int newOffset) {
  this.icuIterator.setOffset(newOffset);
}

/**
 * Obtains the character offset in the source string corresponding to the
 * next collation element. This value could be any of:
 * <ul>
 * <li>The index of the first character in the source string that matches
 * the value of the next collation element. This means that if
 * {@code setOffset(offset)} sets the index in the middle of a contraction,
 * {@code 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 {@code getOffset()} immediately after
 * {@code setOffset(offset)} does not guarantee that the original offset set
 * will be returned.</li>
 * <li>If normalization is on, the index of the immediate subsequent
 * character, or composite character with the first character, having a
 * combining class of 0.</li>
 * <li>The length of the source string, if iteration has reached the end.
 * </li>
 * </ul>
 *
 * @return The position of the collation element in the source string that
 *         will be returned by the next invocation of the {@link #next()}
 *         method.
 */
public int getOffset() {
  return this.icuIterator.getOffset();
}

/**
 * Obtains the primary order of the specified collation element, i.e. the
 * first 16 bits. This value is unsigned.
 *
 * @param order
 *            the element of the collation.
 * @return the element's 16 bit primary order.
 */
public static final int primaryOrder(int order) {
  return CollationElementIteratorICU.primaryOrder(order);
}

/**
 * Obtains the secondary order of the specified collation element, i.e. the
 * 16th to 23th bits, inclusive. This value is unsigned.
 *
 * @param order
 *            the element of the collator.
 * @return the 8 bit secondary order of the element.
 */
public static final short secondaryOrder(int order) {
  return (short) CollationElementIteratorICU.secondaryOrder(order);
}

/**
 * Obtains the next collation element in the source string.
 *
 * @return the next collation element or {@code NULLORDER} if the end
 *         of the iteration has been reached.
 */
public int next() {
  return this.icuIterator.next();
}