icuSources/common/unicode/uiter.h

   1 // © 2016 and later: Unicode, Inc. and others.
   2 // License & terms of use: http://www.unicode.org/copyright.html
   3 /*
   4 *******************************************************************************
   5 *
   6 *   Copyright (C) 2002-2011 International Business Machines
   7 *   Corporation and others.  All Rights Reserved.
   8 *
   9 *******************************************************************************
  10 *   file name:  uiter.h
  11 *   encoding:   UTF-8
  12 *   tab size:   8 (not used)
  13 *   indentation:4
  14 *
  15 *   created on: 2002jan18
  16 *   created by: Markus W. Scherer
  17 */
  18
  19 #ifndef __UITER_H__
  20 #define __UITER_H__
  21
  22 /**
  23  * \file
  24  * \brief C API: Unicode Character Iteration
  25  *
  26  * @see UCharIterator
  27  */
  28
  29 #include "unicode/utypes.h"
  30
  31 #if U_SHOW_CPLUSPLUS_API
  32     U_NAMESPACE_BEGIN
  33
  34     class CharacterIterator;
  35     class Replaceable;
  36
  37     U_NAMESPACE_END
  38 #endif
  39
  40 U_CDECL_BEGIN
  41
  42 struct UCharIterator;
  43 typedef struct UCharIterator UCharIterator; /**< C typedef for struct UCharIterator. @stable ICU 2.1 */
  44
  45 /**
  46  * Origin constants for UCharIterator.getIndex() and UCharIterator.move().
  47  * @see UCharIteratorMove
  48  * @see UCharIterator
  49  * @stable ICU 2.1
  50  */
  51 typedef enum UCharIteratorOrigin {
  52     UITER_START, UITER_CURRENT, UITER_LIMIT, UITER_ZERO, UITER_LENGTH
  53 } UCharIteratorOrigin;
  54
  55 /** Constants for UCharIterator. @stable ICU 2.6 */
  56 enum {
  57     /**
  58      * Constant value that may be returned by UCharIteratorMove
  59      * indicating that the final UTF-16 index is not known, but that the move succeeded.
  60      * This can occur when moving relative to limit or length, or
  61      * when moving relative to the current index after a setState()
  62      * when the current UTF-16 index is not known.
  63      *
  64      * It would be very inefficient to have to count from the beginning of the text
  65      * just to get the current/limit/length index after moving relative to it.
  66      * The actual index can be determined with getIndex(UITER_CURRENT)
  67      * which will count the UChars if necessary.
  68      *
  69      * @stable ICU 2.6
  70      */
  71     UITER_UNKNOWN_INDEX=-2
  72 };
  73
  74
  75 /**
  76  * Constant for UCharIterator getState() indicating an error or
  77  * an unknown state.
  78  * Returned by uiter_getState()/UCharIteratorGetState
  79  * when an error occurs.
  80  * Also, some UCharIterator implementations may not be able to return
  81  * a valid state for each position. This will be clearly documented
  82  * for each such iterator (none of the public ones here).
  83  *
  84  * @stable ICU 2.6
  85  */
  86 #define UITER_NO_STATE ((uint32_t)0xffffffff)
  87
  88 /**
  89  * Function type declaration for UCharIterator.getIndex().
  90  *
  91  * Gets the current position, or the start or limit of the
  92  * iteration range.
  93  *
  94  * This function may perform slowly for UITER_CURRENT after setState() was called,
  95  * or for UITER_LENGTH, because an iterator implementation may have to count
  96  * UChars if the underlying storage is not UTF-16.
  97  *
  98  * @param iter the UCharIterator structure ("this pointer")
  99  * @param origin get the 0, start, limit, length, or current index
 100  * @return the requested index, or U_SENTINEL in an error condition
 101  *
 102  * @see UCharIteratorOrigin
 103  * @see UCharIterator
 104  * @stable ICU 2.1
 105  */
 106 typedef int32_t U_CALLCONV
 107 UCharIteratorGetIndex(UCharIterator *iter, UCharIteratorOrigin origin);
 108
 109 /**
 110  * Function type declaration for UCharIterator.move().
 111  *
 112  * Use iter->move(iter, index, UITER_ZERO) like CharacterIterator::setIndex(index).
 113  *
 114  * Moves the current position relative to the start or limit of the
 115  * iteration range, or relative to the current position itself.
 116  * The movement is expressed in numbers of code units forward
 117  * or backward by specifying a positive or negative delta.
 118  * Out of bounds movement will be pinned to the start or limit.
 119  *
 120  * This function may perform slowly for moving relative to UITER_LENGTH
 121  * because an iterator implementation may have to count the rest of the
 122  * UChars if the native storage is not UTF-16.
 123  *
 124  * When moving relative to the limit or length, or
 125  * relative to the current position after setState() was called,
 126  * move() may return UITER_UNKNOWN_INDEX (-2) to avoid an inefficient
 127  * determination of the actual UTF-16 index.
 128  * The actual index can be determined with getIndex(UITER_CURRENT)
 129  * which will count the UChars if necessary.
 130  * See UITER_UNKNOWN_INDEX for details.
 131  *
 132  * @param iter the UCharIterator structure ("this pointer")
 133  * @param delta can be positive, zero, or negative
 134  * @param origin move relative to the 0, start, limit, length, or current index
 135  * @return the new index, or U_SENTINEL on an error condition,
 136  *         or UITER_UNKNOWN_INDEX when the index is not known.
 137  *
 138  * @see UCharIteratorOrigin
 139  * @see UCharIterator
 140  * @see UITER_UNKNOWN_INDEX
 141  * @stable ICU 2.1
 142  */
 143 typedef int32_t U_CALLCONV
 144 UCharIteratorMove(UCharIterator *iter, int32_t delta, UCharIteratorOrigin origin);
 145
 146 /**
 147  * Function type declaration for UCharIterator.hasNext().
 148  *
 149  * Check if current() and next() can still
 150  * return another code unit.
 151  *
 152  * @param iter the UCharIterator structure ("this pointer")
 153  * @return boolean value for whether current() and next() can still return another code unit
 154  *
 155  * @see UCharIterator
 156  * @stable ICU 2.1
 157  */
 158 typedef UBool U_CALLCONV
 159 UCharIteratorHasNext(UCharIterator *iter);
 160
 161 /**
 162  * Function type declaration for UCharIterator.hasPrevious().
 163  *
 164  * Check if previous() can still return another code unit.
 165  *
 166  * @param iter the UCharIterator structure ("this pointer")
 167  * @return boolean value for whether previous() can still return another code unit
 168  *
 169  * @see UCharIterator
 170  * @stable ICU 2.1
 171  */
 172 typedef UBool U_CALLCONV
 173 UCharIteratorHasPrevious(UCharIterator *iter);
 174
 175 /**
 176  * Function type declaration for UCharIterator.current().
 177  *
 178  * Return the code unit at the current position,
 179  * or U_SENTINEL if there is none (index is at the limit).
 180  *
 181  * @param iter the UCharIterator structure ("this pointer")
 182  * @return the current code unit
 183  *
 184  * @see UCharIterator
 185  * @stable ICU 2.1
 186  */
 187 typedef UChar32 U_CALLCONV
 188 UCharIteratorCurrent(UCharIterator *iter);
 189
 190 /**
 191  * Function type declaration for UCharIterator.next().
 192  *
 193  * Return the code unit at the current index and increment
 194  * the index (post-increment, like s[i++]),
 195  * or return U_SENTINEL if there is none (index is at the limit).
 196  *
 197  * @param iter the UCharIterator structure ("this pointer")
 198  * @return the current code unit (and post-increment the current index)
 199  *
 200  * @see UCharIterator
 201  * @stable ICU 2.1
 202  */
 203 typedef UChar32 U_CALLCONV
 204 UCharIteratorNext(UCharIterator *iter);
 205
 206 /**
 207  * Function type declaration for UCharIterator.previous().
 208  *
 209  * Decrement the index and return the code unit from there
 210  * (pre-decrement, like s[--i]),
 211  * or return U_SENTINEL if there is none (index is at the start).
 212  *
 213  * @param iter the UCharIterator structure ("this pointer")
 214  * @return the previous code unit (after pre-decrementing the current index)
 215  *
 216  * @see UCharIterator
 217  * @stable ICU 2.1
 218  */
 219 typedef UChar32 U_CALLCONV
 220 UCharIteratorPrevious(UCharIterator *iter);
 221
 222 /**
 223  * Function type declaration for UCharIterator.reservedFn().
 224  * Reserved for future use.
 225  *
 226  * @param iter the UCharIterator structure ("this pointer")
 227  * @param something some integer argument
 228  * @return some integer
 229  *
 230  * @see UCharIterator
 231  * @stable ICU 2.1
 232  */
 233 typedef int32_t U_CALLCONV
 234 UCharIteratorReserved(UCharIterator *iter, int32_t something);
 235
 236 /**
 237  * Function type declaration for UCharIterator.getState().
 238  *
 239  * Get the "state" of the iterator in the form of a single 32-bit word.
 240  * It is recommended that the state value be calculated to be as small as
 241  * is feasible. For strings with limited lengths, fewer than 32 bits may
 242  * be sufficient.
 243  *
 244  * This is used together with setState()/UCharIteratorSetState
 245  * to save and restore the iterator position more efficiently than with
 246  * getIndex()/move().
 247  *
 248  * The iterator state is defined as a uint32_t value because it is designed
 249  * for use in ucol_nextSortKeyPart() which provides 32 bits to store the state
 250  * of the character iterator.
 251  *
 252  * With some UCharIterator implementations (e.g., UTF-8),
 253  * getting and setting the UTF-16 index with existing functions
 254  * (getIndex(UITER_CURRENT) followed by move(pos, UITER_ZERO)) is possible but
 255  * relatively slow because the iterator has to "walk" from a known index
 256  * to the requested one.
 257  * This takes more time the farther it needs to go.
 258  *
 259  * An opaque state value allows an iterator implementation to provide
 260  * an internal index (UTF-8: the source byte array index) for
 261  * fast, constant-time restoration.
 262  *
 263  * After calling setState(), a getIndex(UITER_CURRENT) may be slow because
 264  * the UTF-16 index may not be restored as well, but the iterator can deliver
 265  * the correct text contents and move relative to the current position
 266  * without performance degradation.
 267  *
 268  * Some UCharIterator implementations may not be able to return
 269  * a valid state for each position, in which case they return UITER_NO_STATE instead.
 270  * This will be clearly documented for each such iterator (none of the public ones here).
 271  *
 272  * @param iter the UCharIterator structure ("this pointer")
 273  * @return the state word
 274  *
 275  * @see UCharIterator
 276  * @see UCharIteratorSetState
 277  * @see UITER_NO_STATE
 278  * @stable ICU 2.6
 279  */
 280 typedef uint32_t U_CALLCONV
 281 UCharIteratorGetState(const UCharIterator *iter);
 282
 283 /**
 284  * Function type declaration for UCharIterator.setState().
 285  *
 286  * Restore the "state" of the iterator using a state word from a getState() call.
 287  * The iterator object need not be the same one as for which getState() was called,
 288  * but it must be of the same type (set up using the same uiter_setXYZ function)
 289  * and it must iterate over the same string
 290  * (binary identical regardless of memory address).
 291  * For more about the state word see UCharIteratorGetState.
 292  *
 293  * After calling setState(), a getIndex(UITER_CURRENT) may be slow because
 294  * the UTF-16 index may not be restored as well, but the iterator can deliver
 295  * the correct text contents and move relative to the current position
 296  * without performance degradation.
 297  *
 298  * @param iter the UCharIterator structure ("this pointer")
 299  * @param state the state word from a getState() call
 300  *              on a same-type, same-string iterator
 301  * @param pErrorCode Must be a valid pointer to an error code value,
 302  *                   which must not indicate a failure before the function call.
 303  *
 304  * @see UCharIterator
 305  * @see UCharIteratorGetState
 306  * @stable ICU 2.6
 307  */
 308 typedef void U_CALLCONV
 309 UCharIteratorSetState(UCharIterator *iter, uint32_t state, UErrorCode *pErrorCode);
 310
 311
 312 /**
 313  * C API for code unit iteration.
 314  * This can be used as a C wrapper around
 315  * CharacterIterator, Replaceable, or implemented using simple strings, etc.
 316  *
 317  * There are two roles for using UCharIterator:
 318  *
 319  * A "provider" sets the necessary function pointers and controls the "protected"
 320  * fields of the UCharIterator structure. A "provider" passes a UCharIterator
 321  * into C APIs that need a UCharIterator as an abstract, flexible string interface.
 322  *
 323  * Implementations of such C APIs are "callers" of UCharIterator functions;
 324  * they only use the "public" function pointers and never access the "protected"
 325  * fields directly.
 326  *
 327  * The current() and next() functions only check the current index against the
 328  * limit, and previous() only checks the current index against the start,
 329  * to see if the iterator already reached the end of the iteration range.
 330  *
 331  * The assumption - in all iterators - is that the index is moved via the API,
 332  * which means it won't go out of bounds, or the index is modified by
 333  * user code that knows enough about the iterator implementation to set valid
 334  * index values.
 335  *
 336  * UCharIterator functions return code unit values 0..0xffff,
 337  * or U_SENTINEL if the iteration bounds are reached.
 338  *
 339  * @stable ICU 2.1
 340  */
 341 struct UCharIterator {
 342     /**
 343      * (protected) Pointer to string or wrapped object or similar.
 344      * Not used by caller.
 345      * @stable ICU 2.1
 346      */
 347     const void *context;
 348
 349     /**
 350      * (protected) Length of string or similar.
 351      * Not used by caller.
 352      * @stable ICU 2.1
 353      */
 354     int32_t length;
 355
 356     /**
 357      * (protected) Start index or similar.
 358      * Not used by caller.
 359      * @stable ICU 2.1
 360      */
 361     int32_t start;
 362
 363     /**
 364      * (protected) Current index or similar.
 365      * Not used by caller.
 366      * @stable ICU 2.1
 367      */
 368     int32_t index;
 369
 370     /**
 371      * (protected) Limit index or similar.
 372      * Not used by caller.
 373      * @stable ICU 2.1
 374      */
 375     int32_t limit;
 376
 377     /**
 378      * (protected) Used by UTF-8 iterators and possibly others.
 379      * @stable ICU 2.1
 380      */
 381     int32_t reservedField;
 382
 383     /**
 384      * (public) Returns the current position or the
 385      * start or limit index of the iteration range.
 386      *
 387      * @see UCharIteratorGetIndex
 388      * @stable ICU 2.1
 389      */
 390     UCharIteratorGetIndex *getIndex;
 391
 392     /**
 393      * (public) Moves the current position relative to the start or limit of the
 394      * iteration range, or relative to the current position itself.
 395      * The movement is expressed in numbers of code units forward
 396      * or backward by specifying a positive or negative delta.
 397      *
 398      * @see UCharIteratorMove
 399      * @stable ICU 2.1
 400      */
 401     UCharIteratorMove *move;
 402
 403     /**
 404      * (public) Check if current() and next() can still
 405      * return another code unit.
 406      *
 407      * @see UCharIteratorHasNext
 408      * @stable ICU 2.1
 409      */
 410     UCharIteratorHasNext *hasNext;
 411
 412     /**
 413      * (public) Check if previous() can still return another code unit.
 414      *
 415      * @see UCharIteratorHasPrevious
 416      * @stable ICU 2.1
 417      */
 418     UCharIteratorHasPrevious *hasPrevious;
 419
 420     /**
 421      * (public) Return the code unit at the current position,
 422      * or U_SENTINEL if there is none (index is at the limit).
 423      *
 424      * @see UCharIteratorCurrent
 425      * @stable ICU 2.1
 426      */
 427     UCharIteratorCurrent *current;
 428
 429     /**
 430      * (public) Return the code unit at the current index and increment
 431      * the index (post-increment, like s[i++]),
 432      * or return U_SENTINEL if there is none (index is at the limit).
 433      *
 434      * @see UCharIteratorNext
 435      * @stable ICU 2.1
 436      */
 437     UCharIteratorNext *next;
 438
 439     /**
 440      * (public) Decrement the index and return the code unit from there
 441      * (pre-decrement, like s[--i]),
 442      * or return U_SENTINEL if there is none (index is at the start).
 443      *
 444      * @see UCharIteratorPrevious
 445      * @stable ICU 2.1
 446      */
 447     UCharIteratorPrevious *previous;
 448
 449     /**
 450      * (public) Reserved for future use. Currently NULL.
 451      *
 452      * @see UCharIteratorReserved
 453      * @stable ICU 2.1
 454      */
 455     UCharIteratorReserved *reservedFn;
 456
 457     /**
 458      * (public) Return the state of the iterator, to be restored later with setState().
 459      * This function pointer is NULL if the iterator does not implement it.
 460      *
 461      * @see UCharIteratorGet
 462      * @stable ICU 2.6
 463      */
 464     UCharIteratorGetState *getState;
 465
 466     /**
 467      * (public) Restore the iterator state from the state word from a call
 468      * to getState().
 469      * This function pointer is NULL if the iterator does not implement it.
 470      *
 471      * @see UCharIteratorSet
 472      * @stable ICU 2.6
 473      */
 474     UCharIteratorSetState *setState;
 475 };
 476
 477 /**
 478  * Helper function for UCharIterator to get the code point
 479  * at the current index.
 480  *
 481  * Return the code point that includes the code unit at the current position,
 482  * or U_SENTINEL if there is none (index is at the limit).
 483  * If the current code unit is a lead or trail surrogate,
 484  * then the following or preceding surrogate is used to form
 485  * the code point value.
 486  *
 487  * @param iter the UCharIterator structure ("this pointer")
 488  * @return the current code point
 489  *
 490  * @see UCharIterator
 491  * @see U16_GET
 492  * @see UnicodeString::char32At()
 493  * @stable ICU 2.1
 494  */
 495 U_STABLE UChar32 U_EXPORT2
 496 uiter_current32(UCharIterator *iter);
 497
 498 /**
 499  * Helper function for UCharIterator to get the next code point.
 500  *
 501  * Return the code point at the current index and increment
 502  * the index (post-increment, like s[i++]),
 503  * or return U_SENTINEL if there is none (index is at the limit).
 504  *
 505  * @param iter the UCharIterator structure ("this pointer")
 506  * @return the current code point (and post-increment the current index)
 507  *
 508  * @see UCharIterator
 509  * @see U16_NEXT
 510  * @stable ICU 2.1
 511  */
 512 U_STABLE UChar32 U_EXPORT2
 513 uiter_next32(UCharIterator *iter);
 514
 515 /**
 516  * Helper function for UCharIterator to get the previous code point.
 517  *
 518  * Decrement the index and return the code point from there
 519  * (pre-decrement, like s[--i]),
 520  * or return U_SENTINEL if there is none (index is at the start).
 521  *
 522  * @param iter the UCharIterator structure ("this pointer")
 523  * @return the previous code point (after pre-decrementing the current index)
 524  *
 525  * @see UCharIterator
 526  * @see U16_PREV
 527  * @stable ICU 2.1
 528  */
 529 U_STABLE UChar32 U_EXPORT2
 530 uiter_previous32(UCharIterator *iter);
 531
 532 /**
 533  * Get the "state" of the iterator in the form of a single 32-bit word.
 534  * This is a convenience function that calls iter->getState(iter)
 535  * if iter->getState is not NULL;
 536  * if it is NULL or any other error occurs, then UITER_NO_STATE is returned.
 537  *
 538  * Some UCharIterator implementations may not be able to return
 539  * a valid state for each position, in which case they return UITER_NO_STATE instead.
 540  * This will be clearly documented for each such iterator (none of the public ones here).
 541  *
 542  * @param iter the UCharIterator structure ("this pointer")
 543  * @return the state word
 544  *
 545  * @see UCharIterator
 546  * @see UCharIteratorGetState
 547  * @see UITER_NO_STATE
 548  * @stable ICU 2.6
 549  */
 550 U_STABLE uint32_t U_EXPORT2
 551 uiter_getState(const UCharIterator *iter);
 552
 553 /**
 554  * Restore the "state" of the iterator using a state word from a getState() call.
 555  * This is a convenience function that calls iter->setState(iter, state, pErrorCode)
 556  * if iter->setState is not NULL; if it is NULL, then U_UNSUPPORTED_ERROR is set.
 557  *
 558  * @param iter the UCharIterator structure ("this pointer")
 559  * @param state the state word from a getState() call
 560  *              on a same-type, same-string iterator
 561  * @param pErrorCode Must be a valid pointer to an error code value,
 562  *                   which must not indicate a failure before the function call.
 563  *
 564  * @see UCharIterator
 565  * @see UCharIteratorSetState
 566  * @stable ICU 2.6
 567  */
 568 U_STABLE void U_EXPORT2
 569 uiter_setState(UCharIterator *iter, uint32_t state, UErrorCode *pErrorCode);
 570
 571 /**
 572  * Set up a UCharIterator to iterate over a string.
 573  *
 574  * Sets the UCharIterator function pointers for iteration over the string s
 575  * with iteration boundaries start=index=0 and length=limit=string length.
 576  * The "provider" may set the start, index, and limit values at any time
 577  * within the range 0..length.
 578  * The length field will be ignored.
 579  *
 580  * The string pointer s is set into UCharIterator.context without copying
 581  * or reallocating the string contents.
 582  *
 583  * getState() simply returns the current index.
 584  * move() will always return the final index.
 585  *
 586  * @param iter UCharIterator structure to be set for iteration
 587  * @param s String to iterate over
 588  * @param length Length of s, or -1 if NUL-terminated
 589  *
 590  * @see UCharIterator
 591  * @stable ICU 2.1
 592  */
 593 U_STABLE void U_EXPORT2
 594 uiter_setString(UCharIterator *iter, const UChar *s, int32_t length);
 595
 596 /**
 597  * Set up a UCharIterator to iterate over a UTF-16BE string
 598  * (byte vector with a big-endian pair of bytes per UChar).
 599  *
 600  * Everything works just like with a normal UChar iterator (uiter_setString),
 601  * except that UChars are assembled from byte pairs,
 602  * and that the length argument here indicates an even number of bytes.
 603  *
 604  * getState() simply returns the current index.
 605  * move() will always return the final index.
 606  *
 607  * @param iter UCharIterator structure to be set for iteration
 608  * @param s UTF-16BE string to iterate over
 609  * @param length Length of s as an even number of bytes, or -1 if NUL-terminated
 610  *               (NUL means pair of 0 bytes at even index from s)
 611  *
 612  * @see UCharIterator
 613  * @see uiter_setString
 614  * @stable ICU 2.6
 615  */
 616 U_STABLE void U_EXPORT2
 617 uiter_setUTF16BE(UCharIterator *iter, const char *s, int32_t length);
 618
 619 /**
 620  * Set up a UCharIterator to iterate over a UTF-8 string.
 621  *
 622  * Sets the UCharIterator function pointers for iteration over the UTF-8 string s
 623  * with UTF-8 iteration boundaries 0 and length.
 624  * The implementation counts the UTF-16 index on the fly and
 625  * lazily evaluates the UTF-16 length of the text.
 626  *
 627  * The start field is used as the UTF-8 offset, the limit field as the UTF-8 length.
 628  * When the reservedField is not 0, then it contains a supplementary code point
 629  * and the UTF-16 index is between the two corresponding surrogates.
 630  * At that point, the UTF-8 index is behind that code point.
 631  *
 632  * The UTF-8 string pointer s is set into UCharIterator.context without copying
 633  * or reallocating the string contents.
 634  *
 635  * getState() returns a state value consisting of
 636  * - the current UTF-8 source byte index (bits 31..1)
 637  * - a flag (bit 0) that indicates whether the UChar position is in the middle
 638  *   of a surrogate pair
 639  *   (from a 4-byte UTF-8 sequence for the corresponding supplementary code point)
 640  *
 641  * getState() cannot also encode the UTF-16 index in the state value.
 642  * move(relative to limit or length), or
 643  * move(relative to current) after setState(), may return UITER_UNKNOWN_INDEX.
 644  *
 645  * @param iter UCharIterator structure to be set for iteration
 646  * @param s UTF-8 string to iterate over
 647  * @param length Length of s in bytes, or -1 if NUL-terminated
 648  *
 649  * @see UCharIterator
 650  * @stable ICU 2.6
 651  */
 652 U_STABLE void U_EXPORT2
 653 uiter_setUTF8(UCharIterator *iter, const char *s, int32_t length);
 654
 655 #if U_SHOW_CPLUSPLUS_API
 656
 657 /**
 658  * Set up a UCharIterator to wrap around a C++ CharacterIterator.
 659  *
 660  * Sets the UCharIterator function pointers for iteration using the
 661  * CharacterIterator charIter.
 662  *
 663  * The CharacterIterator pointer charIter is set into UCharIterator.context
 664  * without copying or cloning the CharacterIterator object.
 665  * The other "protected" UCharIterator fields are set to 0 and will be ignored.
 666  * The iteration index and boundaries are controlled by the CharacterIterator.
 667  *
 668  * getState() simply returns the current index.
 669  * move() will always return the final index.
 670  *
 671  * @param iter UCharIterator structure to be set for iteration
 672  * @param charIter CharacterIterator to wrap
 673  *
 674  * @see UCharIterator
 675  * @stable ICU 2.1
 676  */
 677 U_STABLE void U_EXPORT2
 678 uiter_setCharacterIterator(UCharIterator *iter, icu::CharacterIterator *charIter);
 679
 680 /**
 681  * Set up a UCharIterator to iterate over a C++ Replaceable.
 682  *
 683  * Sets the UCharIterator function pointers for iteration over the
 684  * Replaceable rep with iteration boundaries start=index=0 and
 685  * length=limit=rep->length().
 686  * The "provider" may set the start, index, and limit values at any time
 687  * within the range 0..length=rep->length().
 688  * The length field will be ignored.
 689  *
 690  * The Replaceable pointer rep is set into UCharIterator.context without copying
 691  * or cloning/reallocating the Replaceable object.
 692  *
 693  * getState() simply returns the current index.
 694  * move() will always return the final index.
 695  *
 696  * @param iter UCharIterator structure to be set for iteration
 697  * @param rep Replaceable to iterate over
 698  *
 699  * @see UCharIterator
 700  * @stable ICU 2.1
 701  */
 702 U_STABLE void U_EXPORT2
 703 uiter_setReplaceable(UCharIterator *iter, const icu::Replaceable *rep);
 704
 705 #endif
 706
 707 U_CDECL_END
 708
 709 #endif