jpayne@69: * There are 2 match options for selection:
jpayne@69: * Let S' be the sub-string of a text string S between the offsets start and
jpayne@69: * end [start, end].
jpayne@69: *
jpayne@69: * A pattern string P matches a text string S at the offsets [start, end]
jpayne@69: * if
jpayne@69: *
jpayne@69: * option 1. Some canonical equivalent of P matches some canonical equivalent jpayne@69: * of S' jpayne@69: * option 2. P matches S' and if P starts or ends with a combining mark, jpayne@69: * there exists no non-ignorable combining mark before or after S? jpayne@69: * in S respectively. jpayne@69: *jpayne@69: * Option 2. will be the default. jpayne@69: *
jpayne@69: * This search has APIs similar to that of other text iteration mechanisms jpayne@69: * such as the break iterators in BreakIterator. Using these jpayne@69: * APIs, it is easy to scan through text looking for all occurrences of jpayne@69: * a given pattern. This search iterator allows changing of direction by jpayne@69: * calling a reset followed by a next or previous. jpayne@69: * Though a direction change can occur without calling reset first, jpayne@69: * this operation comes with some speed penalty. jpayne@69: * Match results in the forward direction will match the result matches in jpayne@69: * the backwards direction in the reverse order jpayne@69: *
jpayne@69: * SearchIterator provides APIs to specify the starting position jpayne@69: * within the text string to be searched, e.g. setOffset, jpayne@69: * preceding and following. Since the jpayne@69: * starting position will be set as it is specified, please take note that jpayne@69: * there are some danger points which the search may render incorrect jpayne@69: * results: jpayne@69: *
jpayne@69: * A BreakIterator can be used if only matches at logical breaks are desired. jpayne@69: * Using a BreakIterator will only give you results that exactly matches the jpayne@69: * boundaries given by the breakiterator. For instance the pattern "e" will jpayne@69: * not be found in the string "\u00e9" if a character break iterator is used. jpayne@69: *
jpayne@69: * Options are provided to handle overlapping matches. jpayne@69: * E.g. In English, overlapping matches produces the result 0 and 2 jpayne@69: * for the pattern "abab" in the text "ababab", where else mutually jpayne@69: * exclusive matches only produce the result of 0. jpayne@69: *
jpayne@69: * Though collator attributes will be taken into consideration while jpayne@69: * performing matches, there are no APIs here for setting and getting the jpayne@69: * attributes. These attributes can be set by getting the collator jpayne@69: * from getCollator and using the APIs in coll.h. jpayne@69: * Lastly to update StringSearch to the new collator attributes, jpayne@69: * reset has to be called. jpayne@69: *
jpayne@69: * Restriction:
jpayne@69: * Currently there are no composite characters that consists of a
jpayne@69: * character with combining class > 0 before a character with combining
jpayne@69: * class == 0. However, if such a character exists in the future,
jpayne@69: * StringSearch does not guarantee the results for option 1.
jpayne@69: *
jpayne@69: * Consult the SearchIterator documentation for information on jpayne@69: * and examples of how to use instances of this class to implement text jpayne@69: * searching. jpayne@69: *
jpayne@69: * UnicodeString target("The quick brown fox jumps over the lazy dog.");
jpayne@69: * UnicodeString pattern("fox");
jpayne@69: *
jpayne@69: * UErrorCode error = U_ZERO_ERROR;
jpayne@69: * StringSearch iter(pattern, target, Locale::getUS(), NULL, status);
jpayne@69: * for (int pos = iter.first(error);
jpayne@69: * pos != USEARCH_DONE;
jpayne@69: * pos = iter.next(error))
jpayne@69: * {
jpayne@69: * printf("Found match at %d pos, length is %d\n", pos, iter.getMatchedLength());
jpayne@69: * }
jpayne@69: * jpayne@69: * Note, StringSearch is not to be subclassed. jpayne@69: *
jpayne@69: * @see SearchIterator jpayne@69: * @see RuleBasedCollator jpayne@69: * @since ICU 2.0 jpayne@69: */ jpayne@69: jpayne@69: class U_I18N_API StringSearch U_FINAL : public SearchIterator jpayne@69: { jpayne@69: public: jpayne@69: jpayne@69: // public constructors and destructors -------------------------------- jpayne@69: jpayne@69: /** jpayne@69: * Creating a StringSearch instance using the argument locale jpayne@69: * language rule set. A collator will be created in the process, which jpayne@69: * will be owned by this instance and will be deleted during jpayne@69: * destruction jpayne@69: * @param pattern The text for which this object will search. jpayne@69: * @param text The text in which to search for the pattern. jpayne@69: * @param locale A locale which defines the language-sensitive jpayne@69: * comparison rules used to determine whether text in the jpayne@69: * pattern and target matches. jpayne@69: * @param breakiter A BreakIterator object used to constrain jpayne@69: * the matches that are found. Matches whose start and end jpayne@69: * indices in the target text are not boundaries as jpayne@69: * determined by the BreakIterator are jpayne@69: * ignored. If this behavior is not desired, jpayne@69: * NULL can be passed in instead. jpayne@69: * @param status for errors if any. If pattern or text is NULL, or if jpayne@69: * either the length of pattern or text is 0 then an jpayne@69: * U_ILLEGAL_ARGUMENT_ERROR is returned. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: StringSearch(const UnicodeString &pattern, const UnicodeString &text, jpayne@69: const Locale &locale, jpayne@69: BreakIterator *breakiter, jpayne@69: UErrorCode &status); jpayne@69: jpayne@69: /** jpayne@69: * Creating a StringSearch instance using the argument collator jpayne@69: * language rule set. Note, user retains the ownership of this collator, jpayne@69: * it does not get destroyed during this instance's destruction. jpayne@69: * @param pattern The text for which this object will search. jpayne@69: * @param text The text in which to search for the pattern. jpayne@69: * @param coll A RuleBasedCollator object which defines jpayne@69: * the language-sensitive comparison rules used to jpayne@69: * determine whether text in the pattern and target jpayne@69: * matches. User is responsible for the clearing of this jpayne@69: * object. jpayne@69: * @param breakiter A BreakIterator object used to constrain jpayne@69: * the matches that are found. Matches whose start and end jpayne@69: * indices in the target text are not boundaries as jpayne@69: * determined by the BreakIterator are jpayne@69: * ignored. If this behavior is not desired, jpayne@69: * NULL can be passed in instead. jpayne@69: * @param status for errors if any. If either the length of pattern or jpayne@69: * text is 0 then an U_ILLEGAL_ARGUMENT_ERROR is returned. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: StringSearch(const UnicodeString &pattern, jpayne@69: const UnicodeString &text, jpayne@69: RuleBasedCollator *coll, jpayne@69: BreakIterator *breakiter, jpayne@69: UErrorCode &status); jpayne@69: jpayne@69: /** jpayne@69: * Creating a StringSearch instance using the argument locale jpayne@69: * language rule set. A collator will be created in the process, which jpayne@69: * will be owned by this instance and will be deleted during jpayne@69: * destruction jpayne@69: *jpayne@69: * Note: No parsing of the text within the CharacterIterator jpayne@69: * will be done during searching for this version. The block of text jpayne@69: * in CharacterIterator will be used as it is. jpayne@69: * @param pattern The text for which this object will search. jpayne@69: * @param text The text iterator in which to search for the pattern. jpayne@69: * @param locale A locale which defines the language-sensitive jpayne@69: * comparison rules used to determine whether text in the jpayne@69: * pattern and target matches. User is responsible for jpayne@69: * the clearing of this object. jpayne@69: * @param breakiter A BreakIterator object used to constrain jpayne@69: * the matches that are found. Matches whose start and end jpayne@69: * indices in the target text are not boundaries as jpayne@69: * determined by the BreakIterator are jpayne@69: * ignored. If this behavior is not desired, jpayne@69: * NULL can be passed in instead. jpayne@69: * @param status for errors if any. If either the length of pattern or jpayne@69: * text is 0 then an U_ILLEGAL_ARGUMENT_ERROR is returned. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: StringSearch(const UnicodeString &pattern, CharacterIterator &text, jpayne@69: const Locale &locale, jpayne@69: BreakIterator *breakiter, jpayne@69: UErrorCode &status); jpayne@69: jpayne@69: /** jpayne@69: * Creating a StringSearch instance using the argument collator jpayne@69: * language rule set. Note, user retains the ownership of this collator, jpayne@69: * it does not get destroyed during this instance's destruction. jpayne@69: *
jpayne@69: * Note: No parsing of the text within the CharacterIterator jpayne@69: * will be done during searching for this version. The block of text jpayne@69: * in CharacterIterator will be used as it is. jpayne@69: * @param pattern The text for which this object will search. jpayne@69: * @param text The text in which to search for the pattern. jpayne@69: * @param coll A RuleBasedCollator object which defines jpayne@69: * the language-sensitive comparison rules used to jpayne@69: * determine whether text in the pattern and target jpayne@69: * matches. User is responsible for the clearing of this jpayne@69: * object. jpayne@69: * @param breakiter A BreakIterator object used to constrain jpayne@69: * the matches that are found. Matches whose start and end jpayne@69: * indices in the target text are not boundaries as jpayne@69: * determined by the BreakIterator are jpayne@69: * ignored. If this behavior is not desired, jpayne@69: * NULL can be passed in instead. jpayne@69: * @param status for errors if any. If either the length of pattern or jpayne@69: * text is 0 then an U_ILLEGAL_ARGUMENT_ERROR is returned. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: StringSearch(const UnicodeString &pattern, CharacterIterator &text, jpayne@69: RuleBasedCollator *coll, jpayne@69: BreakIterator *breakiter, jpayne@69: UErrorCode &status); jpayne@69: jpayne@69: /** jpayne@69: * Copy constructor that creates a StringSearch instance with the same jpayne@69: * behavior, and iterating over the same text. jpayne@69: * @param that StringSearch instance to be copied. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: StringSearch(const StringSearch &that); jpayne@69: jpayne@69: /** jpayne@69: * Destructor. Cleans up the search iterator data struct. jpayne@69: * If a collator is created in the constructor, it will be destroyed here. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual ~StringSearch(void); jpayne@69: jpayne@69: /** jpayne@69: * Clone this object. jpayne@69: * Clones can be used concurrently in multiple threads. jpayne@69: * If an error occurs, then NULL is returned. jpayne@69: * The caller must delete the clone. jpayne@69: * jpayne@69: * @return a clone of this object jpayne@69: * jpayne@69: * @see getDynamicClassID jpayne@69: * @stable ICU 2.8 jpayne@69: */ jpayne@69: StringSearch *clone() const; jpayne@69: jpayne@69: // operator overloading --------------------------------------------- jpayne@69: jpayne@69: /** jpayne@69: * Assignment operator. Sets this iterator to have the same behavior, jpayne@69: * and iterate over the same text, as the one passed in. jpayne@69: * @param that instance to be copied. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: StringSearch & operator=(const StringSearch &that); jpayne@69: jpayne@69: /** jpayne@69: * Equality operator. jpayne@69: * @param that instance to be compared. jpayne@69: * @return TRUE if both instances have the same attributes, jpayne@69: * breakiterators, collators and iterate over the same text jpayne@69: * while looking for the same pattern. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual UBool operator==(const SearchIterator &that) const; jpayne@69: jpayne@69: // public get and set methods ---------------------------------------- jpayne@69: jpayne@69: /** jpayne@69: * Sets the index to point to the given position, and clears any state jpayne@69: * that's affected. jpayne@69: *
jpayne@69: * This method takes the argument index and sets the position in the text jpayne@69: * string accordingly without checking if the index is pointing to a jpayne@69: * valid starting point to begin searching. jpayne@69: * @param position within the text to be set. If position is less jpayne@69: * than or greater than the text range for searching, jpayne@69: * an U_INDEX_OUTOFBOUNDS_ERROR will be returned jpayne@69: * @param status for errors if it occurs jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual void setOffset(int32_t position, UErrorCode &status); jpayne@69: jpayne@69: /** jpayne@69: * Return the current index in the text being searched. jpayne@69: * If the iteration has gone past the end of the text jpayne@69: * (or past the beginning for a backwards search), USEARCH_DONE jpayne@69: * is returned. jpayne@69: * @return current index in the text being searched. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual int32_t getOffset(void) const; jpayne@69: jpayne@69: /** jpayne@69: * Set the target text to be searched. jpayne@69: * Text iteration will hence begin at the start of the text string. jpayne@69: * This method is jpayne@69: * useful if you want to re-use an iterator to search for the same jpayne@69: * pattern within a different body of text. jpayne@69: * @param text text string to be searched jpayne@69: * @param status for errors if any. If the text length is 0 then an jpayne@69: * U_ILLEGAL_ARGUMENT_ERROR is returned. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual void setText(const UnicodeString &text, UErrorCode &status); jpayne@69: jpayne@69: /** jpayne@69: * Set the target text to be searched. jpayne@69: * Text iteration will hence begin at the start of the text string. jpayne@69: * This method is jpayne@69: * useful if you want to re-use an iterator to search for the same jpayne@69: * pattern within a different body of text. jpayne@69: * Note: No parsing of the text within the CharacterIterator jpayne@69: * will be done during searching for this version. The block of text jpayne@69: * in CharacterIterator will be used as it is. jpayne@69: * @param text text string to be searched jpayne@69: * @param status for errors if any. If the text length is 0 then an jpayne@69: * U_ILLEGAL_ARGUMENT_ERROR is returned. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual void setText(CharacterIterator &text, UErrorCode &status); jpayne@69: jpayne@69: /** jpayne@69: * Gets the collator used for the language rules. jpayne@69: *
jpayne@69: * Caller may modify but must not delete the RuleBasedCollator! jpayne@69: * Modifications to this collator will affect the original collator passed in to jpayne@69: * the StringSearch> constructor or to setCollator, if any. jpayne@69: * @return collator used for string search jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: RuleBasedCollator * getCollator() const; jpayne@69: jpayne@69: /** jpayne@69: * Sets the collator used for the language rules. User retains the jpayne@69: * ownership of this collator, thus the responsibility of deletion lies jpayne@69: * with the user. The iterator's position will not be changed by this method. jpayne@69: * @param coll collator jpayne@69: * @param status for errors if any jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: void setCollator(RuleBasedCollator *coll, UErrorCode &status); jpayne@69: jpayne@69: /** jpayne@69: * Sets the pattern used for matching. jpayne@69: * The iterator's position will not be changed by this method. jpayne@69: * @param pattern search pattern to be found jpayne@69: * @param status for errors if any. If the pattern length is 0 then an jpayne@69: * U_ILLEGAL_ARGUMENT_ERROR is returned. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: void setPattern(const UnicodeString &pattern, UErrorCode &status); jpayne@69: jpayne@69: /** jpayne@69: * Gets the search pattern. jpayne@69: * @return pattern used for matching jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: const UnicodeString & getPattern() const; jpayne@69: jpayne@69: // public methods ---------------------------------------------------- jpayne@69: jpayne@69: /** jpayne@69: * Reset the iteration. jpayne@69: * Search will begin at the start of the text string if a forward jpayne@69: * iteration is initiated before a backwards iteration. Otherwise if jpayne@69: * a backwards iteration is initiated before a forwards iteration, the jpayne@69: * search will begin at the end of the text string. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual void reset(); jpayne@69: jpayne@69: /** jpayne@69: * Returns a copy of StringSearch with the same behavior, and jpayne@69: * iterating over the same text, as this one. Note that all data will be jpayne@69: * replicated, except for the user-specified collator and the jpayne@69: * breakiterator. jpayne@69: * @return cloned object jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual StringSearch * safeClone() const; jpayne@69: jpayne@69: /** jpayne@69: * ICU "poor man's RTTI", returns a UClassID for the actual class. jpayne@69: * jpayne@69: * @stable ICU 2.2 jpayne@69: */ jpayne@69: virtual UClassID getDynamicClassID() const; jpayne@69: jpayne@69: /** jpayne@69: * ICU "poor man's RTTI", returns a UClassID for this class. jpayne@69: * jpayne@69: * @stable ICU 2.2 jpayne@69: */ jpayne@69: static UClassID U_EXPORT2 getStaticClassID(); jpayne@69: jpayne@69: protected: jpayne@69: jpayne@69: // protected method ------------------------------------------------- jpayne@69: jpayne@69: /** jpayne@69: * Search forward for matching text, starting at a given location. jpayne@69: * Clients should not call this method directly; instead they should jpayne@69: * call {@link SearchIterator#next }. jpayne@69: *
jpayne@69: * If a match is found, this method returns the index at which the match jpayne@69: * starts and calls {@link SearchIterator#setMatchLength } with the number jpayne@69: * of characters in the target text that make up the match. If no match jpayne@69: * is found, the method returns USEARCH_DONE. jpayne@69: *
jpayne@69: * The StringSearch is adjusted so that its current index jpayne@69: * (as returned by {@link #getOffset }) is the match position if one was jpayne@69: * found. jpayne@69: * If a match is not found, USEARCH_DONE will be returned and jpayne@69: * the StringSearch will be adjusted to the index USEARCH_DONE. jpayne@69: * @param position The index in the target text at which the search jpayne@69: * starts jpayne@69: * @param status for errors if any occurs jpayne@69: * @return The index at which the matched text in the target starts, or jpayne@69: * USEARCH_DONE if no match was found. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual int32_t handleNext(int32_t position, UErrorCode &status); jpayne@69: jpayne@69: /** jpayne@69: * Search backward for matching text, starting at a given location. jpayne@69: * Clients should not call this method directly; instead they should call jpayne@69: * SearchIterator.previous(), which this method overrides. jpayne@69: *
jpayne@69: * If a match is found, this method returns the index at which the match jpayne@69: * starts and calls {@link SearchIterator#setMatchLength } with the number jpayne@69: * of characters in the target text that make up the match. If no match jpayne@69: * is found, the method returns USEARCH_DONE. jpayne@69: *
jpayne@69: * The StringSearch is adjusted so that its current index jpayne@69: * (as returned by {@link #getOffset }) is the match position if one was jpayne@69: * found. jpayne@69: * If a match is not found, USEARCH_DONE will be returned and jpayne@69: * the StringSearch will be adjusted to the index USEARCH_DONE. jpayne@69: * @param position The index in the target text at which the search jpayne@69: * starts. jpayne@69: * @param status for errors if any occurs jpayne@69: * @return The index at which the matched text in the target starts, or jpayne@69: * USEARCH_DONE if no match was found. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual int32_t handlePrev(int32_t position, UErrorCode &status); jpayne@69: jpayne@69: private : jpayne@69: StringSearch(); // default constructor not implemented jpayne@69: jpayne@69: // private data members ---------------------------------------------- jpayne@69: jpayne@69: /** jpayne@69: * Pattern text jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: UnicodeString m_pattern_; jpayne@69: /** jpayne@69: * String search struct data jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: UStringSearch *m_strsrch_; jpayne@69: jpayne@69: }; jpayne@69: jpayne@69: U_NAMESPACE_END jpayne@69: jpayne@69: #endif /* #if !UCONFIG_NO_COLLATION */ jpayne@69: jpayne@69: #endif /* U_SHOW_CPLUSPLUS_API */ jpayne@69: jpayne@69: #endif jpayne@69: