Source for java.text.StringCharacterIterator

   1: /* StringCharacterIterator.java -- Iterate over a character range in a string
   2:    Copyright (C) 1998, 1999, 2001, 2005  Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10:  
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package java.text;
  40: 
  41: /**
  42:  * This class iterates over a range of characters in a <code>String</code>.  
  43:  * For a given range of text, a beginning and ending index,
  44:  * as well as a current index are defined.  These values can be queried
  45:  * by the methods in this interface.  Additionally, various methods allow
  46:  * the index to be set. 
  47:  *
  48:  * @author Aaron M. Renn (arenn@urbanophile.com)
  49:  * @author Tom Tromey (tromey@cygnus.com)
  50:  */
  51: public final class StringCharacterIterator implements CharacterIterator
  52: {
  53:   /**
  54:    * This is the string to iterate over
  55:    */
  56:   private String text;
  57: 
  58:   /**
  59:    * This is the value of the start position of the text range.
  60:    */
  61:   private int begin;
  62: 
  63:   /**
  64:    * This is the value of the ending position of the text range.
  65:    */
  66:   private int end;
  67: 
  68:   /**
  69:    * This is the current value of the scan index.
  70:    */
  71:   private int index;
  72: 
  73:   /**
  74:    * This method initializes a new instance of
  75:    * <code>StringCharacterIterator</code> to iterate over the entire
  76:    * text of the specified <code>String</code>.  The initial index
  77:    * value will be set to the first character in the string.
  78:    *
  79:    * @param text The <code>String</code> to iterate through.
  80:    */
  81:   public StringCharacterIterator (String text)
  82:   {
  83:     this (text, 0, text.length (), 0);
  84:   }
  85: 
  86:   /*************************************************************************/
  87: 
  88:   /**
  89:    * This method initializes a new instance of
  90:    * <code>StringCharacterIterator</code> to iterate over the entire
  91:    * text of the specified <code>String</code>.  The initial index
  92:    * value will be set to the specified value.
  93:    *
  94:    * @param text The <code>String</code> to iterate through.
  95:    * @param index The initial index position.
  96:    */
  97:   public StringCharacterIterator (String text, int index)
  98:   {
  99:     this (text, 0, text.length (), index);
 100:   }
 101: 
 102:   /*************************************************************************/
 103: 
 104:   /**
 105:    * This method initializes a new instance of
 106:    * <code>StringCharacterIterator</code> that iterates over the text
 107:    * in a subrange of the specified <code>String</code>.  The
 108:    * beginning and end of the range are specified by the caller, as is
 109:    * the initial index position.
 110:    *
 111:    * @param text The <code>String</code> to iterate through.
 112:    * @param begin The beginning position in the character range.
 113:    * @param end The ending position in the character range.
 114:    * @param index The initial index position.
 115:    *
 116:    * @param IllegalArgumentException If any of the range values are
 117:    * invalid.
 118:    */
 119:   public StringCharacterIterator (String text, int begin, int end, int index)
 120:   {
 121:     int len = text.length ();
 122: 
 123:     if ((begin < 0) || (begin > len))
 124:       throw new IllegalArgumentException ("Bad begin position");
 125: 
 126:     if ((end < begin) || (end > len))
 127:       throw new IllegalArgumentException ("Bad end position");
 128: 
 129:     if ((index < begin) || (index > end))
 130:       throw new IllegalArgumentException ("Bad initial index position");
 131: 
 132:     this.text = text;
 133:     this.begin = begin;
 134:     this.end = end;
 135:     this.index = index;
 136:   }
 137: 
 138:   /**
 139:    * This is a package level constructor that copies the text out of
 140:    * an existing StringCharacterIterator and resets the beginning and
 141:    * ending index.
 142:    *
 143:    * @param scci The StringCharacterIterator to copy the info from
 144:    * @param begin The beginning index of the range we are interested in.
 145:    * @param end The ending index of the range we are interested in.
 146:    */
 147:   StringCharacterIterator (StringCharacterIterator sci, int begin, int end)
 148:   {
 149:     this (sci.text, begin, end, begin);
 150:   }
 151: 
 152:   /**
 153:    * This method returns the character at the current index position
 154:    *
 155:    * @return The character at the current index position.
 156:    */
 157:   public char current ()
 158:   {
 159:     return (index < end) ? text.charAt (index) : DONE;
 160:   }
 161: 
 162:   /*************************************************************************/
 163: 
 164:   /**
 165:    * This method increments the current index and then returns the
 166:    * character at the new index value.  If the index is already at
 167:    * <code>getEndIndex () - 1</code>, it will not be incremented.
 168:    *
 169:    * @return The character at the position of the incremented index
 170:    * value, or <code>DONE</code> if the index has reached
 171:    * getEndIndex () - 1.
 172:    */
 173:   public char next ()
 174:   {
 175:     if (index == end)
 176:       return DONE;
 177: 
 178:     ++index;
 179:     return current ();
 180:   }
 181: 
 182:   /*************************************************************************/
 183: 
 184:   /**
 185:    * This method decrements the current index and then returns the
 186:    * character at the new index value.  If the index value is already
 187:    * at the beginning index, it will not be decremented.
 188:    *
 189:    * @return The character at the position of the decremented index
 190:    * value, or <code>DONE</code> if index was already equal to the
 191:    * beginning index value.
 192:    */
 193:   public char previous ()
 194:   {
 195:     if (index == begin)
 196:       return DONE;
 197: 
 198:     --index;
 199:     return current ();
 200:   }
 201: 
 202:   /*************************************************************************/
 203: 
 204:   /**
 205:    * This method sets the index value to the beginning of the range and returns
 206:    * the character there.
 207:    *
 208:    * @return The character at the beginning of the range, or
 209:    * <code>DONE</code> if the range is empty. 
 210:    */
 211:   public char first ()
 212:   {
 213:     index = begin;
 214:     return current ();
 215:   }
 216: 
 217:   /*************************************************************************/
 218: 
 219:   /**
 220:    * This method sets the index value to <code>getEndIndex () - 1</code> and
 221:    * returns the character there.  If the range is empty, then the index value
 222:    * will be set equal to the beginning index.
 223:    *
 224:    * @return The character at the end of the range, or
 225:    * <code>DONE</code> if the range is empty. 
 226:    */
 227:   public char last ()
 228:   {
 229:     if (end == begin)
 230:       return DONE;
 231: 
 232:     index = end - 1;
 233:     return current ();
 234:   }
 235: 
 236:   /*************************************************************************/
 237: 
 238:   /**
 239:    * This method returns the current value of the index.
 240:    *
 241:    * @return The current index value
 242:    */
 243:   public int getIndex ()
 244:   {
 245:     return index;
 246:   }
 247: 
 248:   /*************************************************************************/
 249: 
 250:   /**
 251:    * This method sets the value of the index to the specified value, then
 252:    * returns the character at that position.
 253:    *
 254:    * @param index The new index value.
 255:    *
 256:    * @return The character at the new index value or <code>DONE</code>
 257:    * if the index value is equal to <code>getEndIndex</code>. 
 258:    *
 259:    * @exception IllegalArgumentException If the specified index is not valid
 260:    */
 261:   public char setIndex (int index)
 262:   {
 263:     if ((index < begin) || (index > end))
 264:       throw new IllegalArgumentException ("Bad index specified");
 265: 
 266:     this.index = index;
 267:     return current ();
 268:   }
 269: 
 270:   /*************************************************************************/
 271: 
 272:   /**
 273:    * This method returns the character position of the first character in the
 274:    * range.
 275:    *
 276:    * @return The index of the first character in the range.
 277:    */
 278:   public int getBeginIndex ()
 279:   {
 280:     return begin;
 281:   }
 282: 
 283:   /*************************************************************************/
 284: 
 285:   /**
 286:    * This method returns the character position of the end of the text range.
 287:    * This will actually be the index of the first character following the
 288:    * end of the range.  In the event the text range is empty, this will be
 289:    * equal to the first character in the range.
 290:    *
 291:    * @return The index of the end of the range.
 292:    */
 293:   public int getEndIndex ()
 294:   {
 295:     return end;
 296:   }
 297: 
 298:   /*************************************************************************/
 299: 
 300:   /**
 301:    * This method creates a copy of this <code>CharacterIterator</code>.
 302:    *
 303:    * @return A copy of this <code>CharacterIterator</code>.
 304:    */
 305:   public Object clone ()
 306:   {
 307:     return new StringCharacterIterator (text, begin, end, index);
 308:   }
 309: 
 310:   /*************************************************************************/
 311: 
 312:   /**
 313:    * This method tests this object for equality againt the specified 
 314:    * object.  This will be true if and only if the specified object:
 315:    * <p>
 316:    * <ul>
 317:    * <li>is not <code>null</code>.</li>
 318:    * <li>is an instance of <code>StringCharacterIterator</code></li>
 319:    * <li>has the same text as this object</li>
 320:    * <li>has the same beginning, ending, and current index as this object.</li>
 321:    * </ul>
 322:    *
 323:    * @param obj The object to test for equality against.
 324:    *
 325:    * @return <code>true</code> if the specified object is equal to this
 326:    * object, <code>false</code> otherwise.
 327:    */
 328:   public boolean equals (Object obj)
 329:   {
 330:     if (! (obj instanceof StringCharacterIterator))
 331:       return false;
 332: 
 333:     StringCharacterIterator sci = (StringCharacterIterator) obj;
 334: 
 335:     return (begin == sci.begin
 336:         && end == sci.end
 337:         && index == sci.index
 338:         && text.equals (sci.text));
 339:   }
 340: 
 341:   /*************************************************************************/
 342: 
 343:   /**
 344:    * This method allows other classes in java.text to change the value
 345:    * of the underlying text being iterated through.
 346:    *
 347:    * @param text The new <code>String</code> to iterate through.
 348:    */
 349:   public void setText (String text)
 350:   {
 351:     this.text = text;
 352:     this.begin = 0;
 353:     this.end = text.length ();
 354:     this.index = 0;
 355:   }
 356: }