001/* StringCharacterIterator.java -- Iterate over a character range in a string
002   Copyright (C) 1998, 1999, 2001, 2005  Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010 
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package java.text;
040
041/**
042 * This class iterates over a range of characters in a <code>String</code>.  
043 * For a given range of text, a beginning and ending index,
044 * as well as a current index are defined.  These values can be queried
045 * by the methods in this interface.  Additionally, various methods allow
046 * the index to be set. 
047 *
048 * @author Aaron M. Renn (arenn@urbanophile.com)
049 * @author Tom Tromey (tromey@cygnus.com)
050 */
051public final class StringCharacterIterator implements CharacterIterator
052{
053  /**
054   * This is the string to iterate over
055   */
056  private String text;
057
058  /**
059   * This is the value of the start position of the text range.
060   */
061  private int begin;
062
063  /**
064   * This is the value of the ending position of the text range.
065   */
066  private int end;
067
068  /**
069   * This is the current value of the scan index.
070   */
071  private int index;
072
073  /**
074   * This method initializes a new instance of
075   * <code>StringCharacterIterator</code> to iterate over the entire
076   * text of the specified <code>String</code>.  The initial index
077   * value will be set to the first character in the string.
078   *
079   * @param text The <code>String</code> to iterate through (<code>null</code> 
080   *             not permitted).
081   * 
082   * @throws NullPointerException if <code>text</code> is <code>null</code>.
083   */
084  public StringCharacterIterator (String text)
085  {
086    this (text, 0, text.length (), 0);
087  }
088
089  /*************************************************************************/
090
091  /**
092   * This method initializes a new instance of
093   * <code>StringCharacterIterator</code> to iterate over the entire
094   * text of the specified <code>String</code>.  The initial index
095   * value will be set to the specified value.
096   *
097   * @param text The <code>String</code> to iterate through.
098   * @param index The initial index position.
099   */
100  public StringCharacterIterator (String text, int index)
101  {
102    this (text, 0, text.length (), index);
103  }
104
105  /*************************************************************************/
106
107  /**
108   * This method initializes a new instance of
109   * <code>StringCharacterIterator</code> that iterates over the text
110   * in a subrange of the specified <code>String</code>.  The
111   * beginning and end of the range are specified by the caller, as is
112   * the initial index position.
113   *
114   * @param text The <code>String</code> to iterate through.
115   * @param begin The beginning position in the character range.
116   * @param end The ending position in the character range.
117   * @param index The initial index position.
118   *
119   * @throws IllegalArgumentException If any of the range values are
120   * invalid.
121   */
122  public StringCharacterIterator (String text, int begin, int end, int index)
123  {
124    int len = text.length ();
125
126    if ((begin < 0) || (begin > len))
127      throw new IllegalArgumentException ("Bad begin position");
128
129    if ((end < begin) || (end > len))
130      throw new IllegalArgumentException ("Bad end position");
131
132    if ((index < begin) || (index > end))
133      throw new IllegalArgumentException ("Bad initial index position");
134
135    this.text = text;
136    this.begin = begin;
137    this.end = end;
138    this.index = index;
139  }
140
141  /**
142   * This is a package level constructor that copies the text out of
143   * an existing StringCharacterIterator and resets the beginning and
144   * ending index.
145   *
146   * @param sci The StringCharacterIterator to copy the info from
147   * @param begin The beginning index of the range we are interested in.
148   * @param end The ending index of the range we are interested in.
149   */
150  StringCharacterIterator (StringCharacterIterator sci, int begin, int end)
151  {
152    this (sci.text, begin, end, begin);
153  }
154
155  /**
156   * This method returns the character at the current index position
157   *
158   * @return The character at the current index position.
159   */
160  public char current ()
161  {
162    return (index < end) ? text.charAt (index) : DONE;
163  }
164
165  /*************************************************************************/
166
167  /**
168   * This method increments the current index and then returns the
169   * character at the new index value.  If the index is already at
170   * <code>getEndIndex () - 1</code>, it will not be incremented.
171   *
172   * @return The character at the position of the incremented index
173   * value, or <code>DONE</code> if the index has reached
174   * getEndIndex () - 1.
175   */
176  public char next ()
177  {
178    if (index == end)
179      return DONE;
180
181    ++index;
182    return current ();
183  }
184
185  /*************************************************************************/
186
187  /**
188   * This method decrements the current index and then returns the
189   * character at the new index value.  If the index value is already
190   * at the beginning index, it will not be decremented.
191   *
192   * @return The character at the position of the decremented index
193   * value, or <code>DONE</code> if index was already equal to the
194   * beginning index value.
195   */
196  public char previous ()
197  {
198    if (index == begin)
199      return DONE;
200
201    --index;
202    return current ();
203  }
204
205  /*************************************************************************/
206
207  /**
208   * This method sets the index value to the beginning of the range and returns
209   * the character there.
210   *
211   * @return The character at the beginning of the range, or
212   * <code>DONE</code> if the range is empty. 
213   */
214  public char first ()
215  {
216    index = begin;
217    return current ();
218  }
219
220  /*************************************************************************/
221
222  /**
223   * This method sets the index value to <code>getEndIndex () - 1</code> and
224   * returns the character there.  If the range is empty, then the index value
225   * will be set equal to the beginning index.
226   *
227   * @return The character at the end of the range, or
228   * <code>DONE</code> if the range is empty. 
229   */
230  public char last ()
231  {
232    if (end == begin)
233      return DONE;
234
235    index = end - 1;
236    return current ();
237  }
238
239  /*************************************************************************/
240
241  /**
242   * This method returns the current value of the index.
243   *
244   * @return The current index value
245   */
246  public int getIndex ()
247  {
248    return index;
249  }
250
251  /*************************************************************************/
252
253  /**
254   * This method sets the value of the index to the specified value, then
255   * returns the character at that position.
256   *
257   * @param index The new index value.
258   *
259   * @return The character at the new index value or <code>DONE</code>
260   * if the index value is equal to <code>getEndIndex</code>. 
261   *
262   * @exception IllegalArgumentException If the specified index is not valid
263   */
264  public char setIndex (int index)
265  {
266    if ((index < begin) || (index > end))
267      throw new IllegalArgumentException ("Bad index specified");
268
269    this.index = index;
270    return current ();
271  }
272
273  /*************************************************************************/
274
275  /**
276   * This method returns the character position of the first character in the
277   * range.
278   *
279   * @return The index of the first character in the range.
280   */
281  public int getBeginIndex ()
282  {
283    return begin;
284  }
285
286  /*************************************************************************/
287
288  /**
289   * This method returns the character position of the end of the text range.
290   * This will actually be the index of the first character following the
291   * end of the range.  In the event the text range is empty, this will be
292   * equal to the first character in the range.
293   *
294   * @return The index of the end of the range.
295   */
296  public int getEndIndex ()
297  {
298    return end;
299  }
300
301  /*************************************************************************/
302
303  /**
304   * This method creates a copy of this <code>CharacterIterator</code>.
305   *
306   * @return A copy of this <code>CharacterIterator</code>.
307   */
308  public Object clone ()
309  {
310    return new StringCharacterIterator (text, begin, end, index);
311  }
312
313  /*************************************************************************/
314
315  /**
316   * This method tests this object for equality againt the specified 
317   * object.  This will be true if and only if the specified object:
318   * <p>
319   * <ul>
320   * <li>is not <code>null</code>.</li>
321   * <li>is an instance of <code>StringCharacterIterator</code></li>
322   * <li>has the same text as this object</li>
323   * <li>has the same beginning, ending, and current index as this object.</li>
324   * </ul>
325   *
326   * @param obj The object to test for equality against.
327   *
328   * @return <code>true</code> if the specified object is equal to this
329   * object, <code>false</code> otherwise.
330   */
331  public boolean equals (Object obj)
332  {
333    if (! (obj instanceof StringCharacterIterator))
334      return false;
335
336    StringCharacterIterator sci = (StringCharacterIterator) obj;
337
338    return (begin == sci.begin
339            && end == sci.end
340            && index == sci.index
341            && text.equals (sci.text));
342  }
343  
344  /**
345   * Return the hash code for this object.
346   * @return the hash code
347   */
348  public int hashCode()
349  {
350    // Incorporate all the data in a goofy way.
351    return begin ^ end ^ index ^ text.hashCode();
352  }
353
354  /*************************************************************************/
355
356  /**
357   * This method allows other classes in java.text to change the value
358   * of the underlying text being iterated through.
359   *
360   * @param text The new <code>String</code> to iterate through.
361   */
362  public void setText (String text)
363  {
364    this.text = text;
365    this.begin = 0;
366    this.end = text.length ();
367    this.index = 0;
368  }
369}