icuSources/common/unicode/usetiter.h

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