EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2025-01-18 10:13:08
0001 // © 2016 and later: Unicode, Inc. and others. 0002 // License & terms of use: http://www.unicode.org/copyright.html 0003 /* 0004 ********************************************************************** 0005 * Copyright (C) 2001-2014 IBM and others. All rights reserved. 0006 ********************************************************************** 0007 * Date Name Description 0008 * 03/22/2000 helena Creation. 0009 ********************************************************************** 0010 */ 0011 0012 #ifndef STSEARCH_H 0013 #define STSEARCH_H 0014 0015 #include "unicode/utypes.h" 0016 0017 #if U_SHOW_CPLUSPLUS_API 0018 0019 /** 0020 * \file 0021 * \brief C++ API: Service for searching text based on RuleBasedCollator. 0022 */ 0023 0024 #if !UCONFIG_NO_COLLATION && !UCONFIG_NO_BREAK_ITERATION 0025 0026 #include "unicode/tblcoll.h" 0027 #include "unicode/coleitr.h" 0028 #include "unicode/search.h" 0029 0030 U_NAMESPACE_BEGIN 0031 0032 /** 0033 * 0034 * <tt>StringSearch</tt> is a <tt>SearchIterator</tt> that provides 0035 * language-sensitive text searching based on the comparison rules defined 0036 * in a {@link RuleBasedCollator} object. 0037 * StringSearch ensures that language eccentricity can be 0038 * handled, e.g. for the German collator, characters ß and SS will be matched 0039 * if case is chosen to be ignored. 0040 * See the <a href="https://htmlpreview.github.io/?https://github.com/unicode-org/icu-docs/blob/main/design/collation/ICU_collation_design.htm"> 0041 * "ICU Collation Design Document"</a> for more information. 0042 * <p> 0043 * There are 2 match options for selection:<br> 0044 * Let S' be the sub-string of a text string S between the offsets start and 0045 * end [start, end]. 0046 * <br> 0047 * A pattern string P matches a text string S at the offsets [start, end] 0048 * if 0049 * <pre> 0050 * option 1. Some canonical equivalent of P matches some canonical equivalent 0051 * of S' 0052 * option 2. P matches S' and if P starts or ends with a combining mark, 0053 * there exists no non-ignorable combining mark before or after S? 0054 * in S respectively. 0055 * </pre> 0056 * Option 2. will be the default. 0057 * <p> 0058 * This search has APIs similar to that of other text iteration mechanisms 0059 * such as the break iterators in <tt>BreakIterator</tt>. Using these 0060 * APIs, it is easy to scan through text looking for all occurrences of 0061 * a given pattern. This search iterator allows changing of direction by 0062 * calling a <tt>reset</tt> followed by a <tt>next</tt> or <tt>previous</tt>. 0063 * Though a direction change can occur without calling <tt>reset</tt> first, 0064 * this operation comes with some speed penalty. 0065 * Match results in the forward direction will match the result matches in 0066 * the backwards direction in the reverse order 0067 * <p> 0068 * <tt>SearchIterator</tt> provides APIs to specify the starting position 0069 * within the text string to be searched, e.g. <tt>setOffset</tt>, 0070 * <tt>preceding</tt> and <tt>following</tt>. Since the 0071 * starting position will be set as it is specified, please take note that 0072 * there are some danger points which the search may render incorrect 0073 * results: 0074 * <ul> 0075 * <li> The midst of a substring that requires normalization. 0076 * <li> If the following match is to be found, the position should not be the 0077 * second character which requires to be swapped with the preceding 0078 * character. Vice versa, if the preceding match is to be found, 0079 * position to search from should not be the first character which 0080 * requires to be swapped with the next character. E.g certain Thai and 0081 * Lao characters require swapping. 0082 * <li> If a following pattern match is to be found, any position within a 0083 * contracting sequence except the first will fail. Vice versa if a 0084 * preceding pattern match is to be found, a invalid starting point 0085 * would be any character within a contracting sequence except the last. 0086 * </ul> 0087 * <p> 0088 * A <tt>BreakIterator</tt> can be used if only matches at logical breaks are desired. 0089 * Using a <tt>BreakIterator</tt> will only give you results that exactly matches the 0090 * boundaries given by the breakiterator. For instance the pattern "e" will 0091 * not be found in the string "\u00e9" if a character break iterator is used. 0092 * <p> 0093 * Options are provided to handle overlapping matches. 0094 * E.g. In English, overlapping matches produces the result 0 and 2 0095 * for the pattern "abab" in the text "ababab", where else mutually 0096 * exclusive matches only produce the result of 0. 0097 * <p> 0098 * Though collator attributes will be taken into consideration while 0099 * performing matches, there are no APIs here for setting and getting the 0100 * attributes. These attributes can be set by getting the collator 0101 * from <tt>getCollator</tt> and using the APIs in <tt>coll.h</tt>. 0102 * Lastly to update <tt>StringSearch</tt> to the new collator attributes, 0103 * <tt>reset</tt> has to be called. 0104 * <p> 0105 * Restriction: <br> 0106 * Currently there are no composite characters that consists of a 0107 * character with combining class > 0 before a character with combining 0108 * class == 0. However, if such a character exists in the future, 0109 * <tt>StringSearch</tt> does not guarantee the results for option 1. 0110 * <p> 0111 * Consult the <tt>SearchIterator</tt> documentation for information on 0112 * and examples of how to use instances of this class to implement text 0113 * searching. 0114 * <pre><code> 0115 * UnicodeString target("The quick brown fox jumps over the lazy dog."); 0116 * UnicodeString pattern("fox"); 0117 * 0118 * UErrorCode error = U_ZERO_ERROR; 0119 * StringSearch iter(pattern, target, Locale::getUS(), nullptr, status); 0120 * for (int pos = iter.first(error); 0121 * pos != USEARCH_DONE; 0122 * pos = iter.next(error)) 0123 * { 0124 * printf("Found match at %d pos, length is %d\n", pos, iter.getMatchedLength()); 0125 * } 0126 * </code></pre> 0127 * <p> 0128 * Note, <tt>StringSearch</tt> is not to be subclassed. 0129 * </p> 0130 * @see SearchIterator 0131 * @see RuleBasedCollator 0132 * @since ICU 2.0 0133 */ 0134 0135 class U_I18N_API StringSearch final : public SearchIterator 0136 { 0137 public: 0138 0139 // public constructors and destructors -------------------------------- 0140 0141 /** 0142 * Creating a <tt>StringSearch</tt> instance using the argument locale 0143 * language rule set. A collator will be created in the process, which 0144 * will be owned by this instance and will be deleted during 0145 * destruction 0146 * @param pattern The text for which this object will search. 0147 * @param text The text in which to search for the pattern. 0148 * @param locale A locale which defines the language-sensitive 0149 * comparison rules used to determine whether text in the 0150 * pattern and target matches. 0151 * @param breakiter A <tt>BreakIterator</tt> object used to constrain 0152 * the matches that are found. Matches whose start and end 0153 * indices in the target text are not boundaries as 0154 * determined by the <tt>BreakIterator</tt> are 0155 * ignored. If this behavior is not desired, 0156 * <tt>nullptr</tt> can be passed in instead. 0157 * @param status for errors if any. If pattern or text is nullptr, or if 0158 * either the length of pattern or text is 0 then an 0159 * U_ILLEGAL_ARGUMENT_ERROR is returned. 0160 * @stable ICU 2.0 0161 */ 0162 StringSearch(const UnicodeString &pattern, const UnicodeString &text, 0163 const Locale &locale, 0164 BreakIterator *breakiter, 0165 UErrorCode &status); 0166 0167 /** 0168 * Creating a <tt>StringSearch</tt> instance using the argument collator 0169 * language rule set. Note, user retains the ownership of this collator, 0170 * it does not get destroyed during this instance's destruction. 0171 * @param pattern The text for which this object will search. 0172 * @param text The text in which to search for the pattern. 0173 * @param coll A <tt>RuleBasedCollator</tt> object which defines 0174 * the language-sensitive comparison rules used to 0175 * determine whether text in the pattern and target 0176 * matches. User is responsible for the clearing of this 0177 * object. 0178 * @param breakiter A <tt>BreakIterator</tt> object used to constrain 0179 * the matches that are found. Matches whose start and end 0180 * indices in the target text are not boundaries as 0181 * determined by the <tt>BreakIterator</tt> are 0182 * ignored. If this behavior is not desired, 0183 * <tt>nullptr</tt> can be passed in instead. 0184 * @param status for errors if any. If either the length of pattern or 0185 * text is 0 then an U_ILLEGAL_ARGUMENT_ERROR is returned. 0186 * @stable ICU 2.0 0187 */ 0188 StringSearch(const UnicodeString &pattern, 0189 const UnicodeString &text, 0190 RuleBasedCollator *coll, 0191 BreakIterator *breakiter, 0192 UErrorCode &status); 0193 0194 /** 0195 * Creating a <tt>StringSearch</tt> instance using the argument locale 0196 * language rule set. A collator will be created in the process, which 0197 * will be owned by this instance and will be deleted during 0198 * destruction 0199 * <p> 0200 * Note: No parsing of the text within the <tt>CharacterIterator</tt> 0201 * will be done during searching for this version. The block of text 0202 * in <tt>CharacterIterator</tt> will be used as it is. 0203 * @param pattern The text for which this object will search. 0204 * @param text The text iterator in which to search for the pattern. 0205 * @param locale A locale which defines the language-sensitive 0206 * comparison rules used to determine whether text in the 0207 * pattern and target matches. User is responsible for 0208 * the clearing of this object. 0209 * @param breakiter A <tt>BreakIterator</tt> object used to constrain 0210 * the matches that are found. Matches whose start and end 0211 * indices in the target text are not boundaries as 0212 * determined by the <tt>BreakIterator</tt> are 0213 * ignored. If this behavior is not desired, 0214 * <tt>nullptr</tt> can be passed in instead. 0215 * @param status for errors if any. If either the length of pattern or 0216 * text is 0 then an U_ILLEGAL_ARGUMENT_ERROR is returned. 0217 * @stable ICU 2.0 0218 */ 0219 StringSearch(const UnicodeString &pattern, CharacterIterator &text, 0220 const Locale &locale, 0221 BreakIterator *breakiter, 0222 UErrorCode &status); 0223 0224 /** 0225 * Creating a <tt>StringSearch</tt> instance using the argument collator 0226 * language rule set. Note, user retains the ownership of this collator, 0227 * it does not get destroyed during this instance's destruction. 0228 * <p> 0229 * Note: No parsing of the text within the <tt>CharacterIterator</tt> 0230 * will be done during searching for this version. The block of text 0231 * in <tt>CharacterIterator</tt> will be used as it is. 0232 * @param pattern The text for which this object will search. 0233 * @param text The text in which to search for the pattern. 0234 * @param coll A <tt>RuleBasedCollator</tt> object which defines 0235 * the language-sensitive comparison rules used to 0236 * determine whether text in the pattern and target 0237 * matches. User is responsible for the clearing of this 0238 * object. 0239 * @param breakiter A <tt>BreakIterator</tt> object used to constrain 0240 * the matches that are found. Matches whose start and end 0241 * indices in the target text are not boundaries as 0242 * determined by the <tt>BreakIterator</tt> are 0243 * ignored. If this behavior is not desired, 0244 * <tt>nullptr</tt> can be passed in instead. 0245 * @param status for errors if any. If either the length of pattern or 0246 * text is 0 then an U_ILLEGAL_ARGUMENT_ERROR is returned. 0247 * @stable ICU 2.0 0248 */ 0249 StringSearch(const UnicodeString &pattern, CharacterIterator &text, 0250 RuleBasedCollator *coll, 0251 BreakIterator *breakiter, 0252 UErrorCode &status); 0253 0254 /** 0255 * Copy constructor that creates a StringSearch instance with the same 0256 * behavior, and iterating over the same text. 0257 * @param that StringSearch instance to be copied. 0258 * @stable ICU 2.0 0259 */ 0260 StringSearch(const StringSearch &that); 0261 0262 /** 0263 * Destructor. Cleans up the search iterator data struct. 0264 * If a collator is created in the constructor, it will be destroyed here. 0265 * @stable ICU 2.0 0266 */ 0267 virtual ~StringSearch(void); 0268 0269 /** 0270 * Clone this object. 0271 * Clones can be used concurrently in multiple threads. 0272 * If an error occurs, then nullptr is returned. 0273 * The caller must delete the clone. 0274 * 0275 * @return a clone of this object 0276 * 0277 * @see getDynamicClassID 0278 * @stable ICU 2.8 0279 */ 0280 StringSearch *clone() const; 0281 0282 // operator overloading --------------------------------------------- 0283 0284 /** 0285 * Assignment operator. Sets this iterator to have the same behavior, 0286 * and iterate over the same text, as the one passed in. 0287 * @param that instance to be copied. 0288 * @stable ICU 2.0 0289 */ 0290 StringSearch & operator=(const StringSearch &that); 0291 0292 /** 0293 * Equality operator. 0294 * @param that instance to be compared. 0295 * @return true if both instances have the same attributes, 0296 * breakiterators, collators and iterate over the same text 0297 * while looking for the same pattern. 0298 * @stable ICU 2.0 0299 */ 0300 virtual bool operator==(const SearchIterator &that) const override; 0301 0302 // public get and set methods ---------------------------------------- 0303 0304 /** 0305 * Sets the index to point to the given position, and clears any state 0306 * that's affected. 0307 * <p> 0308 * This method takes the argument index and sets the position in the text 0309 * string accordingly without checking if the index is pointing to a 0310 * valid starting point to begin searching. 0311 * @param position within the text to be set. If position is less 0312 * than or greater than the text range for searching, 0313 * an U_INDEX_OUTOFBOUNDS_ERROR will be returned 0314 * @param status for errors if it occurs 0315 * @stable ICU 2.0 0316 */ 0317 virtual void setOffset(int32_t position, UErrorCode &status) override; 0318 0319 /** 0320 * Return the current index in the text being searched. 0321 * If the iteration has gone past the end of the text 0322 * (or past the beginning for a backwards search), USEARCH_DONE 0323 * is returned. 0324 * @return current index in the text being searched. 0325 * @stable ICU 2.0 0326 */ 0327 virtual int32_t getOffset(void) const override; 0328 0329 /** 0330 * Set the target text to be searched. 0331 * Text iteration will hence begin at the start of the text string. 0332 * This method is 0333 * useful if you want to re-use an iterator to search for the same 0334 * pattern within a different body of text. 0335 * @param text text string to be searched 0336 * @param status for errors if any. If the text length is 0 then an 0337 * U_ILLEGAL_ARGUMENT_ERROR is returned. 0338 * @stable ICU 2.0 0339 */ 0340 virtual void setText(const UnicodeString &text, UErrorCode &status) override; 0341 0342 /** 0343 * Set the target text to be searched. 0344 * Text iteration will hence begin at the start of the text string. 0345 * This method is 0346 * useful if you want to re-use an iterator to search for the same 0347 * pattern within a different body of text. 0348 * Note: No parsing of the text within the <tt>CharacterIterator</tt> 0349 * will be done during searching for this version. The block of text 0350 * in <tt>CharacterIterator</tt> will be used as it is. 0351 * @param text text string to be searched 0352 * @param status for errors if any. If the text length is 0 then an 0353 * U_ILLEGAL_ARGUMENT_ERROR is returned. 0354 * @stable ICU 2.0 0355 */ 0356 virtual void setText(CharacterIterator &text, UErrorCode &status) override; 0357 0358 /** 0359 * Gets the collator used for the language rules. 0360 * <p> 0361 * Caller may modify but <b>must not</b> delete the <tt>RuleBasedCollator</tt>! 0362 * Modifications to this collator will affect the original collator passed in to 0363 * the <tt>StringSearch></tt> constructor or to setCollator, if any. 0364 * @return collator used for string search 0365 * @stable ICU 2.0 0366 */ 0367 RuleBasedCollator * getCollator() const; 0368 0369 /** 0370 * Sets the collator used for the language rules. User retains the 0371 * ownership of this collator, thus the responsibility of deletion lies 0372 * with the user. The iterator's position will not be changed by this method. 0373 * @param coll collator 0374 * @param status for errors if any 0375 * @stable ICU 2.0 0376 */ 0377 void setCollator(RuleBasedCollator *coll, UErrorCode &status); 0378 0379 /** 0380 * Sets the pattern used for matching. 0381 * The iterator's position will not be changed by this method. 0382 * @param pattern search pattern to be found 0383 * @param status for errors if any. If the pattern length is 0 then an 0384 * U_ILLEGAL_ARGUMENT_ERROR is returned. 0385 * @stable ICU 2.0 0386 */ 0387 void setPattern(const UnicodeString &pattern, UErrorCode &status); 0388 0389 /** 0390 * Gets the search pattern. 0391 * @return pattern used for matching 0392 * @stable ICU 2.0 0393 */ 0394 const UnicodeString & getPattern() const; 0395 0396 // public methods ---------------------------------------------------- 0397 0398 /** 0399 * Reset the iteration. 0400 * Search will begin at the start of the text string if a forward 0401 * iteration is initiated before a backwards iteration. Otherwise if 0402 * a backwards iteration is initiated before a forwards iteration, the 0403 * search will begin at the end of the text string. 0404 * @stable ICU 2.0 0405 */ 0406 virtual void reset() override; 0407 0408 /** 0409 * Returns a copy of StringSearch with the same behavior, and 0410 * iterating over the same text, as this one. Note that all data will be 0411 * replicated, except for the user-specified collator and the 0412 * breakiterator. 0413 * @return cloned object 0414 * @stable ICU 2.0 0415 */ 0416 virtual StringSearch * safeClone() const override; 0417 0418 /** 0419 * ICU "poor man's RTTI", returns a UClassID for the actual class. 0420 * 0421 * @stable ICU 2.2 0422 */ 0423 virtual UClassID getDynamicClassID() const override; 0424 0425 /** 0426 * ICU "poor man's RTTI", returns a UClassID for this class. 0427 * 0428 * @stable ICU 2.2 0429 */ 0430 static UClassID U_EXPORT2 getStaticClassID(); 0431 0432 protected: 0433 0434 // protected method ------------------------------------------------- 0435 0436 /** 0437 * Search forward for matching text, starting at a given location. 0438 * Clients should not call this method directly; instead they should 0439 * call {@link SearchIterator#next }. 0440 * <p> 0441 * If a match is found, this method returns the index at which the match 0442 * starts and calls {@link SearchIterator#setMatchLength } with the number 0443 * of characters in the target text that make up the match. If no match 0444 * is found, the method returns <tt>USEARCH_DONE</tt>. 0445 * <p> 0446 * The <tt>StringSearch</tt> is adjusted so that its current index 0447 * (as returned by {@link #getOffset }) is the match position if one was 0448 * found. 0449 * If a match is not found, <tt>USEARCH_DONE</tt> will be returned and 0450 * the <tt>StringSearch</tt> will be adjusted to the index USEARCH_DONE. 0451 * @param position The index in the target text at which the search 0452 * starts 0453 * @param status for errors if any occurs 0454 * @return The index at which the matched text in the target starts, or 0455 * USEARCH_DONE if no match was found. 0456 * @stable ICU 2.0 0457 */ 0458 virtual int32_t handleNext(int32_t position, UErrorCode &status) override; 0459 0460 /** 0461 * Search backward for matching text, starting at a given location. 0462 * Clients should not call this method directly; instead they should call 0463 * <tt>SearchIterator.previous()</tt>, which this method overrides. 0464 * <p> 0465 * If a match is found, this method returns the index at which the match 0466 * starts and calls {@link SearchIterator#setMatchLength } with the number 0467 * of characters in the target text that make up the match. If no match 0468 * is found, the method returns <tt>USEARCH_DONE</tt>. 0469 * <p> 0470 * The <tt>StringSearch</tt> is adjusted so that its current index 0471 * (as returned by {@link #getOffset }) is the match position if one was 0472 * found. 0473 * If a match is not found, <tt>USEARCH_DONE</tt> will be returned and 0474 * the <tt>StringSearch</tt> will be adjusted to the index USEARCH_DONE. 0475 * @param position The index in the target text at which the search 0476 * starts. 0477 * @param status for errors if any occurs 0478 * @return The index at which the matched text in the target starts, or 0479 * USEARCH_DONE if no match was found. 0480 * @stable ICU 2.0 0481 */ 0482 virtual int32_t handlePrev(int32_t position, UErrorCode &status) override; 0483 0484 private : 0485 StringSearch() = delete; // default constructor not implemented 0486 0487 // private data members ---------------------------------------------- 0488 0489 /** 0490 * Pattern text 0491 * @stable ICU 2.0 0492 */ 0493 UnicodeString m_pattern_; 0494 /** 0495 * String search struct data 0496 * @stable ICU 2.0 0497 */ 0498 UStringSearch *m_strsrch_; 0499 0500 }; 0501 0502 U_NAMESPACE_END 0503 0504 #endif /* #if !UCONFIG_NO_COLLATION */ 0505 0506 #endif /* U_SHOW_CPLUSPLUS_API */ 0507 0508 #endif 0509
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|