Code example for CharacterIterator

Methods: getBeginIndex, getEndIndex, getIndex, setIndex

0
     *            of the target text range. 
     * @see #getIndex 
     * @stable ICU 2.8 
     */ 
    public void setIndex(int position) {
        if (position < targetText.getBeginIndex() 
            || position > targetText.getEndIndex()) {
            throw new IndexOutOfBoundsException(
                "setIndex(int) expected position to be between " + 
                targetText.getBeginIndex() + " and " + targetText.getEndIndex());
        } 
        m_setOffset_ = position;
        m_reset_ = false;
        matchLength = 0;
    } 
     
    /** 
     * <p> 
     * Determines whether overlapping matches are returned. See the class  
     * documentation for more information about overlapping matches. 
     * </p> 
     * <p> 
     * The default setting of this property is false 
     * </p> 
     * @param allowOverlap flag indicator if overlapping matches are allowed 
     * @see #isOverlapping 
     * @stable ICU 2.8 
     */ 
    public void setOverlapping(boolean allowOverlap)
    { 
        m_isOverlap_ = allowOverlap;
    } 
     
    /** 
     * Set the BreakIterator that is used to restrict the points at which  
     * matches are detected. 
     * Using <tt>null</tt> as the parameter is legal; it means that break  
     * detection should not be attempted. 
     * See class documentation for more information. 
     * @param breakiter A BreakIterator that will be used to restrict the  
     *                     points at which matches are detected. 
     * @see #getBreakIterator 
     * @see BreakIterator 
     * @stable ICU 2.0 
     */ 
    public void setBreakIterator(BreakIterator breakiter) 
    { 
        breakIterator = breakiter;
        if (breakIterator != null) {
            breakIterator.setText(targetText);
        } 
    } 
     
    /** 
     * 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. 
     * @param text new text iterator to look for match,  
     * @exception IllegalArgumentException thrown when text is null or has 
     *               0 length 
     * @see #getTarget 
     * @stable ICU 2.4 
     */ 
    public void setTarget(CharacterIterator text)
    { 
        if (text == null || text.getEndIndex() == text.getIndex()) {
            throw new IllegalArgumentException("Illegal null or empty text");
        } 
         
        targetText = text;
        targetText.setIndex(targetText.getBeginIndex());
        matchLength = 0;
        m_reset_ = true;
        m_isForwardSearching_ = true;
        if (breakIterator != null) {
            breakIterator.setText(targetText);
        } 
    } 
 
    // public getters ---------------------------------------------------- 
     
    /** 
     * <p> 
     * Returns the index of the most recent match in the target text. 
     * This call returns a valid result only after a successful call to  
     * {@link #first}, {@link #next}, {@link #previous}, or {@link #last}. 
     * Just after construction, or after a searching method returns  
     * <tt>DONE</tt>, this method will return <tt>DONE</tt>. 
     * </p> 
     * <p> 
     * Use <tt>getMatchLength</tt> to get the length of the matched text. 
     * <tt>getMatchedText</tt> will return the subtext in the searched  
     * target text from index getMatchStart() with length getMatchLength().  
     * </p> 
     * @return index to a substring within the text string that is being  
     *         searched. 
     * @see #getMatchLength 
     * @see #getMatchedText 
     * @see #first 
     * @see #next 
     * @see #previous 
     * @see #last 
     * @see #DONE 
     * @stable ICU 2.8 
     */ 
    public int getMatchStart() 
    { 
        return m_lastMatchStart_;
    } 
 
    /** 
     * Return the index in the target text at which the iterator is currently 
     * positioned.  
     * If the iteration has gone past the end of the target text, or past  
     * the beginning for a backwards search, {@link #DONE} is returned. 
     * @return index in the target text at which the iterator is currently  
     *         positioned. 
     * @stable ICU 2.8 
     * @see #first 
     * @see #next 
     * @see #previous 
     * @see #last 
     * @see #DONE 
     */ 
    public abstract int getIndex(); 
     
    /** 
     * <p> 
     * Returns the length of the most recent match in the target text.  
     * This call returns a valid result only after a successful 
     * call to {@link #first}, {@link #next}, {@link #previous}, or  
     * {@link #last}. 
     * Just after construction, or after a searching method returns 
     * <tt>DONE</tt>, this method will return 0. See getMatchStart() for  
     * more details. 
     * </p> 
     * @return The length of the most recent match in the target text, or 0 if  
     *         there is no match. 
     * @see #getMatchStart 
     * @see #getMatchedText 
     * @see #first 
     * @see #next 
     * @see #previous 
     * @see #last 
     * @see #DONE 
     * @stable ICU 2.0 
     */ 
    public int getMatchLength()  
    { 
        return matchLength;
    } 
     
    /** 
     * Returns the BreakIterator that is used to restrict the indexes at which  
     * matches are detected. This will be the same object that was passed to  
     * the constructor or to <code>setBreakIterator</code>. 
     * If the BreakIterator has not been set, <tt>null</tt> will be returned. 
     * See setBreakIterator for more information. 
     * @return the BreakIterator set to restrict logic matches 
     * @see #setBreakIterator 
     * @see BreakIterator 
     * @stable ICU 2.0 
     */ 
    public BreakIterator getBreakIterator() 
    { 
        return breakIterator;
    } 
     
    /** 
     * Return the target text that is being searched. 
     * @return target text being searched. 
     * @see #setTarget 
     * @stable ICU 2.0 
     */ 
    public CharacterIterator getTarget() 
    { 
        return targetText;
    } 
     
    /** 
     * Returns the text that was matched by the most recent call to  
     * {@link #first}, {@link #next}, {@link #previous}, or {@link #last}.  
     * If the iterator is not pointing at a valid match, for instance just  
     * after construction or after <tt>DONE</tt> has been returned, an empty  
     * String will be returned. See getMatchStart for more information 
     * @see #getMatchStart 
     * @see #getMatchLength 
     * @see #first 
     * @see #next 
     * @see #previous 
     * @see #last 
     * @see #DONE 
     * @return the substring in the target text of the most recent match  
     * @stable ICU 2.0 
     */ 
    public String getMatchedText() 
    { 
        if (matchLength > 0) {
            int limit = m_lastMatchStart_ + matchLength;
            StringBuilder result = new StringBuilder(matchLength);
            result.append(targetText.current());
            targetText.next();
            while (targetText.getIndex() < limit) {
                result.append(targetText.current());
                targetText.next();
            } 
            targetText.setIndex(m_lastMatchStart_);
            return result.toString();
        } 
        return null; 
    } 
 
    // miscellaneous public methods ----------------------------------------- 
         
    /** 
     * Search <b>forwards</b> in the target text for the next valid match, 
     * starting the search from the current iterator position. The iterator is  
     * adjusted so that its current index, as returned by {@link #getIndex}, 
     * is the starting position of the match if one was found. If a match is  
     * found, the index of the match is returned, otherwise <tt>DONE</tt> is 
     * returned.  If overlapping mode is set, the beginning of the found match 
     * can be before the end of the current match, if any. 
     * @return The starting index of the next forward match after the current  
     *         iterator position, or  
     *         <tt>DONE</tt> if there are no more matches. 
     * @see #getMatchStart 
     * @see #getMatchLength 
     * @see #getMatchedText 
     * @see #following 
     * @see #preceding 
     * @see #previous 
     * @see #first 
     * @see #last 
     * @see #DONE 
     * @stable ICU 2.0 
     */ 
    public int next() 
    { 
        int start = targetText.getIndex();
        if (m_setOffset_ != DONE) {
            start = m_setOffset_;    
            m_setOffset_ = DONE;    
        } 
        if (m_isForwardSearching_) {
            if (!m_reset_ && 
                start + matchLength >= targetText.getEndIndex()) {
                // not enough characters to match 
                matchLength = 0;
                targetText.setIndex(targetText.getEndIndex());
                m_lastMatchStart_ = DONE;
                return DONE; 
            } 
            m_reset_ = false;
        } 
        else { 
            // switching direction.  
            // if matchedIndex == USEARCH_DONE, it means that either a  
            // setIndex has been called or that previous ran off the text 
            // string. the iterator would have been set to offset 0 if a  
            // match is not found. 
            m_isForwardSearching_ = true;
            if (start != DONE) {
                // there's no need to set the collation element iterator 
                // the next call to next will set the offset. 
                return start;
            } 
        } 
         
        if (start == DONE) {
            start = targetText.getBeginIndex();
        } 
        if (matchLength > 0) {
            // if match length is 0 we are at the start of the iteration 
            if (m_isOverlap_) {
                start ++;
            } 
            else { 
                start += matchLength;
            } 
        } 
        m_lastMatchStart_ = handleNext(start);
        return m_lastMatchStart_;
    } 
 
    /** 
     * Search <b>backwards</b> in the target text for the next valid match, 
     * starting the search from the current iterator position. The iterator is  
     * adjusted so that its current index, as returned by {@link #getIndex}, 
     * is the starting position of the match if one was found. If a match is  
     * found, the index is returned, otherwise <tt>DONE</tt> is returned.  If 
     * overlapping mode is set, the end of the found match can be after the 
     * beginning of the previous match, if any. 
     * @return The starting index of the next backwards match after the current  
     *         iterator position, or  
     *         <tt>DONE</tt> if there are no more matches. 
     * @see #getMatchStart 
     * @see #getMatchLength 
     * @see #getMatchedText 
     * @see #following 
     * @see #preceding 
     * @see #next 
     * @see #first 
     * @see #last 
     * @see #DONE 
     * @stable ICU 2.0 
     */ 
    public int previous() 
    { 
        int start = targetText.getIndex();
        if (m_setOffset_ != DONE) {
            start = m_setOffset_;    
            m_setOffset_ = DONE;    
        } 
        if (m_reset_) {
            m_isForwardSearching_ = false;
            m_reset_ = false;
            start = targetText.getEndIndex();
        } 
         
        if (m_isForwardSearching_ == true) {
            // switching direction.  
            // if matchedIndex == USEARCH_DONE, it means that either a  
            // setIndex has been called or that next ran off the text 
            // string. the iterator would have been set to offset textLength if  
            // a match is not found. 
            m_isForwardSearching_ = false;
            if (start != targetText.getEndIndex()) {
                return start;
            } 
        } 
        else { 
            if (start == targetText.getBeginIndex()) {
                // not enough characters to match 
                matchLength = 0;
                targetText.setIndex(targetText.getBeginIndex());
                m_lastMatchStart_ = DONE;
                return DONE; 
            } 
        } 
 
        m_lastMatchStart_ = handlePrevious(start);
        return m_lastMatchStart_;
    } 
 
    /** 
     * Return true if the overlapping property has been set. 
     * See setOverlapping(boolean) for more information. 
     * @see #setOverlapping 
     * @return true if the overlapping property has been set, false otherwise 
     * @stable ICU 2.8 
     */ 
    public boolean isOverlapping()  
    { 
        return m_isOverlap_;
    } 
     
    /**  
     * <p> 
     * Resets the search iteration. All properties will be reset to their 
     * default values. 
     * </p> 
     * <p> 
     * 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. 
     * </p> 
     * @stable ICU 2.8 
     */ 
    public void reset() 
    { 
        // reset is setting the attributes that are already in string search 
        matchLength = 0;
        setIndex(targetText.getBeginIndex());
        m_isOverlap_ = false;
        m_isForwardSearching_ = true;
        m_reset_ = true;
        m_setOffset_ = DONE;
    } 
     
    /** 
     * Return the index of the first <b>forward</b> match in the target text.  
     * This method sets the iteration to begin at the start of the  
     * target text and searches forward from there. 
     * @return The index of the first forward match, or <code>DONE</code>  
     *            if there are no matches. 
     * @see #getMatchStart 
     * @see #getMatchLength 
     * @see #getMatchedText 
     * @see #following 
     * @see #preceding 
     * @see #next 
     * @see #previous 
     * @see #last 
     * @see #DONE 
     * @stable ICU 2.0 
     */ 
    public final int first()  
    { 
        m_isForwardSearching_ = true;
        setIndex(targetText.getBeginIndex());
        return next(); 
    } 
 
    /** 
     * Return the index of the first <b>forward</b> match in target text that  
     * is at or after argument <tt>position</tt>.  
     * This method sets the iteration to begin at the specified 
     * position in the the target text and searches forward from there. 
     * @return The index of the first forward match, or <code>DONE</code>  
     *         if there are no matches. 
     * @see #getMatchStart 
     * @see #getMatchLength 
     * @see #getMatchedText 
     * @see #first 
     * @see #preceding 
     * @see #next 
     * @see #previous 
     * @see #last 
     * @see #DONE 
     * @stable ICU 2.0 
     */ 
    public final int following(int position) 
    { 
        m_isForwardSearching_ = true;
        // position checked in usearch_setOffset 
        setIndex(position);
        return next(); 
    } 
     
    /** 
     * Return the index of the first <b>backward</b> match in target text.  
     * This method sets the iteration to begin at the end of the  
     * target text and searches backwards from there. 
     * @return The starting index of the first backward match, or  
     *         <code>DONE</code> if there are no matches. 
     * @see #getMatchStart 
     * @see #getMatchLength 
     * @see #getMatchedText 
     * @see #first 
     * @see #preceding 
     * @see #next 
     * @see #previous 
     * @see #following 
     * @see #DONE 
     * @stable ICU 2.0 
     */ 
    public final int last()  
    { 
        m_isForwardSearching_ = false;
        setIndex(targetText.getEndIndex());
        return previous(); 
    } 
      
    /** 
     * Return the index of the first <b>backwards</b> match in target