// © 2016 and later: Unicode, Inc. and others. // License & terms of use: http://www.unicode.org/copyright.html /* ********************************************************************** * Copyright (c) 2002-2014, International Business Machines * Corporation and others. All Rights Reserved. ********************************************************************** */ #ifndef USETITER_H #define USETITER_H #include "unicode/utypes.h" #include "unicode/uobject.h" #include "unicode/unistr.h" /** * \file * \brief C++ API: UnicodeSetIterator iterates over the contents of a UnicodeSet. */ U_NAMESPACE_BEGIN class UnicodeSet; class UnicodeString; /** * * UnicodeSetIterator iterates over the contents of a UnicodeSet. It * iterates over either code points or code point ranges. After all * code points or ranges have been returned, it returns the * multicharacter strings of the UnicodeSet, if any. * * This class is not intended to be subclassed. Consider any fields * or methods declared as "protected" to be private. The use of * protected in this class is an artifact of history. * *

To iterate over code points and strings, use a loop like this: *

 * UnicodeSetIterator it(set);
 * while (it.next()) {
 *     processItem(it.getString());
 * }
 * 
*

Each item in the set is accessed as a string. Set elements * consisting of single code points are returned as strings containing * just the one code point. * *

To iterate over code point ranges, instead of individual code points, * use a loop like this: *

 * UnicodeSetIterator it(set);
 * while (it.nextRange()) {
 *   if (it.isString()) {
 *     processString(it.getString());
 *   } else {
 *     processCodepointRange(it.getCodepoint(), it.getCodepointEnd());
 *   }
 * }
 * 
* @author M. Davis * @stable ICU 2.4 */ class U_COMMON_API UnicodeSetIterator : public UObject { protected: /** * Value of codepoint if the iterator points to a string. * If codepoint == IS_STRING, then examine * string for the current iteration result. * @stable ICU 2.4 */ enum { IS_STRING = -1 }; /** * Current code point, or the special value IS_STRING, if * the iterator points to a string. * @stable ICU 2.4 */ UChar32 codepoint; /** * When iterating over ranges using nextRange(), * codepointEnd contains the inclusive end of the * iteration range, if codepoint != IS_STRING. If * iterating over code points using next(), or if * codepoint == IS_STRING, then the value of * codepointEnd is undefined. * @stable ICU 2.4 */ UChar32 codepointEnd; /** * If codepoint == IS_STRING, then string points * to the current string. If codepoint != IS_STRING, the * value of string is undefined. * @stable ICU 2.4 */ const UnicodeString* string; public: /** * Create an iterator over the given set. The iterator is valid * only so long as set is valid. * @param set set to iterate over * @stable ICU 2.4 */ UnicodeSetIterator(const UnicodeSet& set); /** * Create an iterator over nothing. next() and * nextRange() return false. This is a convenience * constructor allowing the target to be set later. * @stable ICU 2.4 */ UnicodeSetIterator(); /** * Destructor. * @stable ICU 2.4 */ virtual ~UnicodeSetIterator(); /** * Returns true if the current element is a string. If so, the * caller can retrieve it with getString(). If this * method returns false, the current element is a code point or * code point range, depending on whether next() or * nextRange() was called. * Elements of types string and codepoint can both be retrieved * with the function getString(). * Elements of type codepoint can also be retrieved with * getCodepoint(). * For ranges, getCodepoint() returns the starting codepoint * of the range, and getCodepointEnd() returns the end * of the range. * @stable ICU 2.4 */ inline UBool isString() const; /** * Returns the current code point, if isString() returned * false. Otherwise returns an undefined result. * @stable ICU 2.4 */ inline UChar32 getCodepoint() const; /** * Returns the end of the current code point range, if * isString() returned false and nextRange() was * called. Otherwise returns an undefined result. * @stable ICU 2.4 */ inline UChar32 getCodepointEnd() const; /** * Returns the current string, if isString() returned * true. If the current iteration item is a code point, a UnicodeString * containing that single code point is returned. * * Ownership of the returned string remains with the iterator. * The string is guaranteed to remain valid only until the iterator is * advanced to the next item, or until the iterator is deleted. * * @stable ICU 2.4 */ const UnicodeString& getString(); /** * Advances the iteration position to the next element in the set, * which can be either a single code point or a string. * If there are no more elements in the set, return false. * *

* If isString() == TRUE, the value is a * string, otherwise the value is a * single code point. Elements of either type can be retrieved * with the function getString(), while elements of * consisting of a single code point can be retrieved with * getCodepoint() * *

The order of iteration is all code points in sorted order, * followed by all strings sorted order. Do not mix * calls to next() and nextRange() without * calling reset() between them. The results of doing so * are undefined. * * @return true if there was another element in the set. * @stable ICU 2.4 */ UBool next(); /** * Returns the next element in the set, either a code point range * or a string. If there are no more elements in the set, return * false. If isString() == TRUE, the value is a * string and can be accessed with getString(). Otherwise the value is a * range of one or more code points from getCodepoint() to * getCodepointeEnd() inclusive. * *

The order of iteration is all code points ranges in sorted * order, followed by all strings sorted order. Ranges are * disjoint and non-contiguous. The value returned from getString() * is undefined unless isString() == TRUE. Do not mix calls to * next() and nextRange() without calling * reset() between them. The results of doing so are * undefined. * * @return true if there was another element in the set. * @stable ICU 2.4 */ UBool nextRange(); /** * Sets this iterator to visit the elements of the given set and * resets it to the start of that set. The iterator is valid only * so long as set is valid. * @param set the set to iterate over. * @stable ICU 2.4 */ void reset(const UnicodeSet& set); /** * Resets this iterator to the start of the set. * @stable ICU 2.4 */ void reset(); /** * ICU "poor man's RTTI", returns a UClassID for this class. * * @stable ICU 2.4 */ static UClassID U_EXPORT2 getStaticClassID(); /** * ICU "poor man's RTTI", returns a UClassID for the actual class. * * @stable ICU 2.4 */ virtual UClassID getDynamicClassID() const; // ======================= PRIVATES =========================== protected: // endElement and nextElements are really UChar32's, but we keep // them as signed int32_t's so we can do comparisons with // endElement set to -1. Leave them as int32_t's. /** The set * @stable ICU 2.4 */ const UnicodeSet* set; /** End range * @stable ICU 2.4 */ int32_t endRange; /** Range * @stable ICU 2.4 */ int32_t range; /** End element * @stable ICU 2.4 */ int32_t endElement; /** Next element * @stable ICU 2.4 */ int32_t nextElement; //UBool abbreviated; /** Next string * @stable ICU 2.4 */ int32_t nextString; /** String count * @stable ICU 2.4 */ int32_t stringCount; /** * Points to the string to use when the caller asks for a * string and the current iteration item is a code point, not a string. * @internal */ UnicodeString *cpString; /** Copy constructor. Disallowed. * @stable ICU 2.4 */ UnicodeSetIterator(const UnicodeSetIterator&); // disallow /** Assignment operator. Disallowed. * @stable ICU 2.4 */ UnicodeSetIterator& operator=(const UnicodeSetIterator&); // disallow /** Load range * @stable ICU 2.4 */ virtual void loadRange(int32_t range); }; inline UBool UnicodeSetIterator::isString() const { return codepoint == (UChar32)IS_STRING; } inline UChar32 UnicodeSetIterator::getCodepoint() const { return codepoint; } inline UChar32 UnicodeSetIterator::getCodepointEnd() const { return codepointEnd; } U_NAMESPACE_END #endif