To iterate over code points, use a loop like this: + * 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 (set.next()) {
- * if (set.isString()) {
- * processString(set.getString());
- * } else {
- * processCodepoint(set.getCodepoint());
- * }
+ * processItem(set.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, use a loop like this: + *
To iterate over code point ranges, instead of individual code points, + * use a loop like this: *
* UnicodeSetIterator it(set);
* while (it.nextRange()) {
@@ -115,9 +125,14 @@ class U_COMMON_API UnicodeSetIterator : public UObject {
* 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, and the caller can retrieve it
- * with getCodepoint() and, for a range,
- * getCodepointEnd().
+ * 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;
@@ -139,28 +154,37 @@ class U_COMMON_API UnicodeSetIterator : public UObject {
/**
* Returns the current string, if isString() returned
- * true. Otherwise returns an undefined result.
+ * 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
*/
- inline const UnicodeString& getString() const;
+ const UnicodeString& getString();
/**
- * Returns the next element in the set, either a single code point
- * or a string. If there are no more elements in the set, return
- * false. If codepoint == IS_STRING, the value is a
- * string in the string field. Otherwise the value is a
- * single code point in the codepoint field.
+ * 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. codepointEnd is
- * undefined after calling this method. string is
- * undefined unless codepoint == IS_STRING. Do not mix
+ * 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 and this
- * object contains the element.
+ * @return true if there was another element in the set.
* @stable ICU 2.4
*/
UBool next();
@@ -168,21 +192,20 @@ class U_COMMON_API UnicodeSetIterator : public UObject {
/**
* 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 codepoint == IS_STRING, the value is a
- * string in the string field. Otherwise the value is a
- * range of one or more code points from codepoint to
- * codepointeEnd inclusive.
+ * 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. string is undefined
- * unless codepoint == IS_STRING. Do not mix calls to
+ * 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 and this
- * object contains the element.
+ * @return true if there was another element in the set.
* @stable ICU 2.4
*/
UBool nextRange();
@@ -253,6 +276,13 @@ class U_COMMON_API UnicodeSetIterator : public UObject {
*/
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
*/
@@ -282,9 +312,6 @@ inline UChar32 UnicodeSetIterator::getCodepointEnd() const {
return codepointEnd;
}
-inline const UnicodeString& UnicodeSetIterator::getString() const {
- return *string;
-}
U_NAMESPACE_END