151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski/* 26e42190c7f7d7cf3d8b787c918de0d797c6ddbbaPaul Duffin * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved. 351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This code is free software; you can redistribute it and/or modify it 651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * under the terms of the GNU General Public License version 2 only, as 751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * published by the Free Software Foundation. Oracle designates this 851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * particular file as subject to the "Classpath" exception as provided 951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * by Oracle in the LICENSE file that accompanied this code. 1051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 1151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This code is distributed in the hope that it will be useful, but WITHOUT 1251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * version 2 for more details (a copy is included in the LICENSE file that 1551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * accompanied this code). 1651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 1751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * You should have received a copy of the GNU General Public License version 1851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 2 along with this work; if not, write to the Free Software Foundation, 1951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 2151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * or visit www.oracle.com if you need additional information or have any 2351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * questions. 2451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 2551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 2651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski/* 2751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * (C) Copyright Taligent, Inc. 1996, 1997 - All Rights Reserved 2851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * (C) Copyright IBM Corp. 1996 - 1998 - All Rights Reserved 2951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 3051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The original version of this source code and documentation 3151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is copyrighted and owned by Taligent, Inc., a wholly-owned 3251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * subsidiary of IBM. These materials are provided under terms 3351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * of a License Agreement between Taligent and Sun. This technology 3451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is protected by multiple US and International patents. 3551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 3651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This notice and attribution to Taligent may not be removed. 3751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Taligent is a registered trademark of Taligent, Inc. 3851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 3951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 4051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 4151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskipackage java.text; 4251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 4351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 4451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski/** 4551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This interface defines a protocol for bidirectional iteration over text. 4651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The iterator iterates over a bounded sequence of characters. Characters 4751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * are indexed with values beginning with the value returned by getBeginIndex() and 4851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * continuing through the value returned by getEndIndex()-1. 4951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> 5051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Iterators maintain a current character index, whose valid range is from 5151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * getBeginIndex() to getEndIndex(); the value getEndIndex() is included to allow 5251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * handling of zero-length text ranges and for historical reasons. 5351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The current index can be retrieved by calling getIndex() and set directly 5451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * by calling setIndex(), first(), and last(). 5551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> 5651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The methods previous() and next() are used for iteration. They return DONE if 5751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * they would move outside the range from getBeginIndex() to getEndIndex() -1, 5851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * signaling that the iterator has reached the end of the sequence. DONE is 5951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * also returned by other methods to indicate that the current index is 6051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * outside this range. 6151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 6251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <P>Examples:<P> 6351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 6451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Traverse the text from start to finish 656e42190c7f7d7cf3d8b787c918de0d797c6ddbbaPaul Duffin * <pre>{@code 6651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * public void traverseForward(CharacterIterator iter) { 6751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * for(char c = iter.first(); c != CharacterIterator.DONE; c = iter.next()) { 6851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * processChar(c); 6951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * } 7051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * } 716e42190c7f7d7cf3d8b787c918de0d797c6ddbbaPaul Duffin * }</pre> 7251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 7351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Traverse the text backwards, from end to start 746e42190c7f7d7cf3d8b787c918de0d797c6ddbbaPaul Duffin * <pre>{@code 7551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * public void traverseBackward(CharacterIterator iter) { 7651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * for(char c = iter.last(); c != CharacterIterator.DONE; c = iter.previous()) { 7751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * processChar(c); 7851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * } 7951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * } 806e42190c7f7d7cf3d8b787c918de0d797c6ddbbaPaul Duffin * }</pre> 8151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 8251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Traverse both forward and backward from a given position in the text. 8351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Calls to notBoundary() in this example represents some 8451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * additional stopping criteria. 856e42190c7f7d7cf3d8b787c918de0d797c6ddbbaPaul Duffin * <pre>{@code 8651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * public void traverseOut(CharacterIterator iter, int pos) { 8751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * for (char c = iter.setIndex(pos); 8851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * c != CharacterIterator.DONE && notBoundary(c); 8951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * c = iter.next()) { 9051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * } 9151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * int end = iter.getIndex(); 9251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * for (char c = iter.setIndex(pos); 9351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * c != CharacterIterator.DONE && notBoundary(c); 9451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * c = iter.previous()) { 9551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * } 9651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * int start = iter.getIndex(); 9751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * processSection(start, end); 9851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * } 996e42190c7f7d7cf3d8b787c918de0d797c6ddbbaPaul Duffin * }</pre> 10051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 10151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see StringCharacterIterator 10251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see AttributedCharacterIterator 10351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 10451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 10551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskipublic interface CharacterIterator extends Cloneable 10651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski{ 10751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 10851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 10951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Constant that is returned when the iterator has reached either the end 11051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * or the beginning of the text. The value is '\\uFFFF', the "not a 11151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * character" value which should not occur in any valid Unicode string. 11251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 11351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public static final char DONE = '\uFFFF'; 11451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 11551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 11651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Sets the position to getBeginIndex() and returns the character at that 11751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * position. 11851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the first character in the text, or DONE if the text is empty 11951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #getBeginIndex() 12051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 12151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public char first(); 12251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 12351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 12451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Sets the position to getEndIndex()-1 (getEndIndex() if the text is empty) 12551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * and returns the character at that position. 12651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the last character in the text, or DONE if the text is empty 12751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #getEndIndex() 12851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 12951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public char last(); 13051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 13151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 13251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Gets the character at the current position (as returned by getIndex()). 13351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the character at the current position or DONE if the current 13451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * position is off the end of the text. 13551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #getIndex() 13651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 13751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public char current(); 13851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 13951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 14051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Increments the iterator's index by one and returns the character 14151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * at the new index. If the resulting index is greater or equal 14251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * to getEndIndex(), the current index is reset to getEndIndex() and 14351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * a value of DONE is returned. 14451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the character at the new position or DONE if the new 14551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * position is off the end of the text range. 14651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 14751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public char next(); 14851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 14951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 15051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Decrements the iterator's index by one and returns the character 15151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * at the new index. If the current index is getBeginIndex(), the index 15251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * remains at getBeginIndex() and a value of DONE is returned. 15351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the character at the new position or DONE if the current 15451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * position is equal to getBeginIndex(). 15551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 15651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public char previous(); 15751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 15851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 15951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Sets the position to the specified position in the text and returns that 16051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * character. 16151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param position the position within the text. Valid values range from 16251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * getBeginIndex() to getEndIndex(). An IllegalArgumentException is thrown 16351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * if an invalid value is supplied. 16451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the character at the specified position or DONE if the specified position is equal to getEndIndex() 16551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 16651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public char setIndex(int position); 16751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 16851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 16951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns the start index of the text. 17051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the index at which the text begins. 17151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 17251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public int getBeginIndex(); 17351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 17451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 17551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns the end index of the text. This index is the index of the first 17651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * character following the end of the text. 17751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the index after the last character in the text 17851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 17951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public int getEndIndex(); 18051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 18151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 18251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns the current index. 18351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the current index. 18451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 18551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public int getIndex(); 18651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 18751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 18851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Create a copy of this iterator 18951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return A copy of this 19051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 19151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public Object clone(); 19251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 19351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski} 194