source/common/unicode/usetiter.h

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