jars/icu4j-52_1/main/classes/core/src/com/ibm/icu/text/UnicodeSetIterator.java

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