jars/icu4j-4_2_1-src/src/com/ibm/icu/text/UnicodeSetIterator.java

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