Function type declaration for UCharIterator.getState().
Get the "state" of the iterator in the form of a single 32-bit word. It is recommended that the state value be calculated to be as small as is feasible. For strings with limited lengths, fewer than 32 bits may be sufficient.
This is used together with setState()/UCharIteratorSetState to save and restore the iterator position more efficiently than with getIndex()/move().
The iterator state is defined as a uint32_t value because it is designed for use in ucol_nextSortKeyPart() which provides 32 bits to store the state of the character iterator.
With some UCharIterator implementations (e.g., UTF-8), getting and setting the UTF-16 index with existing functions (getIndex(UITER_CURRENT) followed by move(pos, UITER_ZERO)) is possible but relatively slow because the iterator has to "walk" from a known index to the requested one. This takes more time the farther it needs to go.
An opaque state value allows an iterator implementation to provide an internal index (UTF-8: the source byte array index) for fast, constant-time restoration.
After calling setState(), a getIndex(UITER_CURRENT) may be slow because the UTF-16 index may not be restored as well, but the iterator can deliver the correct text contents and move relative to the current position without performance degradation.
Some UCharIterator implementations may not be able to return a valid state for each position, in which case they return UITER_NO_STATE instead. This will be clearly documented for each such iterator (none of the public ones here).