Source for java.text.BreakIterator

   1: /* BreakIterator.java -- Breaks text into elements
   2:    Copyright (C) 1998, 1999, 2001, 2004, 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: import java.util.Locale;
  42: import java.util.MissingResourceException;
  43: import java.util.ResourceBundle;
  44: 
  45: /**
  46:  * This class iterates over text elements such as words, lines, sentences,
  47:  * and characters.  It can only iterate over one of these text elements at
  48:  * a time.  An instance of this class configured for the desired iteration
  49:  * type is created by calling one of the static factory methods, not
  50:  * by directly calling a constructor.
  51:  *
  52:  * The standard iterators created by the factory methods in this
  53:  * class will be valid upon creation.  That is, their methods will
  54:  * not cause exceptions if called before you call setText().
  55:  *
  56:  * @author Tom Tromey (tromey@cygnus.com)
  57:  * @author Aaron M. Renn (arenn@urbanophile.com)
  58:  * @date March 19, 1999
  59:  */
  60: /* Written using "Java Class Libraries", 2nd edition, plus online
  61:  * API docs for JDK 1.2 beta from http://www.javasoft.com.
  62:  * Status:  Believed complete and correct to 1.1.
  63:  */
  64: public abstract class BreakIterator implements Cloneable
  65: {
  66:   /**
  67:    * This value is returned by the <code>next()</code> and
  68:    * <code>previous</code> in order to indicate that the end of the
  69:    * text has been reached.
  70:    */
  71:   // The value was discovered by writing a test program.
  72:   public static final int DONE = -1;
  73: 
  74:   /**
  75:    * This method initializes a new instance of <code>BreakIterator</code>.
  76:    * This protected constructor is available to subclasses as a default
  77:    * no-arg superclass constructor.
  78:    */
  79:   protected BreakIterator ()
  80:   {
  81:   }
  82: 
  83:   /**
  84:    * Create a clone of this object.
  85:    */
  86:   public Object clone ()
  87:   {
  88:     try
  89:       {
  90:         return super.clone();
  91:       }
  92:     catch (CloneNotSupportedException e)
  93:       {
  94:         return null;
  95:       }
  96:   }
  97:   
  98:   /**
  99:    * This method returns the index of the current text element boundary.
 100:    *
 101:    * @return The current text boundary.
 102:    */
 103:   public abstract int current ();
 104: 
 105:   /**
 106:    * This method returns the first text element boundary in the text being
 107:    * iterated over.
 108:    *
 109:    * @return The first text boundary.
 110:    */
 111:   public abstract int first ();
 112: 
 113:   /**
 114:    * This methdod returns the offset of the text element boundary following
 115:    * the specified offset.
 116:    *
 117:    * @param pos The text index from which to find the next text boundary.
 118:    *
 119:    * @return The next text boundary following the specified index.
 120:    */
 121:   public abstract int following (int pos);
 122: 
 123:   /**
 124:    * This method returns a list of locales for which instances of
 125:    * <code>BreakIterator</code> are available.
 126:    *
 127:    * @return A list of available locales
 128:    */
 129:   public static synchronized Locale[] getAvailableLocales ()
 130:   {
 131:     Locale[] l = new Locale[1];
 132:     l[0] = Locale.US;
 133:     return l;
 134:   }
 135: 
 136:   private static BreakIterator getInstance (String type, Locale loc)
 137:   {
 138:     String className;
 139:     try
 140:       {
 141:     ResourceBundle res
 142:       = ResourceBundle.getBundle("gnu.java.locale.LocaleInformation",
 143:                      loc, ClassLoader.getSystemClassLoader());
 144:     className = res.getString(type);
 145:       }
 146:     catch (MissingResourceException x)
 147:       {
 148:     return null;
 149:       }
 150:     try
 151:       {
 152:     Class k = Class.forName(className);
 153:     return (BreakIterator) k.newInstance();
 154:       }
 155:     catch (ClassNotFoundException x1)
 156:       {
 157:     return null;
 158:       }
 159:     catch (InstantiationException x2)
 160:       {
 161:     return null;
 162:       }
 163:     catch (IllegalAccessException x3)
 164:       {
 165:     return null;
 166:       }
 167:   }
 168: 
 169:   /**
 170:    * This method returns an instance of <code>BreakIterator</code> that will
 171:    * iterate over characters as defined in the default locale.
 172:    *
 173:    * @return A <code>BreakIterator</code> instance for the default locale.
 174:    */
 175:   public static BreakIterator getCharacterInstance ()
 176:   {
 177:     return getCharacterInstance (Locale.getDefault());
 178:   }
 179: 
 180:   /**
 181:    * This method returns an instance of <code>BreakIterator</code> that will
 182:    * iterate over characters as defined in the specified locale.  If the
 183:    * desired locale is not available, the default locale is used.
 184:    *
 185:    * @param locale The desired locale.
 186:    *
 187:    * @return A <code>BreakIterator</code> instance for the default locale.
 188:    */
 189:   public static BreakIterator getCharacterInstance (Locale locale)
 190:   {
 191:     BreakIterator r = getInstance ("CharacterIterator", locale);
 192:     if (r == null)
 193:       r = new gnu.java.text.CharacterBreakIterator ();
 194:     return r;
 195:   }
 196: 
 197:   /**
 198:    * This method returns an instance of <code>BreakIterator</code> that will
 199:    * iterate over line breaks as defined in the default locale.
 200:    *
 201:    * @return A <code>BreakIterator</code> instance for the default locale.
 202:    */
 203:   public static BreakIterator getLineInstance ()
 204:   {
 205:     return getLineInstance (Locale.getDefault());
 206:   }
 207: 
 208:   /**
 209:    * This method returns an instance of <code>BreakIterator</code> that will
 210:    * iterate over line breaks as defined in the specified locale.  If the
 211:    * desired locale is not available, the default locale is used.
 212:    *
 213:    * @param locale The desired locale.
 214:    *
 215:    * @return A <code>BreakIterator</code> instance for the default locale.
 216:    */
 217:   public static BreakIterator getLineInstance (Locale locale)
 218:   {
 219:     BreakIterator r = getInstance ("LineIterator", locale);
 220:     if (r == null)
 221:       r = new gnu.java.text.LineBreakIterator ();
 222:     return r;
 223:   }
 224: 
 225:   /**
 226:    * This method returns an instance of <code>BreakIterator</code> that will
 227:    * iterate over sentences as defined in the default locale.
 228:    *
 229:    * @return A <code>BreakIterator</code> instance for the default locale.
 230:    */
 231:   public static BreakIterator getSentenceInstance ()
 232:   {
 233:     return getSentenceInstance (Locale.getDefault());
 234:   }
 235: 
 236:   /**
 237:    * This method returns an instance of <code>BreakIterator</code> that will
 238:    * iterate over sentences as defined in the specified locale.  If the
 239:    * desired locale is not available, the default locale is used.
 240:    *
 241:    * @param locale The desired locale.
 242:    *
 243:    * @return A <code>BreakIterator</code> instance for the default locale.
 244:    */
 245:   public static BreakIterator getSentenceInstance (Locale locale)
 246:   {
 247:     BreakIterator r = getInstance ("SentenceIterator", locale);
 248:     if (r == null)
 249:       r = new gnu.java.text.SentenceBreakIterator ();
 250:     return r;
 251:   }
 252: 
 253:   /**
 254:    * This method returns the text this object is iterating over as a
 255:    * <code>CharacterIterator</code>.
 256:    *
 257:    * @return The text being iterated over.
 258:    */
 259:   public abstract CharacterIterator getText ();
 260: 
 261:   /**
 262:    * This method returns an instance of <code>BreakIterator</code> that will
 263:    * iterate over words as defined in the default locale.
 264:    *
 265:    * @return A <code>BreakIterator</code> instance for the default locale.
 266:    */
 267:   public static BreakIterator getWordInstance ()
 268:   {
 269:     return getWordInstance (Locale.getDefault());
 270:   }
 271: 
 272:   /**
 273:    * This method returns an instance of <code>BreakIterator</code> that will
 274:    * iterate over words as defined in the specified locale.  If the
 275:    * desired locale is not available, the default locale is used.
 276:    *
 277:    * @param locale The desired locale.
 278:    *
 279:    * @return A <code>BreakIterator</code> instance for the default locale.
 280:    */
 281:   public static BreakIterator getWordInstance (Locale locale)
 282:   {
 283:     BreakIterator r = getInstance ("WordIterator", locale);
 284:     if (r == null)
 285:       r = new gnu.java.text.WordBreakIterator ();
 286:     return r;
 287:   }
 288: 
 289:   /**
 290:    * This method tests whether or not the specified position is a text
 291:    * element boundary.
 292:    *
 293:    * @param pos The text position to test.
 294:    *
 295:    * @return <code>true</code> if the position is a boundary,
 296:    * <code>false</code> otherwise. 
 297:    */
 298:   public boolean isBoundary (int pos)
 299:   {
 300:     if (pos == 0)
 301:       return true;
 302:     return following (pos - 1) == pos;
 303:   }
 304: 
 305:   /**
 306:    * This method returns the last text element boundary in the text being
 307:    * iterated over.
 308:    *
 309:    * @return The last text boundary.
 310:    */
 311:   public abstract int last ();
 312: 
 313:   /**
 314:    * This method returns the text element boundary following the current
 315:    * text position.
 316:    *
 317:    * @return The next text boundary.
 318:    */
 319:   public abstract int next ();
 320: 
 321:   /**
 322:    * This method returns the n'th text element boundary following the current
 323:    * text position.
 324:    *
 325:    * @param n The number of text element boundaries to skip.
 326:    *
 327:    * @return The next text boundary.
 328:    */
 329:   public abstract int next (int n);
 330: 
 331:   /**
 332:    * This methdod returns the offset of the text element boundary preceding
 333:    * the specified offset.
 334:    *
 335:    * @param pos The text index from which to find the preceding text boundary. 
 336:    *
 337:    * @returns The next text boundary preceding the specified index.
 338:    */
 339:   public int preceding (int pos)
 340:   {
 341:     if (following (pos) == DONE)
 342:       last ();
 343:     while (previous () >= pos)
 344:       ;
 345:     return current ();
 346:   }
 347: 
 348:   /**
 349:    * This method returns the text element boundary preceding the current
 350:    * text position.
 351:    *
 352:    * @return The previous text boundary.
 353:    */
 354:   public abstract int previous ();
 355: 
 356:   /**
 357:    * This method sets the text string to iterate over.
 358:    *
 359:    * @param newText The <code>String</code> to iterate over.
 360:    */
 361:   public void setText (String newText)
 362:   {
 363:     setText (new StringCharacterIterator (newText));
 364:   }
 365: 
 366:   /**
 367:    * This method sets the text to iterate over from the specified
 368:    * <code>CharacterIterator</code>.
 369:    * 
 370:    * @param newText The desired <code>CharacterIterator</code>.
 371:    */
 372:   public abstract void setText (CharacterIterator newText);
 373: }