OSDN Git Service

* java/text/SimpleDateFormat.java: Re-merged with Classpath.
[pf3gnuchains/gcc-fork.git] / 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 }