1 /* BreakIterator.java -- Breaks text into elements
2 Copyright (C) 1998, 1999, 2001, 2004 Free Software Foundation, Inc.
4 This file is part of GNU Classpath.
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)
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.
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
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
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. */
41 import java
.util
.Locale
;
42 import java
.util
.MissingResourceException
;
43 import java
.util
.ResourceBundle
;
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.
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().
56 * @author Tom Tromey <tromey@cygnus.com>
57 * @author Aaron M. Renn (arenn@urbanophile.com)
58 * @date March 19, 1999
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.
64 public abstract class BreakIterator
implements Cloneable
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.
71 // The value was discovered by writing a test program.
72 public static final int DONE
= -1;
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.
79 protected BreakIterator ()
84 * Create a clone of this object.
86 public Object
clone ()
92 catch (CloneNotSupportedException e
)
99 * This method returns the index of the current text element boundary.
101 * @return The current text boundary.
103 public abstract int current ();
106 * This method returns the first text element boundary in the text being
109 * @return The first text boundary.
111 public abstract int first ();
114 * This methdod returns the offset of the text element boundary following
115 * the specified offset.
117 * @param offset The text index from which to find the next text boundary.
119 * @param The next text boundary following the specified index.
121 public abstract int following (int pos
);
124 * This method returns a list of locales for which instances of
125 * <code>BreakIterator</code> are available.
127 * @return A list of available locales
129 public static synchronized Locale
[] getAvailableLocales ()
131 Locale
[] l
= new Locale
[1];
136 private static BreakIterator
getInstance (String type
, Locale loc
)
142 = ResourceBundle
.getBundle("gnu.java.locale.LocaleInformation",
143 loc
, ClassLoader
.getSystemClassLoader());
144 className
= res
.getString(type
);
146 catch (MissingResourceException x
)
152 Class k
= Class
.forName(className
);
153 return (BreakIterator
) k
.newInstance();
155 catch (ClassNotFoundException x1
)
159 catch (InstantiationException x2
)
163 catch (IllegalAccessException x3
)
170 * This method returns an instance of <code>BreakIterator</code> that will
171 * iterate over characters as defined in the default locale.
173 * @return A <code>BreakIterator</code> instance for the default locale.
175 public static BreakIterator
getCharacterInstance ()
177 return getCharacterInstance (Locale
.getDefault());
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.
185 * @param locale The desired locale.
187 * @return A <code>BreakIterator</code> instance for the default locale.
189 public static BreakIterator
getCharacterInstance (Locale loc
)
191 BreakIterator r
= getInstance ("CharacterIterator", loc
);
193 r
= new gnu
.java
.text
.CharacterBreakIterator ();
198 * This method returns an instance of <code>BreakIterator</code> that will
199 * iterate over line breaks as defined in the default locale.
201 * @return A <code>BreakIterator</code> instance for the default locale.
203 public static BreakIterator
getLineInstance ()
205 return getLineInstance (Locale
.getDefault());
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.
213 * @param locale The desired locale.
215 * @return A <code>BreakIterator</code> instance for the default locale.
217 public static BreakIterator
getLineInstance (Locale loc
)
219 BreakIterator r
= getInstance ("LineIterator", loc
);
221 r
= new gnu
.java
.text
.LineBreakIterator ();
226 * This method returns an instance of <code>BreakIterator</code> that will
227 * iterate over sentences as defined in the default locale.
229 * @return A <code>BreakIterator</code> instance for the default locale.
231 public static BreakIterator
getSentenceInstance ()
233 return getSentenceInstance (Locale
.getDefault());
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.
241 * @param locale The desired locale.
243 * @return A <code>BreakIterator</code> instance for the default locale.
245 public static BreakIterator
getSentenceInstance (Locale loc
)
247 BreakIterator r
= getInstance ("SentenceIterator", loc
);
249 r
= new gnu
.java
.text
.SentenceBreakIterator ();
254 * This method returns the text this object is iterating over as a
255 * <code>CharacterIterator</code>.
257 * @param The text being iterated over.
259 public abstract CharacterIterator
getText ();
262 * This method returns an instance of <code>BreakIterator</code> that will
263 * iterate over words as defined in the default locale.
265 * @return A <code>BreakIterator</code> instance for the default locale.
267 public static BreakIterator
getWordInstance ()
269 return getWordInstance (Locale
.getDefault());
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.
277 * @param locale The desired locale.
279 * @return A <code>BreakIterator</code> instance for the default locale.
281 public static BreakIterator
getWordInstance (Locale loc
)
283 BreakIterator r
= getInstance ("WordIterator", loc
);
285 r
= new gnu
.java
.text
.WordBreakIterator ();
290 * This method tests whether or not the specified position is a text
293 * @param offset The text position to test.
295 * @return <code>true</code> if the position is a boundary,
296 * <code>false</code> otherwise.
298 public boolean isBoundary (int pos
)
302 return following (pos
- 1) == pos
;
306 * This method returns the last text element boundary in the text being
309 * @return The last text boundary.
311 public abstract int last ();
314 * This method returns the text element boundary following the current
317 * @return The next text boundary.
319 public abstract int next ();
322 * This method returns the n'th text element boundary following the current
325 * @param n The number of text element boundaries to skip.
327 * @return The next text boundary.
329 public abstract int next (int n
);
332 * This methdod returns the offset of the text element boundary preceding
333 * the specified offset.
335 * @param offset The text index from which to find the preceding
338 * @returns The next text boundary preceding the specified index.
340 public int preceding (int pos
)
342 if (following (pos
) == DONE
)
344 while (previous () >= pos
)
350 * This method returns the text element boundary preceding the current
353 * @return The previous text boundary.
355 public abstract int previous ();
358 * This method sets the text string to iterate over.
360 * @param str The <code>String</code> to iterate over.
362 public void setText (String newText
)
364 setText (new StringCharacterIterator (newText
));
368 * This method sets the text to iterate over from the specified
369 * <code>CharacterIterator</code>.
371 * @param ci The desired <code>CharacterIterator</code>.
373 public abstract void setText (CharacterIterator newText
);