Class SearchIterator

  • Direct Known Subclasses:
    StringSearch

    public abstract class SearchIterator
    extends java.lang.Object
    SearchIterator is an abstract base class that provides methods to search for a pattern within a text string. Instances of SearchIterator maintain a current position and scan over the target text, returning the indices the pattern is matched and the length of each match.

    SearchIterator defines a protocol for text searching. Subclasses provide concrete implementations of various search algorithms. For example, StringSearch implements language-sensitive pattern matching based on the comparison rules defined in a RuleBasedCollator object.

    Other options for searching include using a BreakIterator to restrict the points at which matches are detected.

    SearchIterator provides an API that is similar to that of other text iteration classes such as BreakIterator. Using this class, it is easy to scan through text looking for all occurrences of a given pattern. The following example uses a StringSearch object to find all instances of "fox" in the target string. Any other subclass of SearchIterator can be used in an identical manner.

    
     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()) {
         System.out.println("Found match at " + pos +
                 ", length is " + iter.getMatchLength());
     }
     
    See Also:
    BreakIterator, RuleBasedCollator
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  SearchIterator.ElementComparisonType
      Option to control how collation elements are compared.
      (package private) class  SearchIterator.Search
      Java port of ICU4C struct USearch (usrchimp.h) Note: ICU4J already exposed some protected members such as targetText, breakIterator and matchedLength as a part of stable APIs.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected BreakIterator breakIterator
      The BreakIterator to define the boundaries of a logical match.
      static int DONE
      DONE is returned by previous() and next() after all valid matches have been returned, and by first() and last() if there are no matches at all.
      protected int matchLength
      Length of the most current match in target text.
      (package private) SearchIterator.Search search_  
      protected java.text.CharacterIterator targetText
      Target text for searching.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected SearchIterator​(java.text.CharacterIterator target, BreakIterator breaker)
      Protected constructor for use by subclasses.
    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      int first()
      Returns the first index at which the string text matches the search pattern.
      int following​(int position)
      Returns the first index equal or greater than position at which the string text matches the search pattern.
      BreakIterator getBreakIterator()
      Returns the BreakIterator that is used to restrict the indexes at which matches are detected.
      SearchIterator.ElementComparisonType getElementComparisonType()
      Returns the collation element comparison type.
      abstract int getIndex()
      Return the current index in the text being searched.
      java.lang.String getMatchedText()
      Returns the text that was matched by the most recent call to first(), next(), previous(), or last().
      int getMatchLength()
      Returns the length of text in the string which matches the search pattern.
      int getMatchStart()
      Returns the index to the match in the text string that was searched.
      java.text.CharacterIterator getTarget()
      Return the string text to be searched.
      protected abstract int handleNext​(int start)
      Abstract method which subclasses override to provide the mechanism for finding the next match in the target text.
      protected abstract int handlePrevious​(int startAt)
      Abstract method which subclasses override to provide the mechanism for finding the previous match in the target text.
      boolean isOverlapping()
      Return true if the overlapping property has been set.
      int last()
      Returns the last index in the target text at which it matches the search pattern.
      int next()
      Returns the index of the next point at which the text matches the search pattern, starting from the current position The iterator is adjusted so that its current index (as returned by getIndex()) is the match position if one was found.
      int preceding​(int position)
      Returns the first index less than position at which the string text matches the search pattern.
      int previous()
      Returns the index of the previous point at which the string text matches the search pattern, starting at the current position.
      void reset()
      Resets the iteration.
      void setBreakIterator​(BreakIterator breakiter)
      Set the BreakIterator that will be used to restrict the points at which matches are detected.
      void setElementComparisonType​(SearchIterator.ElementComparisonType type)
      Sets the collation element comparison type.
      void setIndex​(int position)
      Sets the position in the target text at which the next search will start.
      protected void setMatchLength​(int length)
      Sets the length of the most recent match in the target text.
      protected void setMatchNotFound()
      Deprecated.
      This API is ICU internal only.
      void setOverlapping​(boolean allowOverlap)
      Determines whether overlapping matches are returned.
      void setTarget​(java.text.CharacterIterator text)
      Set the target text to be searched.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • SearchIterator

        protected SearchIterator​(java.text.CharacterIterator target,
                                 BreakIterator breaker)
        Protected constructor for use by subclasses. Initializes the iterator with the argument target text for searching and sets the BreakIterator. See class documentation for more details on the use of the target text and BreakIterator.
        Parameters:
        target - The target text to be searched.
        breaker - A BreakIterator that is used to determine the boundaries of a logical match. This argument can be null.
        Throws:
        java.lang.IllegalArgumentException - thrown when argument target is null, or of length 0
        See Also:
        BreakIterator
    • Method Detail

      • setIndex

        public void setIndex​(int position)

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

        Parameters:
        position - position from which to start the next search
        Throws:
        java.lang.IndexOutOfBoundsException - thrown if argument position is out of the target text range.
        See Also:
        getIndex()
      • setOverlapping

        public void setOverlapping​(boolean allowOverlap)
        Determines whether overlapping matches are returned. See the class documentation for more information about overlapping matches.

        The default setting of this property is false

        Parameters:
        allowOverlap - flag indicator if overlapping matches are allowed
        See Also:
        isOverlapping()
      • setBreakIterator

        public void setBreakIterator​(BreakIterator breakiter)
        Set the BreakIterator that will be used to restrict the points at which matches are detected.
        Parameters:
        breakiter - A BreakIterator that will be used to restrict the points at which matches are detected. If a match is found, but the match's start or end index is not a boundary as determined by the BreakIterator, the match will be rejected and another will be searched for. If this parameter is null, no break detection is attempted.
        See Also:
        BreakIterator
      • setTarget

        public void setTarget​(java.text.CharacterIterator text)
        Set the target text to be searched. Text iteration will then begin at the start of the text string. This method is useful if you want to reuse an iterator to search within a different body of text.
        Parameters:
        text - new text iterator to look for match,
        Throws:
        java.lang.IllegalArgumentException - thrown when text is null or has 0 length
        See Also:
        getTarget()
      • getMatchStart

        public int getMatchStart()
        Returns the index to the match in the text string that was searched. This call returns a valid result only after a successful call to first(), next(), previous(), or last(). Just after construction, or after a searching method returns DONE, this method will return DONE.

        Use getMatchLength() to get the matched string length.

        Returns:
        index of a substring within the text string that is being searched.
        See Also:
        first(), next(), previous(), last()
      • getIndex

        public abstract int getIndex()
        Return the current index in the text being searched. If the iteration has gone past the end of the text (or past the beginning for a backwards search), DONE is returned.
        Returns:
        current index in the text being searched.
      • getMatchLength

        public int getMatchLength()
        Returns the length of text in the string which matches the search pattern. This call returns a valid result only after a successful call to first(), next(), previous(), or last(). Just after construction, or after a searching method returns DONE, this method will return 0.
        Returns:
        The length of the match in the target text, or 0 if there is no match currently.
        See Also:
        first(), next(), previous(), last()
      • getTarget

        public java.text.CharacterIterator getTarget()
        Return the string text to be searched.
        Returns:
        text string to be searched.
      • getMatchedText

        public java.lang.String getMatchedText()
        Returns the text that was matched by the most recent call to first(), next(), previous(), or last(). If the iterator is not pointing at a valid match (e.g. just after construction or after DONE has been returned, returns an empty string.
        Returns:
        the substring in the target test of the most recent match, or null if there is no match currently.
        See Also:
        first(), next(), previous(), last()
      • next

        public int next()
        Returns the index of the next point at which the text matches the search pattern, starting from the current position The iterator is adjusted so that its current index (as returned by getIndex()) is the match position if one was found. If a match is not found, DONE will be returned and the iterator will be adjusted to a position after the end of the text string.
        Returns:
        The index of the next match after the current position, or DONE if there are no more matches.
        See Also:
        getIndex()
      • previous

        public int previous()
        Returns the index of the previous point at which the string text matches the search pattern, starting at the current position. The iterator is adjusted so that its current index (as returned by getIndex()) is the match position if one was found. If a match is not found, DONE will be returned and the iterator will be adjusted to the index DONE.
        Returns:
        The index of the previous match before the current position, or DONE if there are no more matches.
        See Also:
        getIndex()
      • isOverlapping

        public boolean isOverlapping()
        Return true if the overlapping property has been set. See setOverlapping(boolean) for more information.
        Returns:
        true if the overlapping property has been set, false otherwise
        See Also:
        setOverlapping(boolean)
      • reset

        public void reset()
        Resets the iteration. Search will begin at the start of the text string if a forward iteration is initiated before a backwards iteration. Otherwise if a backwards iteration is initiated before a forwards iteration, the search will begin at the end of the text string.
      • first

        public final int first()
        Returns the first index at which the string text matches the search pattern. The iterator is adjusted so that its current index (as returned by getIndex()) is the match position if one was found. If a match is not found, DONE will be returned and the iterator will be adjusted to the index DONE.
        Returns:
        The character index of the first match, or DONE if there are no matches.
        See Also:
        getIndex()
      • following

        public final int following​(int position)
        Returns the first index equal or greater than position at which the string text matches the search pattern. The iterator is adjusted so that its current index (as returned by getIndex()) is the match position if one was found. If a match is not found, DONE will be returned and the iterator will be adjusted to the index DONE.
        Parameters:
        position - where search if to start from.
        Returns:
        The character index of the first match following position, or DONE if there are no matches.
        Throws:
        java.lang.IndexOutOfBoundsException - If position is less than or greater than the text range for searching.
        See Also:
        getIndex()
      • last

        public final int last()
        Returns the last index in the target text at which it matches the search pattern. The iterator is adjusted so that its current index (as returned by getIndex()) is the match position if one was found. If a match is not found, DONE will be returned and the iterator will be adjusted to the index DONE.
        Returns:
        The index of the first match, or DONE if there are no matches.
        See Also:
        getIndex()
      • preceding

        public final int preceding​(int position)
        Returns the first index less than position at which the string text matches the search pattern. The iterator is adjusted so that its current index (as returned by getIndex()) is the match position if one was found. If a match is not found, DONE will be returned and the iterator will be adjusted to the index DONE

        When the overlapping option (isOverlapping()) is off, the last index of the result match is always less than position. When the overlapping option is on, the result match may span across position.

        Parameters:
        position - where search is to start from.
        Returns:
        The character index of the first match preceding position, or DONE if there are no matches.
        Throws:
        java.lang.IndexOutOfBoundsException - If position is less than or greater than the text range for searching
        See Also:
        getIndex()
      • setMatchLength

        protected void setMatchLength​(int length)
        Sets the length of the most recent match in the target text. Subclasses' handleNext() and handlePrevious() methods should call this after they find a match in the target text.
        Parameters:
        length - new length to set
        See Also:
        handleNext(int), handlePrevious(int)
      • handleNext

        protected abstract int handleNext​(int start)
        Abstract method which subclasses override to provide the mechanism for finding the next match in the target text. This allows different subclasses to provide different search algorithms.

        If a match is found, the implementation should return the index at which the match starts and should call setMatchLength(int) with the number of characters in the target text that make up the match. If no match is found, the method should return DONE.

        Parameters:
        start - The index in the target text at which the search should start.
        Returns:
        index at which the match starts, else if match is not found DONE is returned
        See Also:
        setMatchLength(int)
      • handlePrevious

        protected abstract int handlePrevious​(int startAt)
        Abstract method which subclasses override to provide the mechanism for finding the previous match in the target text. This allows different subclasses to provide different search algorithms.

        If a match is found, the implementation should return the index at which the match starts and should call setMatchLength(int) with the number of characters in the target text that make up the match. If no match is found, the method should return DONE.

        Parameters:
        startAt - The index in the target text at which the search should start.
        Returns:
        index at which the match starts, else if match is not found DONE is returned
        See Also:
        setMatchLength(int)
      • setMatchNotFound

        @Deprecated
        protected void setMatchNotFound()
        Deprecated.
        This API is ICU internal only.