Java Doc for SearchIterator.java in  » Internationalization-Localization » icu4j » com » ibm » icu » text » Java Source Code / Java DocumentationJava Source Code and Java Documentation

SearchIterator is an abstract base class that defines a protocol for text searching. Subclasses provide concrete implementations of various search algorithms. A concrete subclass, StringSearch, is provided that implements language-sensitive pattern matching based on the comparison rules defined in a RuleBasedCollator object. Instances of SearchIterator maintain a current position and scan over the target text, returning the indices where a match is found and the length of each match. Generally, the sequence of forward matches will be equivalent to the sequence of backward matches.One case where this statement may not hold is when non-overlapping mode is set on and there are continuous repetitive patterns in the text. Consider the case searching for pattern "aba" in the text "ababababa", setting overlapping mode off will produce forward matches at offsets 0, 4. However when a backwards search is done, the results will be at offsets 6 and 2.

If matches searched for have boundary restrictions. BreakIterators can be used to define the valid boundaries of such a match. Once a BreakIterator is set, potential matches will be tested against the BreakIterator to determine if the boundaries are valid and that all characters in the potential match are equivalent to the pattern searched for. For example, looking for the pattern "fox" in the text "foxy fox" will produce match results at offset 0 and 5 with length 3 if no BreakIterators were set. However if a WordBreakIterator is set, the only match that would be found will be at the offset 5. Since, the SearchIterator guarantees that if a BreakIterator is set, all its matches will match the given pattern exactly, a potential match that passes the BreakIterator might still not produce a valid match. For instance the pattern "e" will not be found in the string "\u00e9" (latin small letter e with acute) if a CharacterBreakIterator is used. Even though "e" is a part of the character "\u00e9" and the potential match at offset 0 length 1 passes the CharacterBreakIterator test, "\u00e9" is not equivalent to "e", hence the SearchIterator rejects the potential match. By default, the SearchIterator does not impose any boundary restriction on the matches, it will return all results that match the pattern. Illustrating with the above example, "e" will be found in the string "\u00e9" if no BreakIterator is specified.

SearchIterator also provides a means to handle overlapping matches via the API setOverlapping(boolean). For example, if overlapping mode is set, searching for the pattern "abab" in the text "ababab" will match at positions 0 and 2, whereas if overlapping is not set, SearchIterator will only match at position 0. By default, overlapping mode is not set.

The APIs in SearchIterator are similar to that of other text iteration classes such as BreakIterator. Using this class, it is easy to scan through text looking for all occurances of a match.

Example of use:

 String target = "The quick brown fox jumped over the lazy fox";
 String pattern = "fox";
 SearchIterator iter = new StringSearch(pattern, target);
 for (int pos = iter.first(); pos != SearchIterator.DONE; 
 pos = iter.next()) {
 // println matches at offset 16 and 41 with length 3
 System.out.println("Found match at " + pos + ", length is " 
 + iter.getMatchLength());
 }
 target = "ababababa";
 pattern = "aba";
 iter.setTarget(new StringCharacterIterator(pattern));
 iter.setOverlapping(false);
 System.out.println("Overlapping mode set to false");
 System.out.println("Forward matches of pattern " + pattern + " in text "
 + text + ": ");
 for (int pos = iter.first(); pos != SearchIterator.DONE; 
 pos = iter.next()) {
 // println matches at offset 0 and 4 with length 3
 System.out.println("offset " + pos + ", length " 
 + iter.getMatchLength());
 }
 System.out.println("Backward matches of pattern " + pattern + " in text "
 + text + ": ");
 for (int pos = iter.last(); pos != SearchIterator.DONE; 
 pos = iter.previous()) {
 // println matches at offset 6 and 2 with length 3
 System.out.println("offset " + pos + ", length " 
 + iter.getMatchLength());
 }
 System.out.println("Overlapping mode set to true");
 System.out.println("Index set to 2");
 iter.setIndex(2);
 iter.setOverlapping(true);
 System.out.println("Forward matches of pattern " + pattern + " in text "
 + text + ": ");
 for (int pos = iter.first(); pos != SearchIterator.DONE; 
 pos = iter.next()) {
 // println matches at offset 2, 4 and 6 with length 3
 System.out.println("offset " + pos + ", length " 
 + iter.getMatchLength());
 }
 System.out.println("Index set to 2");
 iter.setIndex(2);
 System.out.println("Backward matches of pattern " + pattern + " in text "
 + text + ": ");
 for (int pos = iter.last(); pos != SearchIterator.DONE; 
 pos = iter.previous()) {
 // println matches at offset 0 with length 3
 System.out.println("offset " + pos + ", length " 
 + iter.getMatchLength());
 }
 

Returns the length of the most recent match in the target text.

Returns the index of the most recent match in the target text. This call returns a valid result only after a successful call to SearchIterator.first , SearchIterator.next , SearchIterator.previous , or SearchIterator.last . Just after construction, or after a searching method returns DONE, this method will return DONE.

Use getMatchLength to get the length of the matched text. getMatchedText will return the subtext in the searched target text from index getMatchStart() with length getMatchLength().

Abstract method that subclasses override to provide the mechanism for finding the next forwards match in the target text.

Abstract method which subclasses override to provide the mechanism for finding the next backwards match in the target text.

Resets the search iteration.

Sets the position in the target text at which the next search will start.

Determines whether overlapping matches are returned.

Returns the length of the most recent match in the target text. This call returns a valid result only after a successful call to SearchIterator.first , SearchIterator.next , SearchIterator.previous , or SearchIterator.last . Just after construction, or after a searching method returns DONE, this method will return 0. See getMatchStart() for more details.

Returns the index of the most recent match in the target text. This call returns a valid result only after a successful call to SearchIterator.first , SearchIterator.next , SearchIterator.previous , or SearchIterator.last . Just after construction, or after a searching method returns DONE, this method will return DONE.

Use getMatchLength to get the length of the matched text. getMatchedText will return the subtext in the searched target text from index getMatchStart() with length getMatchLength().

Abstract method that subclasses override to provide the mechanism for finding the next forwards match in the target text. This allows different subclasses to provide different search algorithms.

If a match is found, this function must call setMatchLength(int) to set the length of the result match. The iterator is adjusted so that its current index, as returned by SearchIterator.getIndex , is the starting position of the match if one was found. If a match is not found, DONE will be returned.

Abstract method which subclasses override to provide the mechanism for finding the next backwards match in the target text. This allows different subclasses to provide different search algorithms.

If a match is found, this function must call setMatchLength(int) to set the length of the result match. The iterator is adjusted so that its current index, as returned by SearchIterator.getIndex , is the starting position of the match if one was found. If a match is not found, DONE will be returned.

Resets the search iteration. All properties will be reset to their default values.

If a forward iteration is initiated, the next search will begin at the start of the target text. Otherwise, if a backwards iteration is initiated, the next search will begin at the end of the target text.

Sets the position in the target text at which the next search will start. This method clears any previous match.

Determines whether overlapping matches are returned. See the class documentation for more information about overlapping matches.

The default setting of this property is false