home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / text / CharacterIterator.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  6.5 KB  |  185 lines
  1. /*
  2.  * @(#)CharacterIterator.java    1.11 98/03/18
  3.  *
  4.  * (C) Copyright Taligent, Inc. 1996-1997 - All Rights Reserved
  5.  * (C) Copyright IBM Corp. 1996-1997 - All Rights Reserved
  6.  *
  7.  * Portions copyright (c) 1996-1998 Sun Microsystems, Inc. All Rights Reserved.
  8.  *
  9.  *   The original version of this source code and documentation is copyrighted
  10.  * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These
  11.  * materials are provided under terms of a License Agreement between Taligent
  12.  * and Sun. This technology is protected by multiple US and International
  13.  * patents. This notice and attribution to Taligent may not be removed.
  14.  *   Taligent is a registered trademark of Taligent, Inc.
  15.  *
  16.  * Permission to use, copy, modify, and distribute this software
  17.  * and its documentation for NON-COMMERCIAL purposes and without
  18.  * fee is hereby granted provided that this copyright notice
  19.  * appears in all copies. Please refer to the file "copyright.html"
  20.  * for further important copyright and licensing information.
  21.  *
  22.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF
  23.  * THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
  24.  * TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
  25.  * PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR
  26.  * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
  27.  * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
  28.  *
  29.  */
  30.  
  31. package java.text;
  32.  
  33.  
  34. /**
  35.  * This interface defines a protocol for bidirectional iteration over text.
  36.  * The iterator iterates over a bounded sequence of characters.  Characters
  37.  * are indexed with values beginning with the value returned by getBeginIndex() and
  38.  * continuing through the value returned by getEndIndex()-1.
  39.  * <p>
  40.  * Iterators maintain a current character index, whose valid range is from
  41.  * getBeginIndex() to getEndIndex(); the value getEndIndex() is included to allow
  42.  * handling of zero-length text ranges and for historical reasons.
  43.  * The current index can be retrieved by calling getIndex() and set directly
  44.  * by calling setIndex(), first(), and last().
  45.  * <p>
  46.  * The methods previous() and next() are used for iteration. They return DONE if
  47.  * they would move outside the range from getBeginIndex() to getEndIndex() -1,
  48.  * signaling that the iterator has reached the end of the sequence. DONE is
  49.  * also returned by other methods to indicate that the current index is
  50.  * outside this range.
  51.  *
  52.  * <P>Examples:<P>
  53.  *
  54.  * Traverse the text from start to finish
  55.  * <pre>
  56.  * public void traverseForward(CharacterIterator iter) {
  57.  *     for(char c = iter.first(); c != CharacterIterator.DONE; c = iter.next()) {
  58.  *         processChar(c);
  59.  *     }
  60.  * }
  61.  * </pre>
  62.  *
  63.  * Traverse the text backwards, from end to start
  64.  * <pre>
  65.  * public void traverseBackward(CharacterIterator iter) {
  66.  *     for(char c = iter.last(); c != CharacterIterator.DONE; c = iter.prev()) {
  67.  *         processChar(c);
  68.  *     }
  69.  * }
  70.  * </pre>
  71.  *
  72.  * Traverse both forward and backward from a given position in the text.
  73.  * Calls to notBoundary() in this example represents some
  74.  * additional stopping criteria.
  75.  * <pre>
  76.  * public void traverseOut(CharacterIterator iter, int pos) {
  77.  *     for (char c = iter.setIndex(pos);
  78.  *              c != CharacterIterator.DONE && notBoundary(c);
  79.  *              c = iter.next()) {
  80.  *     }
  81.  *     int end = iter.getIndex();
  82.  *     for (char c = iter.setIndex(pos);
  83.  *             c != CharacterIterator.DONE && notBoundary(c);
  84.  *             c = iter.prev()) {
  85.  *     }
  86.  *     int start = iter.getIndex();
  87.  *     processSection(start, end);
  88.  * }
  89.  * </pre>
  90.  *
  91.  * @see StringCharacterIterator
  92.  * @see AttributedCharacterIterator
  93.  */
  94.  
  95. public interface CharacterIterator extends Cloneable
  96. {
  97.  
  98.     /**
  99.      * Constant that is returned when the iterator has reached either the end
  100.      * or the beginning of the text.  The unicode 2.0 standard states that
  101.      * '\\uFFFF' is an invalid unicode value and should not occur in any valid
  102.      * unicode string.
  103.      */
  104.     public static final char DONE = '\uFFFF';
  105.  
  106.     /**
  107.      * Sets the position to getBeginIndex() and returns the character at that
  108.      * position.
  109.      * @return the first character in the text, or DONE if the text is empty
  110.      * @see getBeginIndex
  111.      */
  112.     public char first();
  113.  
  114.     /**
  115.      * Sets the position to getEndIndex()-1 (getEndIndex() if the text is empty)
  116.      * and returns the character at that position.
  117.      * @return the last character in the text, or DONE if the text is empty
  118.      * @see getEndIndex
  119.      */
  120.     public char last();
  121.  
  122.     /**
  123.      * Gets the character at the current position (as returned by getIndex()).
  124.      * @return the character at the current position or DONE if the current
  125.      * position is off the end of the text.
  126.      * @see getIndex
  127.      */
  128.     public char current();
  129.  
  130.     /**
  131.      * Increments the iterator's index by one and returns the character
  132.      * at the new index.  If the resulting index is greater or equal
  133.      * to getEndIndex(), the current index is reset to getEndIndex() and
  134.      * a value of DONE is returned.
  135.      * @return the character at the new position or DONE if the new
  136.      * position is off the end of the text range.
  137.      */
  138.     public char next();
  139.  
  140.     /**
  141.      * Decrements the iterator's index by one and returns the character
  142.      * at the new index. If the current index is getBeginIndex(), the index
  143.      * remains at getBeginIndex() and a value of DONE is returned.
  144.      * @return the character at the new position or DONE if the current
  145.      * position is equal to getBeginIndex().
  146.      */
  147.     public char previous();
  148.  
  149.     /**
  150.      * Sets the position to the specified position in the text and returns that
  151.      * character.
  152.      * @param position the position within the text.  Valid values range from
  153.      * getBeginIndex() to getEndIndex().  An IllegalArgumentException is thrown
  154.      * if an invalid value is supplied.
  155.      * @return the character at the specified position or DONE if the specified position is equal to getEndIndex()
  156.      */
  157.     public char setIndex(int position);
  158.  
  159.     /**
  160.      * Returns the start index of the text.
  161.      * @return the index at which the text begins.
  162.      */
  163.     public int getBeginIndex();
  164.  
  165.     /**
  166.      * Returns the end index of the text.  This index is the index of the first
  167.      * character following the end of the text.
  168.      * @return the index after the last character in the text
  169.      */
  170.     public int getEndIndex();
  171.  
  172.     /**
  173.      * Returns the current index.
  174.      * @return the current index.
  175.      */
  176.     public int getIndex();
  177.  
  178.     /**
  179.      * Create a copy of this iterator
  180.      * @return A copy of this
  181.      */
  182.     public Object clone();
  183.  
  184. }
  185.