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 ß 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 644
