icuSources/common/unicode/usetiter.h

   1 /*
   2 **********************************************************************
   3 * Copyright (c) 2002-2004, International Business Machines
   4 * Corporation and others.  All Rights Reserved.
   5 **********************************************************************
   6 */
   7 #ifndef USETITER_H
   8 #define USETITER_H
   9
  10 #include "unicode/utypes.h"
  11 #include "unicode/uobject.h"
  12 #include "unicode/unistr.h"
  13
  14 U_NAMESPACE_BEGIN
  15
  16 class UnicodeSet;
  17 class UnicodeString;
  18
  19 /**
  20  * UnicodeSetIterator iterates over the contents of a UnicodeSet.  It
  21  * iterates over either code points or code point ranges.  After all
  22  * code points or ranges have been returned, it returns the
  23  * multicharacter strings of the UnicodSet, if any.
  24  *
  25  * <p>To iterate over code points, use a loop like this:
  26  * <pre>
  27  * UnicodeSetIterator it(set);
  28  * while (set.next()) {
  29  *   if (set.isString()) {
  30  *     processString(set.getString());
  31  *   } else {
  32  *     processCodepoint(set.getCodepoint());
  33  *   }
  34  * }
  35  * </pre>
  36  *
  37  * <p>To iterate over code point ranges, use a loop like this:
  38  * <pre>
  39  * UnicodeSetIterator it(set);
  40  * while (it.nextRange()) {
  41  *   if (it.isString()) {
  42  *     processString(it.getString());
  43  *   } else {
  44  *     processCodepointRange(it.getCodepoint(), it.getCodepointEnd());
  45  *   }
  46  * }
  47  * </pre>
  48  * @author M. Davis
  49  * @stable ICU 2.4
  50  */
  51 class U_COMMON_API UnicodeSetIterator : public UObject {
  52
  53  protected:
  54
  55     /**
  56      * Value of <tt>codepoint</tt> if the iterator points to a string.
  57      * If <tt>codepoint == IS_STRING</tt>, then examine
  58      * <tt>string</tt> for the current iteration result.
  59      * @stable ICU 2.4
  60      */
  61     enum { IS_STRING = -1 };
  62
  63     /**
  64      * Current code point, or the special value <tt>IS_STRING</tt>, if
  65      * the iterator points to a string.
  66      * @stable ICU 2.4
  67      */
  68     UChar32 codepoint;
  69
  70     /**
  71      * When iterating over ranges using <tt>nextRange()</tt>,
  72      * <tt>codepointEnd</tt> contains the inclusive end of the
  73      * iteration range, if <tt>codepoint != IS_STRING</tt>.  If
  74      * iterating over code points using <tt>next()</tt>, or if
  75      * <tt>codepoint == IS_STRING</tt>, then the value of
  76      * <tt>codepointEnd</tt> is undefined.
  77      * @stable ICU 2.4
  78      */
  79     UChar32 codepointEnd;
  80
  81     /**
  82      * If <tt>codepoint == IS_STRING</tt>, then <tt>string</tt> points
  83      * to the current string.  If <tt>codepoint != IS_STRING</tt>, the
  84      * value of <tt>string</tt> is undefined.
  85      * @stable ICU 2.4
  86      */
  87     const UnicodeString* string;
  88
  89  public:
  90
  91     /**
  92      * Create an iterator over the given set.  The iterator is valid
  93      * only so long as <tt>set</tt> is valid.
  94      * @param set set to iterate over
  95      * @stable ICU 2.4
  96      */
  97     UnicodeSetIterator(const UnicodeSet& set);
  98
  99     /**
 100      * Create an iterator over nothing.  <tt>next()</tt> and
 101      * <tt>nextRange()</tt> return false. This is a convenience
 102      * constructor allowing the target to be set later.
 103      * @stable ICU 2.4
 104      */
 105     UnicodeSetIterator();
 106
 107     /**
 108      * Destructor.
 109      * @stable ICU 2.4
 110      */
 111     virtual ~UnicodeSetIterator();
 112
 113     /**
 114      * Returns true if the current element is a string.  If so, the
 115      * caller can retrieve it with <tt>getString()</tt>.  If this
 116      * method returns false, the current element is a code point or
 117      * code point range, depending on whether <tt>next()</tt> or
 118      * <tt>nextRange()</tt> was called, and the caller can retrieve it
 119      * with <tt>getCodepoint()</tt> and, for a range,
 120      * <tt>getCodepointEnd()</tt>.
 121      * @stable ICU 2.4
 122      */
 123     inline UBool isString() const;
 124
 125     /**
 126      * Returns the current code point, if <tt>isString()</tt> returned
 127      * false.  Otherwise returns an undefined result.
 128      * @stable ICU 2.4
 129      */
 130     inline UChar32 getCodepoint() const;
 131
 132     /**
 133      * Returns the end of the current code point range, if
 134      * <tt>isString()</tt> returned false and <tt>nextRange()</tt> was
 135      * called.  Otherwise returns an undefined result.
 136      * @stable ICU 2.4
 137      */
 138     inline UChar32 getCodepointEnd() const;
 139
 140     /**
 141      * Returns the current string, if <tt>isString()</tt> returned
 142      * true.  Otherwise returns an undefined result.
 143      * @stable ICU 2.4
 144      */
 145     inline const UnicodeString& getString() const;
 146
 147     /**
 148      * Returns the next element in the set, either a single code point
 149      * or a string.  If there are no more elements in the set, return
 150      * false.  If <tt>codepoint == IS_STRING</tt>, the value is a
 151      * string in the <tt>string</tt> field.  Otherwise the value is a
 152      * single code point in the <tt>codepoint</tt> field.
 153      *
 154      * <p>The order of iteration is all code points in sorted order,
 155      * followed by all strings sorted order.  <tt>codepointEnd</tt> is
 156      * undefined after calling this method.  <tt>string</tt> is
 157      * undefined unless <tt>codepoint == IS_STRING</tt>.  Do not mix
 158      * calls to <tt>next()</tt> and <tt>nextRange()</tt> without
 159      * calling <tt>reset()</tt> between them.  The results of doing so
 160      * are undefined.
 161      *
 162      * @return true if there was another element in the set and this
 163      * object contains the element.
 164      * @stable ICU 2.4
 165      */
 166     UBool next();
 167
 168     /**
 169      * Returns the next element in the set, either a code point range
 170      * or a string.  If there are no more elements in the set, return
 171      * false.  If <tt>codepoint == IS_STRING</tt>, the value is a
 172      * string in the <tt>string</tt> field.  Otherwise the value is a
 173      * range of one or more code points from <tt>codepoint</tt> to
 174      * <tt>codepointeEnd</tt> inclusive.
 175      *
 176      * <p>The order of iteration is all code points ranges in sorted
 177      * order, followed by all strings sorted order.  Ranges are
 178      * disjoint and non-contiguous.  <tt>string</tt> is undefined
 179      * unless <tt>codepoint == IS_STRING</tt>.  Do not mix calls to
 180      * <tt>next()</tt> and <tt>nextRange()</tt> without calling
 181      * <tt>reset()</tt> between them.  The results of doing so are
 182      * undefined.
 183      *
 184      * @return true if there was another element in the set and this
 185      * object contains the element.
 186      * @stable ICU 2.4
 187      */
 188     UBool nextRange();
 189
 190     /**
 191      * Sets this iterator to visit the elements of the given set and
 192      * resets it to the start of that set.  The iterator is valid only
 193      * so long as <tt>set</tt> is valid.
 194      * @param set the set to iterate over.
 195      * @stable ICU 2.4
 196      */
 197     void reset(const UnicodeSet& set);
 198
 199     /**
 200      * Resets this iterator to the start of the set.
 201      * @stable ICU 2.4
 202      */
 203     void reset();
 204
 205     /**
 206      * ICU "poor man's RTTI", returns a UClassID for this class.
 207      *
 208      * @stable ICU 2.4
 209      */
 210     static UClassID U_EXPORT2 getStaticClassID();
 211
 212     /**
 213      * ICU "poor man's RTTI", returns a UClassID for the actual class.
 214      *
 215      * @stable ICU 2.4
 216      */
 217     virtual UClassID getDynamicClassID() const;
 218
 219     // ======================= PRIVATES ===========================
 220
 221  protected:
 222
 223     // endElement and nextElements are really UChar32's, but we keep
 224     // them as signed int32_t's so we can do comparisons with
 225     // endElement set to -1.  Leave them as int32_t's.
 226     /** The set
 227      * @stable ICU 2.4
 228      */
 229     const UnicodeSet* set;
 230     /** End range
 231      * @stable ICU 2.4
 232      */
 233     int32_t endRange;
 234     /** Range
 235      * @stable ICU 2.4
 236      */
 237     int32_t range;
 238     /** End element
 239      * @stable ICU 2.4
 240      */
 241     int32_t endElement;
 242     /** Next element
 243      * @stable ICU 2.4
 244      */
 245     int32_t nextElement;
 246     //UBool abbreviated;
 247     /** Next string
 248      * @stable ICU 2.4
 249      */
 250     int32_t nextString;
 251     /** String count
 252      * @stable ICU 2.4
 253      */
 254     int32_t stringCount;
 255
 256     /** Copy constructor. Disallowed.
 257      * @stable ICU 2.4
 258      */
 259     UnicodeSetIterator(const UnicodeSetIterator&); // disallow
 260
 261     /** Assignment operator. Disallowed.
 262      * @stable ICU 2.4
 263      */
 264     UnicodeSetIterator& operator=(const UnicodeSetIterator&); // disallow
 265
 266     /** Load range
 267      * @stable ICU 2.4
 268      */
 269     virtual void loadRange(int32_t range);
 270
 271 };
 272
 273 inline UBool UnicodeSetIterator::isString() const {
 274     return codepoint == (UChar32)IS_STRING;
 275 }
 276
 277 inline UChar32 UnicodeSetIterator::getCodepoint() const {
 278     return codepoint;
 279 }
 280
 281 inline UChar32 UnicodeSetIterator::getCodepointEnd() const {
 282     return codepointEnd;
 283 }
 284
 285 inline const UnicodeString& UnicodeSetIterator::getString() const {
 286     return *string;
 287 }
 288
 289 U_NAMESPACE_END
 290
 291 #endif