icuSources/common/unicode/usetiter.h

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