jars/icu4j-52_1/main/tests/framework/src/com/ibm/icu/dev/util/UnicodeMapIterator.java

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