1 /* 2 ********************************************************************** 3 * Copyright (C) 2001-2014 IBM and others. All rights reserved. 4 ********************************************************************** 5 * Date Name Description 6 * 03/22/2000 helena Creation. 7 ********************************************************************** 8 */ 9 10 #ifndef STSEARCH_H 11 #define STSEARCH_H 12 13 #include "unicode/utypes.h" 14 15 /** 16 * \file 17 * \brief C++ API: Service for searching text based on RuleBasedCollator. 18 */ 19 20 #if !UCONFIG_NO_COLLATION && !UCONFIG_NO_BREAK_ITERATION 21 22 #include "unicode/tblcoll.h" 23 #include "unicode/coleitr.h" 24 #include "unicode/search.h" 25 26 U_NAMESPACE_BEGIN 27 28 /** 29 * 30 * <tt>StringSearch</tt> is a <tt>SearchIterator</tt> that provides 31 * language-sensitive text searching based on the comparison rules defined 32 * in a {@link RuleBasedCollator} object. 33 * StringSearch ensures that language eccentricity can be 34 * handled, e.g. for the German collator, characters ß and SS will be matched 35 * if case is chosen to be ignored. 36 * See the <a href="http://source.icu-project.org/repos/icu/icuhtml/trunk/design/collation/ICU_collation_design.htm"> 37 * "ICU Collation Design Document"</a> for more information. 38 * <p> 39 * There are 2 match options for selection:<br> 40 * Let S' be the sub-string of a text string S between the offsets start and 41 * end [start, end]. 42 * <br> 43 * A pattern string P matches a text string S at the offsets [start, end] 44 * if 45 * <pre> 46 * option 1. Some canonical equivalent of P matches some canonical equivalent 47 * of S' 48 * option 2. P matches S' and if P starts or ends with a combining mark, 49 * there exists no non-ignorable combining mark before or after S? 50 * in S respectively. 51 * </pre> 52 * Option 2. will be the default. 53 * <p> 54 * This search has APIs similar to that of other text iteration mechanisms 55 * such as the break iterators in <tt>BreakIterator</tt>. Using these 56 * APIs, it is easy to scan through text looking for all occurrences of 57 * a given pattern. This search iterator allows changing of direction by 58 * calling a <tt>reset</tt> followed by a <tt>next</tt> or <tt>previous</tt>. 59 * Though a direction change can occur without calling <tt>reset</tt> first, 60 * this operation comes with some speed penalty. 61 * Match results in the forward direction will match the result matches in 62 * the backwards direction in the reverse order 63 * <p> 64 * <tt>SearchIterator</tt> provides APIs to specify the starting position 65 * within the text string to be searched, e.g. <tt>setOffset</tt>, 66 * <tt>preceding</tt> and <tt>following</tt>. Since the 67 * starting position will be set as it is specified, please take note that 68 * there are some danger points which the search may render incorrect 69 * results: 70 * <ul> 71 * <li> The midst of a substring that requires normalization. 72 * <li> If the following match is to be found, the position should not be the 73 * second character which requires to be swapped with the preceding 74 * character. Vice versa, if the preceding match is to be found, 75 * position to search from should not be the first character which 76 * requires to be swapped with the next character. E.g certain Thai and 77 * Lao characters require swapping. 78 * <li> If a following pattern match is to be found, any position within a 79 * contracting sequence except the first will fail. Vice versa if a 80 * preceding pattern match is to be found, a invalid starting point 81 * would be any character within a contracting sequence except the last. 82 * </ul> 83 * <p> 84 * A <tt>BreakIterator</tt> can be used if only matches at logical breaks are desired. 85 * Using a <tt>BreakIterator</tt> will only give you results that exactly matches the 86 * boundaries given by the breakiterator. For instance the pattern "e" will 87 * not be found in the string "\u00e9" if a character break iterator is used. 88 * <p> 89 * Options are provided to handle overlapping matches. 90 * E.g. In English, overlapping matches produces the result 0 and 2 91 * for the pattern "abab" in the text "ababab", where else mutually 92 * exclusive matches only produce the result of 0. 93 * <p> 94 * Though collator attributes will be taken into consideration while 95 * performing matches, there are no APIs here for setting and getting the 96 * attributes. These attributes can be set by getting the collator 97 * from <tt>getCollator</tt> and using the APIs in <tt>coll.h</tt>. 98 * Lastly to update <tt>StringSearch</tt> to the new collator attributes, 99 * <tt>reset</tt> has to be called. 100 * <p> 101 * Restriction: <br> 102 * Currently there are no composite characters that consists of a 103 * character with combining class > 0 before a character with combining 104 * class == 0. However, if such a character exists in the future, 105 * <tt>StringSearch</tt> does not guarantee the results for option 1. 106 * <p> 107 * Consult the <tt>SearchIterator</tt> documentation for information on 108 * and examples of how to use instances of this class to implement text 109 * searching. 110 * <pre><code> 111 * UnicodeString target("The quick brown fox jumps over the lazy dog."); 112 * UnicodeString pattern("fox"); 113 * 114 * UErrorCode error = U_ZERO_ERROR; 115 * StringSearch iter(pattern, target, Locale::getUS(), NULL, status); 116 * for (int pos = iter.first(error); 117 * pos != USEARCH_DONE; 118 * pos = iter.next(error)) 119 * { 120 * printf("Found match at %d pos, length is %d\n", pos, 121 * iter.getMatchLength()); 122 * } 123 * </code></pre> 124 * <p> 125 * Note, <tt>StringSearch</tt> is not to be subclassed. 126 * </p> 127 * @see SearchIterator 128 * @see RuleBasedCollator 129 * @since ICU 2.0 130 */ 131 132 class U_I18N_API StringSearch U_FINAL : public SearchIterator 133 { 134 public: 135 136 // public constructors and destructors -------------------------------- 137 138 /** 139 * Creating a <tt>StringSearch</tt> instance using the argument locale 140 * language rule set. A collator will be created in the process, which 141 * will be owned by this instance and will be deleted during 142 * destruction 143 * @param pattern The text for which this object will search. 144 * @param text The text in which to search for the pattern. 145 * @param locale A locale which defines the language-sensitive 146 * comparison rules used to determine whether text in the 147 * pattern and target matches. 148 * @param breakiter A <tt>BreakIterator</tt> object used to constrain 149 * the matches that are found. Matches whose start and end 150 * indices in the target text are not boundaries as 151 * determined by the <tt>BreakIterator</tt> are 152 * ignored. If this behavior is not desired, 153 * <tt>NULL</tt> can be passed in instead. 154 * @param status for errors if any. If pattern or text is NULL, or if 155 * either the length of pattern or text is 0 then an 156 * U_ILLEGAL_ARGUMENT_ERROR is returned. 157 * @stable ICU 2.0 158 */ 159 StringSearch(const UnicodeString &pattern, const UnicodeString &text, 160 const Locale &locale, 161 BreakIterator *breakiter, 162 UErrorCode &status); 163 164 /** 165 * Creating a <tt>StringSearch</tt> instance using the argument collator 166 * language rule set. Note, user retains the ownership of this collator, 167 * it does not get destroyed during this instance's destruction. 168 * @param pattern The text for which this object will search. 169 * @param text The text in which to search for the pattern. 170 * @param coll A <tt>RuleBasedCollator</tt> object which defines 171 * the language-sensitive comparison rules used to 172 * determine whether text in the pattern and target 173 * matches. User is responsible for the clearing of this 174 * object. 175 * @param breakiter A <tt>BreakIterator</tt> object used to constrain 176 * the matches that are found. Matches whose start and end 177 * indices in the target text are not boundaries as 178 * determined by the <tt>BreakIterator</tt> are 179 * ignored. If this behavior is not desired, 180 * <tt>NULL</tt> can be passed in instead. 181 * @param status for errors if any. If either the length of pattern or 182 * text is 0 then an U_ILLEGAL_ARGUMENT_ERROR is returned. 183 * @stable ICU 2.0 184 */ 185 StringSearch(const UnicodeString &pattern, 186 const UnicodeString &text, 187 RuleBasedCollator *coll, 188 BreakIterator *breakiter, 189 UErrorCode &status); 190 191 /** 192 * Creating a <tt>StringSearch</tt> instance using the argument locale 193 * language rule set. A collator will be created in the process, which 194 * will be owned by this instance and will be deleted during 195 * destruction 196 * <p> 197 * Note: No parsing of the text within the <tt>CharacterIterator</tt> 198 * will be done during searching for this version. The block of text 199 * in <tt>CharacterIterator</tt> will be used as it is. 200 * @param pattern The text for which this object will search. 201 * @param text The text iterator in which to search for the pattern. 202 * @param locale A locale which defines the language-sensitive 203 * comparison rules used to determine whether text in the 204 * pattern and target matches. User is responsible for 205 * the clearing of this object. 206 * @param breakiter A <tt>BreakIterator</tt> object used to constrain 207 * the matches that are found. Matches whose start and end 208 * indices in the target text are not boundaries as 209 * determined by the <tt>BreakIterator</tt> are 210 * ignored. If this behavior is not desired, 211 * <tt>NULL</tt> can be passed in instead. 212 * @param status for errors if any. If either the length of pattern or 213 * text is 0 then an U_ILLEGAL_ARGUMENT_ERROR is returned. 214 * @stable ICU 2.0 215 */ 216 StringSearch(const UnicodeString &pattern, CharacterIterator &text, 217 const Locale &locale, 218 BreakIterator *breakiter, 219 UErrorCode &status); 220 221 /** 222 * Creating a <tt>StringSearch</tt> instance using the argument collator 223 * language rule set. Note, user retains the ownership of this collator, 224 * it does not get destroyed during this instance's destruction. 225 * <p> 226 * Note: No parsing of the text within the <tt>CharacterIterator</tt> 227 * will be done during searching for this version. The block of text 228 * in <tt>CharacterIterator</tt> will be used as it is. 229 * @param pattern The text for which this object will search. 230 * @param text The text in which to search for the pattern. 231 * @param coll A <tt>RuleBasedCollator</tt> object which defines 232 * the language-sensitive comparison rules used to 233 * determine whether text in the pattern and target 234 * matches. User is responsible for the clearing of this 235 * object. 236 * @param breakiter A <tt>BreakIterator</tt> object used to constrain 237 * the matches that are found. Matches whose start and end 238 * indices in the target text are not boundaries as 239 * determined by the <tt>BreakIterator</tt> are 240 * ignored. If this behavior is not desired, 241 * <tt>NULL</tt> can be passed in instead. 242 * @param status for errors if any. If either the length of pattern or 243 * text is 0 then an U_ILLEGAL_ARGUMENT_ERROR is returned. 244 * @stable ICU 2.0 245 */ 246 StringSearch(const UnicodeString &pattern, CharacterIterator &text, 247 RuleBasedCollator *coll, 248 BreakIterator *breakiter, 249 UErrorCode &status); 250 251 /** 252 * Copy constructor that creates a StringSearch instance with the same 253 * behavior, and iterating over the same text. 254 * @param that StringSearch instance to be copied. 255 * @stable ICU 2.0 256 */ 257 StringSearch(const StringSearch &that); 258 259 /** 260 * Destructor. Cleans up the search iterator data struct. 261 * If a collator is created in the constructor, it will be destroyed here. 262 * @stable ICU 2.0 263 */ 264 virtual ~StringSearch(void); 265 266 /** 267 * Clone this object. 268 * Clones can be used concurrently in multiple threads. 269 * If an error occurs, then NULL is returned. 270 * The caller must delete the clone. 271 * 272 * @return a clone of this object 273 * 274 * @see getDynamicClassID 275 * @stable ICU 2.8 276 */ 277 StringSearch *clone() const; 278 279 // operator overloading --------------------------------------------- 280 281 /** 282 * Assignment operator. Sets this iterator to have the same behavior, 283 * and iterate over the same text, as the one passed in. 284 * @param that instance to be copied. 285 * @stable ICU 2.0 286 */ 287 StringSearch & operator=(const StringSearch &that); 288 289 /** 290 * Equality operator. 291 * @param that instance to be compared. 292 * @return TRUE if both instances have the same attributes, 293 * breakiterators, collators and iterate over the same text 294 * while looking for the same pattern. 295 * @stable ICU 2.0 296 */ 297 virtual UBool operator==(const SearchIterator &that) const; 298 299 // public get and set methods ---------------------------------------- 300 301 /** 302 * Sets the index to point to the given position, and clears any state 303 * that's affected. 304 * <p> 305 * This method takes the argument index and sets the position in the text 306 * string accordingly without checking if the index is pointing to a 307 * valid starting point to begin searching. 308 * @param position within the text to be set. If position is less 309 * than or greater than the text range for searching, 310 * an U_INDEX_OUTOFBOUNDS_ERROR will be returned 311 * @param status for errors if it occurs 312 * @stable ICU 2.0 313 */ 314 virtual void setOffset(int32_t position, UErrorCode &status); 315 316 /** 317 * Return the current index in the text being searched. 318 * If the iteration has gone past the end of the text 319 * (or past the beginning for a backwards search), USEARCH_DONE 320 * is returned. 321 * @return current index in the text being searched. 322 * @stable ICU 2.0 323 */ 324 virtual int32_t getOffset(void) const; 325 326 /** 327 * Set the target text to be searched. 328 * Text iteration will hence begin at the start of the text string. 329 * This method is 330 * useful if you want to re-use an iterator to search for the same 331 * pattern within a different body of text. 332 * @param text text string to be searched 333 * @param status for errors if any. If the text length is 0 then an 334 * U_ILLEGAL_ARGUMENT_ERROR is returned. 335 * @stable ICU 2.0 336 */ 337 virtual void setText(const UnicodeString &text, UErrorCode &status); 338 339 /** 340 * Set the target text to be searched. 341 * Text iteration will hence begin at the start of the text string. 342 * This method is 343 * useful if you want to re-use an iterator to search for the same 344 * pattern within a different body of text. 345 * Note: No parsing of the text within the <tt>CharacterIterator</tt> 346 * will be done during searching for this version. The block of text 347 * in <tt>CharacterIterator</tt> will be used as it is. 348 * @param text text string to be searched 349 * @param status for errors if any. If the text length is 0 then an 350 * U_ILLEGAL_ARGUMENT_ERROR is returned. 351 * @stable ICU 2.0 352 */ 353 virtual void setText(CharacterIterator &text, UErrorCode &status); 354 355 /** 356 * Gets the collator used for the language rules. 357 * <p> 358 * Caller may modify but <b>must not</b> delete the <tt>RuleBasedCollator</tt>! 359 * Modifications to this collator will affect the original collator passed in to 360 * the <tt>StringSearch></tt> constructor or to setCollator, if any. 361 * @return collator used for string search 362 * @stable ICU 2.0 363 */ 364 RuleBasedCollator * getCollator() const; 365 366 /** 367 * Sets the collator used for the language rules. User retains the 368 * ownership of this collator, thus the responsibility of deletion lies 369 * with the user. The iterator's position will not be changed by this method. 370 * @param coll collator 371 * @param status for errors if any 372 * @stable ICU 2.0 373 */ 374 void setCollator(RuleBasedCollator *coll, UErrorCode &status); 375 376 /** 377 * Sets the pattern used for matching. 378 * The iterator's position will not be changed by this method. 379 * @param pattern search pattern to be found 380 * @param status for errors if any. If the pattern length is 0 then an 381 * U_ILLEGAL_ARGUMENT_ERROR is returned. 382 * @stable ICU 2.0 383 */ 384 void setPattern(const UnicodeString &pattern, UErrorCode &status); 385 386 /** 387 * Gets the search pattern. 388 * @return pattern used for matching 389 * @stable ICU 2.0 390 */ 391 const UnicodeString & getPattern() const; 392 393 // public methods ---------------------------------------------------- 394 395 /** 396 * Reset the iteration. 397 * Search will begin at the start of the text string if a forward 398 * iteration is initiated before a backwards iteration. Otherwise if 399 * a backwards iteration is initiated before a forwards iteration, the 400 * search will begin at the end of the text string. 401 * @stable ICU 2.0 402 */ 403 virtual void reset(); 404 405 /** 406 * Returns a copy of StringSearch with the same behavior, and 407 * iterating over the same text, as this one. Note that all data will be 408 * replicated, except for the user-specified collator and the 409 * breakiterator. 410 * @return cloned object 411 * @stable ICU 2.0 412 */ 413 virtual SearchIterator * safeClone(void) const; 414 415 /** 416 * ICU "poor man's RTTI", returns a UClassID for the actual class. 417 * 418 * @stable ICU 2.2 419 */ 420 virtual UClassID getDynamicClassID() const; 421 422 /** 423 * ICU "poor man's RTTI", returns a UClassID for this class. 424 * 425 * @stable ICU 2.2 426 */ 427 static UClassID U_EXPORT2 getStaticClassID(); 428 429 protected: 430 431 // protected method ------------------------------------------------- 432 433 /** 434 * Search forward for matching text, starting at a given location. 435 * Clients should not call this method directly; instead they should 436 * call {@link SearchIterator#next }. 437 * <p> 438 * If a match is found, this method returns the index at which the match 439 * starts and calls {@link SearchIterator#setMatchLength } with the number 440 * of characters in the target text that make up the match. If no match 441 * is found, the method returns <tt>USEARCH_DONE</tt>. 442 * <p> 443 * The <tt>StringSearch</tt> is adjusted so that its current index 444 * (as returned by {@link #getOffset }) is the match position if one was 445 * found. 446 * If a match is not found, <tt>USEARCH_DONE</tt> will be returned and 447 * the <tt>StringSearch</tt> will be adjusted to the index USEARCH_DONE. 448 * @param position The index in the target text at which the search 449 * starts 450 * @param status for errors if any occurs 451 * @return The index at which the matched text in the target starts, or 452 * USEARCH_DONE if no match was found. 453 * @stable ICU 2.0 454 */ 455 virtual int32_t handleNext(int32_t position, UErrorCode &status); 456 457 /** 458 * Search backward for matching text, starting at a given location. 459 * Clients should not call this method directly; instead they should call 460 * <tt>SearchIterator.previous()</tt>, which this method overrides. 461 * <p> 462 * If a match is found, this method returns the index at which the match 463 * starts and calls {@link SearchIterator#setMatchLength } with the number 464 * of characters in the target text that make up the match. If no match 465 * is found, the method returns <tt>USEARCH_DONE</tt>. 466 * <p> 467 * The <tt>StringSearch</tt> is adjusted so that its current index 468 * (as returned by {@link #getOffset }) is the match position if one was 469 * found. 470 * If a match is not found, <tt>USEARCH_DONE</tt> will be returned and 471 * the <tt>StringSearch</tt> will be adjusted to the index USEARCH_DONE. 472 * @param position The index in the target text at which the search 473 * starts. 474 * @param status for errors if any occurs 475 * @return The index at which the matched text in the target starts, or 476 * USEARCH_DONE if no match was found. 477 * @stable ICU 2.0 478 */ 479 virtual int32_t handlePrev(int32_t position, UErrorCode &status); 480 481 private : 482 StringSearch(); // default constructor not implemented 483 484 // private data members ---------------------------------------------- 485 486 /** 487 * Pattern text 488 * @stable ICU 2.0 489 */ 490 UnicodeString m_pattern_; 491 /** 492 * String search struct data 493 * @stable ICU 2.0 494 */ 495 UStringSearch *m_strsrch_; 496 497 }; 498 499 U_NAMESPACE_END 500 501 #endif /* #if !UCONFIG_NO_COLLATION */ 502 503 #endif 504 505
