KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > ibm > icu > text > UnicodeSetIterator


1 /*
2  *******************************************************************************
3  * Copyright (C) 1996-2006, International Business Machines Corporation and *
4  * others. All Rights Reserved. *
5  *******************************************************************************
6  */
7 package com.ibm.icu.text;
8
9 import java.util.*;
10
11 /**
12  * UnicodeSetIterator iterates over the contents of a UnicodeSet. It
13  * iterates over either code points or code point ranges. After all
14  * code points or ranges have been returned, it returns the
15  * multicharacter strings of the UnicodSet, if any.
16  *
17  * <p>To iterate over code points, use a loop like this:
18  * <pre>
19  * UnicodeSetIterator it = new UnicodeSetIterator(set);
20  * while (set.next()) {
21  * if (set.codepoint != UnicodeSetIterator.IS_STRING) {
22  * processCodepoint(set.codepoint);
23  * } else {
24  * processString(set.string);
25  * }
26  * }
27  * </pre>
28  *
29  * <p>To iterate over code point ranges, use a loop like this:
30  * <pre>
31  * UnicodeSetIterator it = new UnicodeSetIterator(set);
32  * while (set.nextRange()) {
33  * if (set.codepoint != UnicodeSetIterator.IS_STRING) {
34  * processCodepointRange(set.codepoint, set.codepointEnd);
35  * } else {
36  * processString(set.string);
37  * }
38  * }
39  * </pre>
40  * @author M. Davis
41  * @stable ICU 2.0
42  */
43 public class UnicodeSetIterator {
44     
45     /**
46      * Value of <tt>codepoint</tt> if the iterator points to a string.
47      * If <tt>codepoint == IS_STRING</tt>, then examine
48      * <tt>string</tt> for the current iteration result.
49      * @stable ICU 2.0
50      */
51     public static int IS_STRING = -1;
52     
53     /**
54      * Current code point, or the special value <tt>IS_STRING</tt>, if
55      * the iterator points to a string.
56      * @stable ICU 2.0
57      */
58     public int codepoint;
59
60     /**
61      * When iterating over ranges using <tt>nextRange()</tt>,
62      * <tt>codepointEnd</tt> contains the inclusive end of the
63      * iteration range, if <tt>codepoint != IS_STRING</tt>. If
64      * iterating over code points using <tt>next()</tt>, or if
65      * <tt>codepoint == IS_STRING</tt>, then the value of
66      * <tt>codepointEnd</tt> is undefined.
67      * @stable ICU 2.0
68      */
69     public int codepointEnd;
70
71     /**
72      * If <tt>codepoint == IS_STRING</tt>, then <tt>string</tt> points
73      * to the current string. If <tt>codepoint != IS_STRING</tt>, the
74      * value of <tt>string</tt> is undefined.
75      * @stable ICU 2.0
76      */
77     public String JavaDoc string;
78
79     /**
80      * Create an iterator over the given set.
81      * @param set set to iterate over
82      * @stable ICU 2.0
83      */
84     public UnicodeSetIterator(UnicodeSet set) {
85         reset(set);
86     }
87         
88     /**
89      * Create an iterator over nothing. <tt>next()</tt> and
90      * <tt>nextRange()</tt> return false. This is a convenience
91      * constructor allowing the target to be set later.
92      * @stable ICU 2.0
93      */
94     public UnicodeSetIterator() {
95         reset(new UnicodeSet());
96     }
97         
98     /**
99      * Returns the next element in the set, either a single code point
100      * or a string. If there are no more elements in the set, return
101      * false. If <tt>codepoint == IS_STRING</tt>, the value is a
102      * string in the <tt>string</tt> field. Otherwise the value is a
103      * single code point in the <tt>codepoint</tt> field.
104      *
105      * <p>The order of iteration is all code points in sorted order,
106      * followed by all strings sorted order. <tt>codepointEnd</tt> is
107      * undefined after calling this method. <tt>string</tt> is
108      * undefined unless <tt>codepoint == IS_STRING</tt>. Do not mix
109      * calls to <tt>next()</tt> and <tt>nextRange()</tt> without
110      * calling <tt>reset()</tt> between them. The results of doing so
111      * are undefined.
112      *
113      * @return true if there was another element in the set and this
114      * object contains the element.
115      * @stable ICU 2.0
116      */
117     public boolean next() {
118         if (nextElement <= endElement) {
119             codepoint = codepointEnd = nextElement++;
120             return true;
121         }
122         if (range < endRange) {
123             loadRange(++range);
124             codepoint = codepointEnd = nextElement++;
125             return true;
126         }
127         
128         // stringIterator == null iff there are no string elements remaining
129
130         if (stringIterator == null) return false;
131         codepoint = IS_STRING; // signal that value is actually a string
132 string = (String JavaDoc)stringIterator.next();
133         if (!stringIterator.hasNext()) stringIterator = null;
134         return true;
135     }
136         
137     /**
138      * Returns the next element in the set, either a code point range
139      * or a string. If there are no more elements in the set, return
140      * false. If <tt>codepoint == IS_STRING</tt>, the value is a
141      * string in the <tt>string</tt> field. Otherwise the value is a
142      * range of one or more code points from <tt>codepoint</tt> to
143      * <tt>codepointeEnd</tt> inclusive.
144      *
145      * <p>The order of iteration is all code points ranges in sorted
146      * order, followed by all strings sorted order. Ranges are
147      * disjoint and non-contiguous. <tt>string</tt> is undefined
148      * unless <tt>codepoint == IS_STRING</tt>. Do not mix calls to
149      * <tt>next()</tt> and <tt>nextRange()</tt> without calling
150      * <tt>reset()</tt> between them. The results of doing so are
151      * undefined.
152      *
153      * @return true if there was another element in the set and this
154      * object contains the element.
155      * @stable ICU 2.0
156      */
157     public boolean nextRange() {
158         if (nextElement <= endElement) {
159             codepointEnd = endElement;
160             codepoint = nextElement;
161             nextElement = endElement+1;
162             return true;
163         }
164         if (range < endRange) {
165             loadRange(++range);
166             codepointEnd = endElement;
167             codepoint = nextElement;
168             nextElement = endElement+1;
169             return true;
170         }
171         
172         // stringIterator == null iff there are no string elements remaining
173
174         if (stringIterator == null) return false;
175         codepoint = IS_STRING; // signal that value is actually a string
176 string = (String JavaDoc)stringIterator.next();
177         if (!stringIterator.hasNext()) stringIterator = null;
178         return true;
179     }
180         
181     /**
182      * Sets this iterator to visit the elements of the given set and
183      * resets it to the start of that set. The iterator is valid only
184      * so long as <tt>set</tt> is valid.
185      * @param set the set to iterate over.
186      * @stable ICU 2.0
187      */
188     public void reset(UnicodeSet set) {
189         this.set = set;
190         reset();
191     }
192         
193     /**
194      * Resets this iterator to the start of the set.
195      * @stable ICU 2.0
196      */
197     public void reset() {
198         endRange = set.getRangeCount() - 1;
199         range = 0;
200         endElement = -1;
201         nextElement = 0;
202         if (endRange >= 0) {
203             loadRange(range);
204         }
205         stringIterator = null;
206         if (set.strings != null) {
207             stringIterator = set.strings.iterator();
208             if (!stringIterator.hasNext()) stringIterator = null;
209         }
210     }
211     
212     /**
213      * Gets the current string from the iterator. Only use after calling next(), not nextRange().
214      * @internal
215      * @deprecated This API is ICU internal only.
216      */
217     public String JavaDoc getString() {
218         if (codepoint != IS_STRING) {
219             return UTF16.valueOf(codepoint);
220         }
221         return string;
222     }
223     
224     // ======================= PRIVATES ===========================
225
226     private UnicodeSet set;
227     private int endRange = 0;
228     private int range = 0;
229     /**
230      * @internal
231      * @deprecated This API is ICU internal only.
232      */
233     protected int endElement;
234     /**
235      * @internal
236      * @deprecated This API is ICU internal only.
237      */
238     protected int nextElement;
239     private Iterator stringIterator = null;
240     
241     /**
242      * Invariant: stringIterator is null when there are no (more) strings remaining
243      */
244
245     /**
246      * @internal
247      * @deprecated This API is ICU internal only.
248      */
249     protected void loadRange(int range) {
250         nextElement = set.getRangeStart(range);
251         endElement = set.getRangeEnd(range);
252     }
253 }
254
Popular Tags