Added in API level 29

Iterator


class Iterator
kotlin.Any
   ↳ android.icu.text.Edits.Iterator

Access to the list of edits.

At any moment in time, an instance of this class points to a single edit: a "window" into a span of the source string and the corresponding span of the destination string. The source string span starts at sourceIndex() and runs for oldLength() chars; the destination string span starts at destinationIndex() and runs for newLength() chars.

The iterator can be moved between edits using the next(), findSourceIndex(int), and findDestinationIndex(int) methods. Calling any of these methods mutates the iterator to make it point to the corresponding edit.

For more information, see the documentation for Edits.

Note: Although this class is called "Iterator", it does not implement java.util.Iterator.

Summary

Public methods
Int

The start index of the current span in the destination string; the span has length newLength.

Int

Computes the destination index corresponding to the given source index.

Boolean

Moves the iterator to the edit that contains the destination index.

Boolean

Moves the iterator to the edit that contains the source index.

Boolean

Returns whether the edit currently represented by the iterator is a change edit.

Int

The length of the current span in the destination string, which starts at destinationIndex, or in the replacement string, which starts at replacementIndex.

Boolean

Advances the iterator to the next edit.

Int

The length of the current span in the source string, which starts at sourceIndex.

Int

The start index of the current span in the replacement string; the span has length newLength.

Int

The start index of the current span in the source string; the span has length oldLength.

Int

Computes the source index corresponding to the given destination index.

String

A string representation of the current edit represented by the iterator for debugging.

Public methods

destinationIndex

Added in API level 29
fun destinationIndex(): Int

The start index of the current span in the destination string; the span has length newLength.

Return
Int the current index into the full destination string

destinationIndexFromSourceIndex

Added in API level 29
fun destinationIndexFromSourceIndex(i: Int): Int

Computes the destination index corresponding to the given source index. If the source index is inside a change edit (not at its start), then the destination index at the end of that edit is returned, since there is no information about index mapping inside a change edit.

(This means that indexes to the start and middle of an edit, for example around a grapheme cluster, are mapped to indexes encompassing the entire edit. The alternative, mapping an interior index to the start, would map such an interval to an empty one.)

This operation will usually but not always modify this object. The iterator state after this search is undefined.

Parameters
i Int: source index
Return
Int destination index; undefined if i is not 0..string length

findDestinationIndex

Added in API level 29
fun findDestinationIndex(i: Int): Boolean

Moves the iterator to the edit that contains the destination index. The destination index may be found in a no-change edit even if normal iteration would skip no-change edits. Normal iteration can continue from a found edit.

The iterator state before this search logically does not matter. (It may affect the performance of the search.)

The iterator state after this search is undefined if the source index is out of bounds for the source string.

Parameters
i Int: destination index
Return
Boolean true if the edit for the destination index was found

findSourceIndex

Added in API level 29
fun findSourceIndex(i: Int): Boolean

Moves the iterator to the edit that contains the source index. The source index may be found in a no-change edit even if normal iteration would skip no-change edits. Normal iteration can continue from a found edit.

The iterator state before this search logically does not matter. (It may affect the performance of the search.)

The iterator state after this search is undefined if the source index is out of bounds for the source string.

Parameters
i Int: source index
Return
Boolean true if the edit for the source index was found

hasChange

Added in API level 29
fun hasChange(): Boolean

Returns whether the edit currently represented by the iterator is a change edit.

Return
Boolean true if this edit replaces oldLength() units with newLength() different ones. false if oldLength units remain unchanged.

newLength

Added in API level 29
fun newLength(): Int

The length of the current span in the destination string, which starts at destinationIndex, or in the replacement string, which starts at replacementIndex.

Return
Int the number of units in the destination string, if hasChange() is true. Same as oldLength if hasChange() is false.

next

Added in API level 29
fun next(): Boolean

Advances the iterator to the next edit.

Return
Boolean true if there is another edit

oldLength

Added in API level 29
fun oldLength(): Int

The length of the current span in the source string, which starts at sourceIndex.

Return
Int the number of units in the source string which are replaced or remain unchanged.

replacementIndex

Added in API level 29
fun replacementIndex(): Int

The start index of the current span in the replacement string; the span has length newLength. Well-defined only if the current edit is a change edit.

The replacement string is the concatenation of all substrings of the destination string corresponding to change edits.

This method is intended to be used together with operations that write only replacement characters (e.g., CaseMap#omitUnchangedText()). The source string can then be modified in-place.

Return
Int the current index into the replacement-characters-only string, not counting unchanged spans

sourceIndex

Added in API level 29
fun sourceIndex(): Int

The start index of the current span in the source string; the span has length oldLength.

Return
Int the current index into the source string

sourceIndexFromDestinationIndex

Added in API level 29
fun sourceIndexFromDestinationIndex(i: Int): Int

Computes the source index corresponding to the given destination index. If the destination index is inside a change edit (not at its start), then the source index at the end of that edit is returned, since there is no information about index mapping inside a change edit.

(This means that indexes to the start and middle of an edit, for example around a grapheme cluster, are mapped to indexes encompassing the entire edit. The alternative, mapping an interior index to the start, would map such an interval to an empty one.)

This operation will usually but not always modify this object. The iterator state after this search is undefined.

Parameters
i Int: destination index
Return
Int source index; undefined if i is not 0..string length

toString

Added in API level 29
fun toString(): String

A string representation of the current edit represented by the iterator for debugging. You should not depend on the contents of the return string; it may change over time.

Return
String a string representation of the object.