libjava/java/text/BreakIterator.java

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