ICU 76.1: UCharIterator Struct Reference

ICU 76.1 76.1

Data Fields
UCharIterator Struct Reference

C API for code unit iteration. More...

`#include <uiter.h>`

## Data Fields
const void * | context
| (protected) Pointer to string or wrapped object or similar.
int32_t | length
| (protected) Length of string or similar.
int32_t | start
| (protected) Start index or similar.
int32_t | index
| (protected) Current index or similar.
int32_t | limit
| (protected) Limit index or similar.
int32_t | reservedField
| (protected) Used by UTF-8 iterators and possibly others.
UCharIteratorGetIndex * | getIndex
| (public) Returns the current position or the start or limit index of the iteration range.
UCharIteratorMove * | move
| (public) Moves the current position relative to the start or limit of the iteration range, or relative to the current position itself.
UCharIteratorHasNext * | hasNext
| (public) Check if current() and next() can still return another code unit.
UCharIteratorHasPrevious * | hasPrevious
| (public) Check if previous() can still return another code unit.
UCharIteratorCurrent * | current
| (public) Return the code unit at the current position, or U_SENTINEL if there is none (index is at the limit).
UCharIteratorNext * | next
| (public) Return the code unit at the current index and increment the index (post-increment, like s[i++]), or return U_SENTINEL if there is none (index is at the limit).
UCharIteratorPrevious * | previous
| (public) Decrement the index and return the code unit from there (pre-decrement, like s[–i]), or return U_SENTINEL if there is none (index is at the start).
UCharIteratorReserved * | reservedFn
| (public) Reserved for future use.
UCharIteratorGetState * | getState
| (public) Return the state of the iterator, to be restored later with setState().
UCharIteratorSetState * | setState
| (public) Restore the iterator state from the state word from a call to getState().

## Detailed Description

C API for code unit iteration.

This can be used as a C wrapper around CharacterIterator, Replaceable, or implemented using simple strings, etc.

There are two roles for using UCharIterator:

A "provider" sets the necessary function pointers and controls the "protected" fields of the UCharIterator structure. A "provider" passes a UCharIterator into C APIs that need a UCharIterator as an abstract, flexible string interface.

Implementations of such C APIs are "callers" of UCharIterator functions; they only use the "public" function pointers and never access the "protected" fields directly.

The current() and next() functions only check the current index against the limit, and previous() only checks the current index against the start, to see if the iterator already reached the end of the iteration range.

The assumption - in all iterators - is that the index is moved via the API, which means it won't go out of bounds, or the index is modified by user code that knows enough about the iterator implementation to set valid index values.

UCharIterator functions return code unit values 0..0xffff, or U_SENTINEL if the iteration bounds are reached.

Stable
  ICU 2.1

Definition at line 341 of file uiter.h.

## Field Documentation

## ◆ context

const void* UCharIterator::context

(protected) Pointer to string or wrapped object or similar.

Not used by caller.

Stable
  ICU 2.1

Definition at line 347 of file uiter.h.

## ◆ current

UCharIteratorCurrent* UCharIterator::current

(public) Return the code unit at the current position, or U_SENTINEL if there is none (index is at the limit).

See also
  UCharIteratorCurrent

Stable
  ICU 2.1

Definition at line 427 of file uiter.h.

## ◆ getIndex

UCharIteratorGetIndex* UCharIterator::getIndex

(public) Returns the current position or the start or limit index of the iteration range.

See also
  UCharIteratorGetIndex

Stable
  ICU 2.1

Definition at line 390 of file uiter.h.

## ◆ getState

UCharIteratorGetState* UCharIterator::getState

(public) Return the state of the iterator, to be restored later with setState().

This function pointer is NULL if the iterator does not implement it.

See also
  UCharIteratorGet

Stable
  ICU 2.6

Definition at line 464 of file uiter.h.

## ◆ hasNext

UCharIteratorHasNext* UCharIterator::hasNext

(public) Check if current() and next() can still return another code unit.

See also
  UCharIteratorHasNext

Stable
  ICU 2.1

Definition at line 410 of file uiter.h.

## ◆ hasPrevious

UCharIteratorHasPrevious* UCharIterator::hasPrevious

(public) Check if previous() can still return another code unit.

See also
  UCharIteratorHasPrevious

Stable
  ICU 2.1

Definition at line 418 of file uiter.h.

## ◆ index

int32_t UCharIterator::index

(protected) Current index or similar.

Not used by caller.

Stable
  ICU 2.1

Definition at line 368 of file uiter.h.

## ◆ length

int32_t UCharIterator::length

(protected) Length of string or similar.

Not used by caller.

Stable
  ICU 2.1

Definition at line 354 of file uiter.h.

## ◆ limit

int32_t UCharIterator::limit

(protected) Limit index or similar.

Not used by caller.

Stable
  ICU 2.1

Definition at line 375 of file uiter.h.

## ◆ move

UCharIteratorMove* UCharIterator::move

(public) Moves the current position relative to the start or limit of the iteration range, or relative to the current position itself.

The movement is expressed in numbers of code units forward or backward by specifying a positive or negative delta.

See also
  UCharIteratorMove

Stable
  ICU 2.1

Definition at line 401 of file uiter.h.

## ◆ next

UCharIteratorNext* UCharIterator::next

(public) Return the code unit at the current index and increment the index (post-increment, like s[i++]), or return U_SENTINEL if there is none (index is at the limit).

See also
  UCharIteratorNext

Stable
  ICU 2.1

Definition at line 437 of file uiter.h.

## ◆ previous

UCharIteratorPrevious* UCharIterator::previous

(public) Decrement the index and return the code unit from there (pre-decrement, like s[–i]), or return U_SENTINEL if there is none (index is at the start).

See also
  UCharIteratorPrevious

Stable
  ICU 2.1

Definition at line 447 of file uiter.h.

## ◆ reservedField

int32_t UCharIterator::reservedField

(protected) Used by UTF-8 iterators and possibly others.

Stable
  ICU 2.1

Definition at line 381 of file uiter.h.

## ◆ reservedFn

UCharIteratorReserved* UCharIterator::reservedFn

(public) Reserved for future use.

Currently NULL.

See also
  UCharIteratorReserved

Stable
  ICU 2.1

Definition at line 455 of file uiter.h.

## ◆ setState

UCharIteratorSetState* UCharIterator::setState

(public) Restore the iterator state from the state word from a call to getState().

This function pointer is NULL if the iterator does not implement it.

See also
  UCharIteratorSet

Stable
  ICU 2.6

Definition at line 474 of file uiter.h.

## ◆ start

int32_t UCharIterator::start

(protected) Start index or similar.

Not used by caller.

Stable
  ICU 2.1

Definition at line 361 of file uiter.h.

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

- common/unicode/uiter.h