ICU 76.1: icu::Edits::Iterator Struct Reference

ICU 76.1 76.1

Public Member Functions | Friends
icu::Edits::Iterator Struct Referencefinal

Access to the list of edits. More...

`#include <edits.h>`

Inheritance diagram for icu::Edits::Iterator:

## Public Member Functions
| Iterator ()
| Default constructor, empty iterator.
| Iterator (const Iterator &other)=default
| Copy constructor.
Iterator & | operator= (const Iterator &other)=default
| Assignment operator.
UBool | next (UErrorCode &errorCode)
| Advances the iterator to the next edit.
UBool | findSourceIndex (int32_t i, UErrorCode &errorCode)
| Moves the iterator to the edit that contains the source index.
UBool | findDestinationIndex (int32_t i, UErrorCode &errorCode)
| Moves the iterator to the edit that contains the destination index.
int32_t | destinationIndexFromSourceIndex (int32_t i, UErrorCode &errorCode)
| Computes the destination index corresponding to the given source index.
int32_t | sourceIndexFromDestinationIndex (int32_t i, UErrorCode &errorCode)
| Computes the source index corresponding to the given destination index.
UBool | hasChange () const
| Returns whether the edit currently represented by the iterator is a change edit.
int32_t | oldLength () const
| The length of the current span in the source string, which starts at `sourceIndex`.
int32_t | newLength () const
| The length of the current span in the destination string, which starts at `destinationIndex`, or in the replacement string, which starts at `replacementIndex`.
int32_t | sourceIndex () const
| The start index of the current span in the source string; the span has length `oldLength`.
int32_t | replacementIndex () const
| The start index of the current span in the replacement string; the span has length `newLength`.
int32_t | destinationIndex () const
| The start index of the current span in the destination string; the span has length `newLength`.
UnicodeString & | toString (UnicodeString &appendTo) const
| A string representation of the current edit represented by the iterator for debugging.

## Friends
class | Edits

## Detailed Description

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(int32_t, UErrorCode &)`, and `findDestinationIndex(int32_t, UErrorCode &)` 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`.

See also
  getCoarseIterator
  getFineIterator

Stable
  ICU 59

Definition at line 203 of file edits.h.

## Constructor & Destructor Documentation

## ◆ Iterator() [1/2]

icu::Edits::Iterator::Iterator | ( |  | ) |
| inline

Default constructor, empty iterator.

Stable
  ICU 60

Definition at line 208 of file edits.h.

## ◆ Iterator() [2/2]

icu::Edits::Iterator::Iterator | ( | const Iterator & | other | ) |
| default

Copy constructor.

Stable
  ICU 59

## Member Function Documentation

## ◆ destinationIndex()

int32_t icu::Edits::Iterator::destinationIndex | ( |  | ) | const
| inline

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

Returns
  the current index into the full destination string

Stable
  ICU 59

Definition at line 392 of file edits.h.

## ◆ destinationIndexFromSourceIndex()

int32_t icu::Edits::Iterator::destinationIndexFromSourceIndex | ( | int32_t | i,
|  | UErrorCode & | errorCode )

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 | source index
  errorCode | ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns
  destination index; undefined if i is not 0..string length

Stable
  ICU 60

## ◆ findDestinationIndex()

UBool icu::Edits::Iterator::findDestinationIndex | ( | int32_t | i,
|  | UErrorCode & | errorCode )
| inline

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 | destination index
  errorCode | ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns
  true if the edit for the destination index was found

Stable
  ICU 60

Definition at line 276 of file edits.h.

## ◆ findSourceIndex()

UBool icu::Edits::Iterator::findSourceIndex | ( | int32_t | i,
|  | UErrorCode & | errorCode )
| inline

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 | source index
  errorCode | ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns
  true if the edit for the source index was found

Stable
  ICU 59

Definition at line 253 of file edits.h.

## ◆ hasChange()

UBool icu::Edits::Iterator::hasChange | ( |  | ) | const
| inline

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

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

Stable
  ICU 59

Definition at line 335 of file edits.h.

## ◆ newLength()

int32_t icu::Edits::Iterator::newLength | ( |  | ) | const
| inline

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

Returns
  the number of units in the modified string, if hasChange() is true. Same as oldLength if hasChange() is false.

Stable
  ICU 59

Definition at line 354 of file edits.h.

## ◆ next()

UBool icu::Edits::Iterator::next | ( | UErrorCode & | errorCode | ) |
| inline

Advances the iterator to the next edit.

Parameters

  errorCode | ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns
  true if there is another edit

Stable
  ICU 59

Definition at line 232 of file edits.h.

References next().

Referenced by next().

## ◆ oldLength()

int32_t icu::Edits::Iterator::oldLength | ( |  | ) | const
| inline

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

Returns
  the number of units in the original string which are replaced or remain unchanged.

Stable
  ICU 59

Definition at line 343 of file edits.h.

## ◆ operator=()

Iterator & icu::Edits::Iterator::operator= | ( | const Iterator & | other | ) |
| default

Assignment operator.

Stable
  ICU 59

## ◆ replacementIndex()

int32_t icu::Edits::Iterator::replacementIndex | ( |  | ) | const
| inline

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. operations specifying the U_OMIT_UNCHANGED_TEXT option). The source string can then be modified in-place.

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

Stable
  ICU 59

Definition at line 380 of file edits.h.

## ◆ sourceIndex()

int32_t icu::Edits::Iterator::sourceIndex | ( |  | ) | const
| inline

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

Returns
  the current index into the source string

Stable
  ICU 59

Definition at line 363 of file edits.h.

## ◆ sourceIndexFromDestinationIndex()

int32_t icu::Edits::Iterator::sourceIndexFromDestinationIndex | ( | int32_t | i,
|  | UErrorCode & | errorCode )

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 | destination index
  errorCode | ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns
  source index; undefined if i is not 0..string length

Stable
  ICU 60

## ◆ toString()

UnicodeString & icu::Edits::Iterator::toString | ( | UnicodeString & | appendTo | ) | const

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

You should not depend on the contents of the return string.

Internal
  Do not use. This API is for internal use only.

## Friends And Related Symbol Documentation

## ◆ Edits

friend class Edits
| friend

Definition at line 404 of file edits.h.

The documentation for this struct was generated from the following file:

- common/unicode/edits.h