icuSources/i18n/unicode/usearch.h

   1 /*
   2 **********************************************************************
   3 *   Copyright (C) 2001-2005 IBM and others. All rights reserved.
   4 **********************************************************************
   5 *   Date        Name        Description
   6 *  06/28/2001   synwee      Creation.
   7 **********************************************************************
   8 */
   9 #ifndef USEARCH_H
  10 #define USEARCH_H
  11
  12 #include "unicode/utypes.h"
  13
  14 #if !UCONFIG_NO_COLLATION
  15
  16 #include "unicode/ucol.h"
  17 #include "unicode/ucoleitr.h"
  18 #include "unicode/ubrk.h"
  19
  20 /**
  21  * \file
  22  * \brief C API: StringSearch
  23  *
  24  * C Apis for an engine that provides language-sensitive text searching based
  25  * on the comparison rules defined in a <tt>UCollator</tt> data struct,
  26  * see <tt>ucol.h</tt>. This ensures that language eccentricity can be
  27  * handled, e.g. for the German collator, characters &szlig; and SS will be matched
  28  * if case is chosen to be ignored.
  29  * See the <a href="http://dev.icu-project.org/cgi-bin/viewcvs.cgi/~checkout~/icuhtml/design/collation/ICU_collation_design.htm">
  30  * "ICU Collation Design Document"</a> for more information.
  31  * <p>
  32  * The algorithm implemented is a modified form of the Boyer Moore's search.
  33  * For more information  see
  34  * <a href="http://icu.sourceforge.net/docs/papers/efficient_text_searching_in_java.html">
  35  * "Efficient Text Searching in Java"</a>, published in <i>Java Report</i>
  36  * in February, 1999, for further information on the algorithm.
  37  * <p>
  38  * There are 2 match options for selection:<br>
  39  * Let S' be the sub-string of a text string S between the offsets start and
  40  * end <start, end>.
  41  * <br>
  42  * A pattern string P matches a text string S at the offsets <start, end>
  43  * if
  44  * <pre>
  45  * option 1. Some canonical equivalent of P matches some canonical equivalent
  46  *           of S'
  47  * option 2. P matches S' and if P starts or ends with a combining mark,
  48  *           there exists no non-ignorable combining mark before or after S'
  49  *           in S respectively.
  50  * </pre>
  51  * Option 2. will be the default.
  52  * <p>
  53  * This search has APIs similar to that of other text iteration mechanisms
  54  * such as the break iterators in <tt>ubrk.h</tt>. Using these
  55  * APIs, it is easy to scan through text looking for all occurances of
  56  * a given pattern. This search iterator allows changing of direction by
  57  * calling a <tt>reset</tt> followed by a <tt>next</tt> or <tt>previous</tt>.
  58  * Though a direction change can occur without calling <tt>reset</tt> first,
  59  * this operation comes with some speed penalty.
  60  * Generally, match results in the forward direction will match the result
  61  * matches in the backwards direction in the reverse order
  62  * <p>
  63  * <tt>usearch.h</tt> provides APIs to specify the starting position
  64  * within the text string to be searched, e.g. <tt>usearch_setOffset</tt>,
  65  * <tt>usearch_preceding</tt> and <tt>usearch_following</tt>. Since the
  66  * starting position will be set as it is specified, please take note that
  67  * there are some dangerous positions which the search may render incorrect
  68  * results:
  69  * <ul>
  70  * <li> The midst of a substring that requires normalization.
  71  * <li> If the following match is to be found, the position should not be the
  72  *      second character which requires to be swapped with the preceding
  73  *      character. Vice versa, if the preceding match is to be found,
  74  *      position to search from should not be the first character which
  75  *      requires to be swapped with the next character. E.g certain Thai and
  76  *      Lao characters require swapping.
  77  * <li> If a following pattern match is to be found, any position within a
  78  *      contracting sequence except the first will fail. Vice versa if a
  79  *      preceding pattern match is to be found, a invalid starting point
  80  *      would be any character within a contracting sequence except the last.
  81  * </ul>
  82  * <p>
  83  * A breakiterator can be used if only matches at logical breaks are desired.
  84  * Using a breakiterator will only give you results that exactly matches the
  85  * boundaries given by the breakiterator. For instance the pattern "e" will
  86  * not be found in the string "\u00e9" if a character break iterator is used.
  87  * <p>
  88  * Options are provided to handle overlapping matches.
  89  * E.g. In English, overlapping matches produces the result 0 and 2
  90  * for the pattern "abab" in the text "ababab", where else mutually
  91  * exclusive matches only produce the result of 0.
  92  * <p>
  93  * Though collator attributes will be taken into consideration while
  94  * performing matches, there are no APIs here for setting and getting the
  95  * attributes. These attributes can be set by getting the collator
  96  * from <tt>usearch_getCollator</tt> and using the APIs in <tt>ucol.h</tt>.
  97  * Lastly to update String Search to the new collator attributes,
  98  * usearch_reset() has to be called.
  99  * <p>
 100  * Restriction: <br>
 101  * Currently there are no composite characters that consists of a
 102  * character with combining class > 0 before a character with combining
 103  * class == 0. However, if such a character exists in the future, the
 104  * search mechanism does not guarantee the results for option 1.
 105  *
 106  * <p>
 107  * Example of use:<br>
 108  * <pre><code>
 109  * char *tgtstr = "The quick brown fox jumped over the lazy fox";
 110  * char *patstr = "fox";
 111  * UChar target[64];
 112  * UChar pattern[16];
 113  * UErrorCode status = U_ZERO_ERROR;
 114  * u_uastrcpy(target, tgtstr);
 115  * u_uastrcpy(pattern, patstr);
 116  *
 117  * UStringSearch *search = usearch_open(pattern, -1, target, -1, "en_US",
 118  *                                  &status);
 119  * if (U_SUCCESS(status)) {
 120  *     for (int pos = usearch_first(search, &status);
 121  *                                      pos != USEARCH_DONE;
 122  *                                      pos = usearch_next(search, &status)) {
 123  *         printf("Found match at %d pos, length is %d\n", pos,
 124  *                                        usearch_getMatchLength(search));
 125  *     }
 126  * }
 127  * </code></pre>
 128  * @stable ICU 2.4
 129  */
 130
 131 /**
 132 * DONE is returned by previous() and next() after all valid matches have
 133 * been returned, and by first() and last() if there are no matches at all.
 134 * @stable ICU 2.4
 135 */
 136 #define USEARCH_DONE -1
 137
 138 /**
 139 * Data structure for searching
 140 * @stable ICU 2.4
 141 */
 142 struct UStringSearch;
 143 /**
 144 * Data structure for searching
 145 * @stable ICU 2.4
 146 */
 147 typedef struct UStringSearch UStringSearch;
 148
 149 /**
 150 * @stable ICU 2.4
 151 */
 152 typedef enum {
 153     /** Option for overlapping matches */
 154     USEARCH_OVERLAP,
 155     /**
 156     Option for canonical matches. option 1 in header documentation.
 157     The default value will be USEARCH_OFF
 158     */
 159     USEARCH_CANONICAL_MATCH,
 160     USEARCH_ATTRIBUTE_COUNT
 161 } USearchAttribute;
 162
 163 /**
 164 * @stable ICU 2.4
 165 */
 166 typedef enum {
 167     /** default value for any USearchAttribute */
 168     USEARCH_DEFAULT = -1,
 169     /** value for USEARCH_OVERLAP and USEARCH_CANONICAL_MATCH */
 170     USEARCH_OFF,
 171     /** value for USEARCH_OVERLAP and USEARCH_CANONICAL_MATCH */
 172     USEARCH_ON,
 173     USEARCH_ATTRIBUTE_VALUE_COUNT
 174 } USearchAttributeValue;
 175
 176 /* open and close ------------------------------------------------------ */
 177
 178 /**
 179 * Creating a search iterator data struct using the argument locale language
 180 * rule set. A collator will be created in the process, which will be owned by
 181 * this search and will be deleted in <tt>usearch_close</tt>.
 182 * @param pattern for matching
 183 * @param patternlength length of the pattern, -1 for null-termination
 184 * @param text text string
 185 * @param textlength length of the text string, -1 for null-termination
 186 * @param locale name of locale for the rules to be used
 187 * @param breakiter A BreakIterator that will be used to restrict the points
 188 *                  at which matches are detected. If a match is found, but
 189 *                  the match's start or end index is not a boundary as
 190 *                  determined by the <tt>BreakIterator</tt>, the match will
 191 *                  be rejected and another will be searched for.
 192 *                  If this parameter is <tt>NULL</tt>, no break detection is
 193 *                  attempted.
 194 * @param status for errors if it occurs. If pattern or text is NULL, or if
 195 *               patternlength or textlength is 0 then an
 196 *               U_ILLEGAL_ARGUMENT_ERROR is returned.
 197 * @return search iterator data structure, or NULL if there is an error.
 198 * @stable ICU 2.4
 199 */
 200 U_STABLE UStringSearch * U_EXPORT2 usearch_open(const UChar          *pattern,
 201                                               int32_t         patternlength,
 202                                         const UChar          *text,
 203                                               int32_t         textlength,
 204                                         const char           *locale,
 205                                               UBreakIterator *breakiter,
 206                                               UErrorCode     *status);
 207
 208 /**
 209 * Creating a search iterator data struct using the argument collator language
 210 * rule set. Note, user retains the ownership of this collator, thus the
 211 * responsibility of deletion lies with the user.
 212 * NOTE: string search cannot be instantiated from a collator that has
 213 * collate digits as numbers (CODAN) turned on.
 214 * @param pattern for matching
 215 * @param patternlength length of the pattern, -1 for null-termination
 216 * @param text text string
 217 * @param textlength length of the text string, -1 for null-termination
 218 * @param collator used for the language rules
 219 * @param breakiter A BreakIterator that will be used to restrict the points
 220 *                  at which matches are detected. If a match is found, but
 221 *                  the match's start or end index is not a boundary as
 222 *                  determined by the <tt>BreakIterator</tt>, the match will
 223 *                  be rejected and another will be searched for.
 224 *                  If this parameter is <tt>NULL</tt>, no break detection is
 225 *                  attempted.
 226 * @param status for errors if it occurs. If collator, pattern or text is NULL,
 227 *               or if patternlength or textlength is 0 then an
 228 *               U_ILLEGAL_ARGUMENT_ERROR is returned.
 229 * @return search iterator data structure, or NULL if there is an error.
 230 * @stable ICU 2.4
 231 */
 232 U_STABLE UStringSearch * U_EXPORT2 usearch_openFromCollator(
 233                                          const UChar *pattern,
 234                                                int32_t         patternlength,
 235                                          const UChar          *text,
 236                                                int32_t         textlength,
 237                                          const UCollator      *collator,
 238                                                UBreakIterator *breakiter,
 239                                                UErrorCode     *status);
 240
 241 /**
 242 * Destroying and cleaning up the search iterator data struct.
 243 * If a collator is created in <tt>usearch_open</tt>, it will be destroyed here.
 244 * @param searchiter data struct to clean up
 245 * @stable ICU 2.4
 246 */
 247 U_STABLE void U_EXPORT2 usearch_close(UStringSearch *searchiter);
 248
 249 /* get and set methods -------------------------------------------------- */
 250
 251 /**
 252 * Sets the current position in the text string which the next search will
 253 * start from. Clears previous states.
 254 * This method takes the argument index and sets the position in the text
 255 * string accordingly without checking if the index is pointing to a
 256 * valid starting point to begin searching.
 257 * Search positions that may render incorrect results are highlighted in the
 258 * header comments
 259 * @param strsrch search iterator data struct
 260 * @param position position to start next search from. If position is less
 261 *          than or greater than the text range for searching,
 262 *          an U_INDEX_OUTOFBOUNDS_ERROR will be returned
 263 * @param status error status if any.
 264 * @stable ICU 2.4
 265 */
 266 U_STABLE void U_EXPORT2 usearch_setOffset(UStringSearch *strsrch,
 267                                         int32_t    position,
 268                                         UErrorCode    *status);
 269
 270 /**
 271 * Return the current index in the string text being searched.
 272 * If the iteration has gone past the end of the text (or past the beginning
 273 * for a backwards search), <tt>USEARCH_DONE</tt> is returned.
 274 * @param strsrch search iterator data struct
 275 * @see #USEARCH_DONE
 276 * @stable ICU 2.4
 277 */
 278 U_STABLE int32_t U_EXPORT2 usearch_getOffset(const UStringSearch *strsrch);
 279
 280 /**
 281 * Sets the text searching attributes located in the enum USearchAttribute
 282 * with values from the enum USearchAttributeValue.
 283 * <tt>USEARCH_DEFAULT</tt> can be used for all attributes for resetting.
 284 * @param strsrch search iterator data struct
 285 * @param attribute text attribute to be set
 286 * @param value text attribute value
 287 * @param status for errors if it occurs
 288 * @see #usearch_getAttribute
 289 * @stable ICU 2.4
 290 */
 291 U_STABLE void U_EXPORT2 usearch_setAttribute(UStringSearch         *strsrch,
 292                                            USearchAttribute       attribute,
 293                                            USearchAttributeValue  value,
 294                                            UErrorCode            *status);
 295
 296 /**
 297 * Gets the text searching attributes.
 298 * @param strsrch search iterator data struct
 299 * @param attribute text attribute to be retrieve
 300 * @return text attribute value
 301 * @see #usearch_setAttribute
 302 * @stable ICU 2.4
 303 */
 304 U_STABLE USearchAttributeValue U_EXPORT2 usearch_getAttribute(
 305                                          const UStringSearch    *strsrch,
 306                                                USearchAttribute  attribute);
 307
 308 /**
 309 * Returns the index to the match in the text string that was searched.
 310 * This call returns a valid result only after a successful call to
 311 * <tt>usearch_first</tt>, <tt>usearch_next</tt>, <tt>usearch_previous</tt>,
 312 * or <tt>usearch_last</tt>.
 313 * Just after construction, or after a searching method returns
 314 * <tt>USEARCH_DONE</tt>, this method will return <tt>USEARCH_DONE</tt>.
 315 * <p>
 316 * Use <tt>usearch_getMatchedLength</tt> to get the matched string length.
 317 * @param strsrch search iterator data struct
 318 * @return index to a substring within the text string that is being
 319 *         searched.
 320 * @see #usearch_first
 321 * @see #usearch_next
 322 * @see #usearch_previous
 323 * @see #usearch_last
 324 * @see #USEARCH_DONE
 325 * @stable ICU 2.4
 326 */
 327 U_STABLE int32_t U_EXPORT2 usearch_getMatchedStart(
 328                                                const UStringSearch *strsrch);
 329
 330 /**
 331 * Returns the length of text in the string which matches the search pattern.
 332 * This call returns a valid result only after a successful call to
 333 * <tt>usearch_first</tt>, <tt>usearch_next</tt>, <tt>usearch_previous</tt>,
 334 * or <tt>usearch_last</tt>.
 335 * Just after construction, or after a searching method returns
 336 * <tt>USEARCH_DONE</tt>, this method will return 0.
 337 * @param strsrch search iterator data struct
 338 * @return The length of the match in the string text, or 0 if there is no
 339 *         match currently.
 340 * @see #usearch_first
 341 * @see #usearch_next
 342 * @see #usearch_previous
 343 * @see #usearch_last
 344 * @see #USEARCH_DONE
 345 * @stable ICU 2.4
 346 */
 347 U_STABLE int32_t U_EXPORT2 usearch_getMatchedLength(
 348                                                const UStringSearch *strsrch);
 349
 350 /**
 351 * Returns the text that was matched by the most recent call to
 352 * <tt>usearch_first</tt>, <tt>usearch_next</tt>, <tt>usearch_previous</tt>,
 353 * or <tt>usearch_last</tt>.
 354 * If the iterator is not pointing at a valid match (e.g. just after
 355 * construction or after <tt>USEARCH_DONE</tt> has been returned, returns
 356 * an empty string. If result is not large enough to store the matched text,
 357 * result will be filled with the partial text and an U_BUFFER_OVERFLOW_ERROR
 358 * will be returned in status. result will be null-terminated whenever
 359 * possible. If the buffer fits the matched text exactly, a null-termination
 360 * is not possible, then a U_STRING_NOT_TERMINATED_ERROR set in status.
 361 * Pre-flighting can be either done with length = 0 or the API
 362 * <tt>usearch_getMatchLength</tt>.
 363 * @param strsrch search iterator data struct
 364 * @param result UChar buffer to store the matched string
 365 * @param resultCapacity length of the result buffer
 366 * @param status error returned if result is not large enough
 367 * @return exact length of the matched text, not counting the null-termination
 368 * @see #usearch_first
 369 * @see #usearch_next
 370 * @see #usearch_previous
 371 * @see #usearch_last
 372 * @see #USEARCH_DONE
 373 * @stable ICU 2.4
 374 */
 375 U_STABLE int32_t U_EXPORT2 usearch_getMatchedText(const UStringSearch *strsrch,
 376                                             UChar         *result,
 377                                             int32_t        resultCapacity,
 378                                             UErrorCode    *status);
 379
 380 #if !UCONFIG_NO_BREAK_ITERATION
 381
 382 /**
 383 * Set the BreakIterator that will be used to restrict the points at which
 384 * matches are detected.
 385 * @param strsrch search iterator data struct
 386 * @param breakiter A BreakIterator that will be used to restrict the points
 387 *                  at which matches are detected. If a match is found, but
 388 *                  the match's start or end index is not a boundary as
 389 *                  determined by the <tt>BreakIterator</tt>, the match will
 390 *                  be rejected and another will be searched for.
 391 *                  If this parameter is <tt>NULL</tt>, no break detection is
 392 *                  attempted.
 393 * @param status for errors if it occurs
 394 * @see #usearch_getBreakIterator
 395 * @stable ICU 2.4
 396 */
 397 U_STABLE void U_EXPORT2 usearch_setBreakIterator(UStringSearch  *strsrch,
 398                                                UBreakIterator *breakiter,
 399                                                UErrorCode     *status);
 400
 401 /**
 402 * Returns the BreakIterator that is used to restrict the points at which
 403 * matches are detected. This will be the same object that was passed to the
 404 * constructor or to <tt>usearch_setBreakIterator</tt>. Note that
 405 * <tt>NULL</tt>
 406 * is a legal value; it means that break detection should not be attempted.
 407 * @param strsrch search iterator data struct
 408 * @return break iterator used
 409 * @see #usearch_setBreakIterator
 410 * @stable ICU 2.4
 411 */
 412 U_STABLE const UBreakIterator * U_EXPORT2 usearch_getBreakIterator(
 413                                               const UStringSearch *strsrch);
 414
 415 #endif
 416
 417 /**
 418 * Set the string text to be searched. Text iteration will hence begin at the
 419 * start of the text string. This method is useful if you want to re-use an
 420 * iterator to search for the same pattern within a different body of text.
 421 * @param strsrch search iterator data struct
 422 * @param text new string to look for match
 423 * @param textlength length of the new string, -1 for null-termination
 424 * @param status for errors if it occurs. If text is NULL, or textlength is 0
 425 *               then an U_ILLEGAL_ARGUMENT_ERROR is returned with no change
 426 *               done to strsrch.
 427 * @see #usearch_getText
 428 * @stable ICU 2.4
 429 */
 430 U_STABLE void U_EXPORT2 usearch_setText(      UStringSearch *strsrch,
 431                                       const UChar         *text,
 432                                             int32_t        textlength,
 433                                             UErrorCode    *status);
 434
 435 /**
 436 * Return the string text to be searched.
 437 * @param strsrch search iterator data struct
 438 * @param length returned string text length
 439 * @return string text
 440 * @see #usearch_setText
 441 * @stable ICU 2.4
 442 */
 443 U_STABLE const UChar * U_EXPORT2 usearch_getText(const UStringSearch *strsrch,
 444                                                int32_t       *length);
 445
 446 /**
 447 * Gets the collator used for the language rules.
 448 * <p>
 449 * Deleting the returned <tt>UCollator</tt> before calling
 450 * <tt>usearch_close</tt> would cause the string search to fail.
 451 * <tt>usearch_close</tt> will delete the collator if this search owns it.
 452 * @param strsrch search iterator data struct
 453 * @return collator
 454 * @stable ICU 2.4
 455 */
 456 U_STABLE UCollator * U_EXPORT2 usearch_getCollator(
 457                                                const UStringSearch *strsrch);
 458
 459 /**
 460 * Sets the collator used for the language rules. User retains the ownership
 461 * of this collator, thus the responsibility of deletion lies with the user.
 462 * This method causes internal data such as Boyer-Moore shift tables to
 463 * be recalculated, but the iterator's position is unchanged.
 464 * @param strsrch search iterator data struct
 465 * @param collator to be used
 466 * @param status for errors if it occurs
 467 * @stable ICU 2.4
 468 */
 469 U_STABLE void U_EXPORT2 usearch_setCollator(      UStringSearch *strsrch,
 470                                           const UCollator     *collator,
 471                                                 UErrorCode    *status);
 472
 473 /**
 474 * Sets the pattern used for matching.
 475 * Internal data like the Boyer Moore table will be recalculated, but the
 476 * iterator's position is unchanged.
 477 * @param strsrch search iterator data struct
 478 * @param pattern string
 479 * @param patternlength pattern length, -1 for null-terminated string
 480 * @param status for errors if it occurs. If text is NULL, or textlength is 0
 481 *               then an U_ILLEGAL_ARGUMENT_ERROR is returned with no change
 482 *               done to strsrch.
 483 * @stable ICU 2.4
 484 */
 485 U_STABLE void U_EXPORT2 usearch_setPattern(      UStringSearch *strsrch,
 486                                          const UChar         *pattern,
 487                                                int32_t        patternlength,
 488                                                UErrorCode    *status);
 489
 490 /**
 491 * Gets the search pattern
 492 * @param strsrch search iterator data struct
 493 * @param length return length of the pattern, -1 indicates that the pattern
 494 *               is null-terminated
 495 * @return pattern string
 496 * @stable ICU 2.4
 497 */
 498 U_STABLE const UChar * U_EXPORT2 usearch_getPattern(
 499                                                const UStringSearch *strsrch,
 500                                                      int32_t       *length);
 501
 502 /* methods ------------------------------------------------------------- */
 503
 504 /**
 505 * Returns the first index at which the string text matches the search
 506 * pattern.
 507 * The iterator is adjusted so that its current index (as returned by
 508 * <tt>usearch_getOffset</tt>) is the match position if one was found.
 509 * If a match is not found, <tt>USEARCH_DONE</tt> will be returned and
 510 * the iterator will be adjusted to the index <tt>USEARCH_DONE</tt>.
 511 * @param strsrch search iterator data struct
 512 * @param status for errors if it occurs
 513 * @return The character index of the first match, or
 514 * <tt>USEARCH_DONE</tt> if there are no matches.
 515 * @see #usearch_getOffset
 516 * @see #USEARCH_DONE
 517 * @stable ICU 2.4
 518 */
 519 U_STABLE int32_t U_EXPORT2 usearch_first(UStringSearch *strsrch,
 520                                            UErrorCode    *status);
 521
 522 /**
 523 * Returns the first index greater than <tt>position</tt> at which the string
 524 * text
 525 * matches the search pattern. The iterator is adjusted so that its current
 526 * index (as returned by <tt>usearch_getOffset</tt>) is the match position if
 527 * one was found.
 528 * If a match is not found, <tt>USEARCH_DONE</tt> will be returned and
 529 * the iterator will be adjusted to the index <tt>USEARCH_DONE</tt>
 530 * <p>
 531 * Search positions that may render incorrect results are highlighted in the
 532 * header comments. If position is less than or greater than the text range
 533 * for searching, an U_INDEX_OUTOFBOUNDS_ERROR will be returned
 534 * @param strsrch search iterator data struct
 535 * @param position to start the search at
 536 * @param status for errors if it occurs
 537 * @return The character index of the first match following <tt>pos</tt>,
 538 *         or <tt>USEARCH_DONE</tt> if there are no matches.
 539 * @see #usearch_getOffset
 540 * @see #USEARCH_DONE
 541 * @stable ICU 2.4
 542 */
 543 U_STABLE int32_t U_EXPORT2 usearch_following(UStringSearch *strsrch,
 544                                                int32_t    position,
 545                                                UErrorCode    *status);
 546
 547 /**
 548 * Returns the last index in the target text at which it matches the search
 549 * pattern. The iterator is adjusted so that its current
 550 * index (as returned by <tt>usearch_getOffset</tt>) is the match position if
 551 * one was found.
 552 * If a match is not found, <tt>USEARCH_DONE</tt> will be returned and
 553 * the iterator will be adjusted to the index <tt>USEARCH_DONE</tt>.
 554 * @param strsrch search iterator data struct
 555 * @param status for errors if it occurs
 556 * @return The index of the first match, or <tt>USEARCH_DONE</tt> if there
 557 *         are no matches.
 558 * @see #usearch_getOffset
 559 * @see #USEARCH_DONE
 560 * @stable ICU 2.4
 561 */
 562 U_STABLE int32_t U_EXPORT2 usearch_last(UStringSearch *strsrch,
 563                                           UErrorCode    *status);
 564
 565 /**
 566 * Returns the first index less than <tt>position</tt> at which the string text
 567 * matches the search pattern. The iterator is adjusted so that its current
 568 * index (as returned by <tt>usearch_getOffset</tt>) is the match position if
 569 * one was found.
 570 * If a match is not found, <tt>USEARCH_DONE</tt> will be returned and
 571 * the iterator will be adjusted to the index <tt>USEARCH_DONE</tt>
 572 * <p>
 573 * Search positions that may render incorrect results are highlighted in the
 574 * header comments. If position is less than or greater than the text range
 575 * for searching, an U_INDEX_OUTOFBOUNDS_ERROR will be returned
 576 * @param strsrch search iterator data struct
 577 * @param position index position the search is to begin at
 578 * @param status for errors if it occurs
 579 * @return The character index of the first match preceding <tt>pos</tt>,
 580 *         or <tt>USEARCH_DONE</tt> if there are no matches.
 581 * @see #usearch_getOffset
 582 * @see #USEARCH_DONE
 583 * @stable ICU 2.4
 584 */
 585 U_STABLE int32_t U_EXPORT2 usearch_preceding(UStringSearch *strsrch,
 586                                                int32_t    position,
 587                                                UErrorCode    *status);
 588
 589 /**
 590 * Returns the index of the next point at which the string text matches the
 591 * search pattern, starting from the current position.
 592 * The iterator is adjusted so that its current
 593 * index (as returned by <tt>usearch_getOffset</tt>) is the match position if
 594 * one was found.
 595 * If a match is not found, <tt>USEARCH_DONE</tt> will be returned and
 596 * the iterator will be adjusted to the index <tt>USEARCH_DONE</tt>
 597 * @param strsrch search iterator data struct
 598 * @param status for errors if it occurs
 599 * @return The index of the next match after the current position, or
 600 *         <tt>USEARCH_DONE</tt> if there are no more matches.
 601 * @see #usearch_first
 602 * @see #usearch_getOffset
 603 * @see #USEARCH_DONE
 604 * @stable ICU 2.4
 605 */
 606 U_STABLE int32_t U_EXPORT2 usearch_next(UStringSearch *strsrch,
 607                                           UErrorCode    *status);
 608
 609 /**
 610 * Returns the index of the previous point at which the string text matches
 611 * the search pattern, starting at the current position.
 612 * The iterator is adjusted so that its current
 613 * index (as returned by <tt>usearch_getOffset</tt>) is the match position if
 614 * one was found.
 615 * If a match is not found, <tt>USEARCH_DONE</tt> will be returned and
 616 * the iterator will be adjusted to the index <tt>USEARCH_DONE</tt>
 617 * @param strsrch search iterator data struct
 618 * @param status for errors if it occurs
 619 * @return The index of the previous match before the current position,
 620 *         or <tt>USEARCH_DONE</tt> if there are no more matches.
 621 * @see #usearch_last
 622 * @see #usearch_getOffset
 623 * @see #USEARCH_DONE
 624 * @stable ICU 2.4
 625 */
 626 U_STABLE int32_t U_EXPORT2 usearch_previous(UStringSearch *strsrch,
 627                                               UErrorCode    *status);
 628
 629 /**
 630 * Reset the iteration.
 631 * Search will begin at the start of the text string if a forward iteration
 632 * is initiated before a backwards iteration. Otherwise if a backwards
 633 * iteration is initiated before a forwards iteration, the search will begin
 634 * at the end of the text string.
 635 * @param strsrch search iterator data struct
 636 * @see #usearch_first
 637 * @stable ICU 2.4
 638 */
 639 U_STABLE void U_EXPORT2 usearch_reset(UStringSearch *strsrch);
 640
 641 #endif /* #if !UCONFIG_NO_COLLATION */
 642
 643 #endif