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