ICU-400.37.tar.gz

[apple/icu.git] / icuSources / common / unicode / usetiter.h

diff --git a/icuSources/common/unicode/usetiter.h b/icuSources/common/unicode/usetiter.h
index 9584b748061a1f33b23e4548a921d704b3a73e6e..defa75cd7ed690b0deba97c2b6b027d81df797b8 100644 (file)
--- a/icuSources/common/unicode/usetiter.h
+++ b/icuSources/common/unicode/usetiter.h
@@ -1,6 +1,6 @@
 /*
 **********************************************************************
 /*
 **********************************************************************

-* Copyright (c) 2002-2004, International Business Machines
+* Copyright (c) 2002-2006, International Business Machines

 * Corporation and others.  All Rights Reserved.
 **********************************************************************
 */
 * Corporation and others.  All Rights Reserved.
 **********************************************************************
 */


@@ -11,30 +11,40 @@
 #include "unicode/uobject.h"
 #include "unicode/unistr.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;
 
 /**
 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 UnicodSet, if any.
  *
  * 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 UnicodSet, if any.
  *

- * <p>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.
+ *
+ * <p>To iterate over code points and strings, use a loop like this:

  * <pre>
  * UnicodeSetIterator it(set);
  * while (set.next()) {
  * <pre>
  * UnicodeSetIterator it(set);
  * while (set.next()) {

- *   if (set.isString()) {
- *     processString(set.getString());
- *   } else {
- *     processCodepoint(set.getCodepoint());
- *   }
+ *     processItem(set.getString());

  * }
  * </pre>
  * }
  * </pre>

+ * <p>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.

  *
  *

- * <p>To iterate over code point ranges, use a loop like this:
+ * <p>To iterate over code point ranges, instead of individual code points,
+ *    use a loop like this:

  * <pre>
  * UnicodeSetIterator it(set);
  * while (it.nextRange()) {
  * <pre>
  * UnicodeSetIterator it(set);
  * while (it.nextRange()) {


@@ -115,9 +125,14 @@ class U_COMMON_API UnicodeSetIterator : public UObject {
      * caller can retrieve it with <tt>getString()</tt>.  If this
      * method returns false, the current element is a code point or
      * code point range, depending on whether <tt>next()</tt> or
      * caller can retrieve it with <tt>getString()</tt>.  If this
      * method returns false, the current element is a code point or
      * code point range, depending on whether <tt>next()</tt> or

-     * <tt>nextRange()</tt> was called, and the caller can retrieve it
-     * with <tt>getCodepoint()</tt> and, for a range,
-     * <tt>getCodepointEnd()</tt>.
+     * <tt>nextRange()</tt> was called.
+     * Elements of types string and codepoint can both be retrieved
+     * with the function <tt>getString()</tt>.
+     * Elements of type codepoint can also be retrieved with
+     * <tt>getCodepoint()</tt>.
+     * For ranges, <tt>getCodepoint()</tt> returns the starting codepoint
+     * of the range, and <tt>getCodepointEnd()</tt> returns the end
+     * of the range.

      * @stable ICU 2.4
      */
     inline UBool isString() const;
      * @stable ICU 2.4
      */
     inline UBool isString() const;


@@ -139,28 +154,37 @@ class U_COMMON_API UnicodeSetIterator : public UObject {
 
     /**
      * Returns the current string, if <tt>isString()</tt> returned
 
     /**
      * Returns the current string, if <tt>isString()</tt> 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
      */
      * @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 <tt>codepoint == IS_STRING</tt>, the value is a
-     * string in the <tt>string</tt> field.  Otherwise the value is a
-     * single code point in the <tt>codepoint</tt> 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.
+     *
+     * <p>
+     * If <tt>isString() == TRUE</tt>, the value is a
+     * string, otherwise the value is a
+     * single code point.  Elements of either type can be retrieved
+     * with the function <tt>getString()</tt>, while elements of
+     * consisting of a single code point can be retrieved with
+     * <tt>getCodepoint()</tt>

      *
      * <p>The order of iteration is all code points in sorted order,
      *
      * <p>The order of iteration is all code points in sorted order,

-     * followed by all strings sorted order.  <tt>codepointEnd</tt> is
-     * undefined after calling this method.  <tt>string</tt> is
-     * undefined unless <tt>codepoint == IS_STRING</tt>.  Do not mix
+     * followed by all strings sorted order.    Do not mix

      * calls to <tt>next()</tt> and <tt>nextRange()</tt> without
      * calling <tt>reset()</tt> between them.  The results of doing so
      * are undefined.
      *
      * calls to <tt>next()</tt> and <tt>nextRange()</tt> without
      * calling <tt>reset()</tt> 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();
      * @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
     /**
      * 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 <tt>codepoint == IS_STRING</tt>, the value is a
-     * string in the <tt>string</tt> field.  Otherwise the value is a
-     * range of one or more code points from <tt>codepoint</tt> to
-     * <tt>codepointeEnd</tt> inclusive.
+     * false.  If <tt>isString() == TRUE</tt>, the value is a
+     * string and can be accessed with <tt>getString()</tt>.  Otherwise the value is a
+     * range of one or more code points from <tt>getCodepoint()</tt> to
+     * <tt>getCodepointeEnd()</tt> inclusive.

      *
      * <p>The order of iteration is all code points ranges in sorted
      * order, followed by all strings sorted order.  Ranges are
      *
      * <p>The order of iteration is all code points ranges in sorted
      * order, followed by all strings sorted order.  Ranges are

-     * disjoint and non-contiguous.  <tt>string</tt> is undefined
-     * unless <tt>codepoint == IS_STRING</tt>.  Do not mix calls to
+     * disjoint and non-contiguous.  The value returned from <tt>getString()</tt>
+     * is undefined unless <tt>isString() == TRUE</tt>.  Do not mix calls to

      * <tt>next()</tt> and <tt>nextRange()</tt> without calling
      * <tt>reset()</tt> between them.  The results of doing so are
      * undefined.
      *
      * <tt>next()</tt> and <tt>nextRange()</tt> without calling
      * <tt>reset()</tt> 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();
      * @stable ICU 2.4
      */
     UBool nextRange();


@@ -253,6 +276,13 @@ class U_COMMON_API UnicodeSetIterator : public UObject {
      */
     int32_t stringCount;
 
      */
     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
      */
     /** Copy constructor. Disallowed.
      * @stable ICU 2.4
      */


@@ -282,9 +312,6 @@ inline UChar32 UnicodeSetIterator::getCodepointEnd() const {
     return codepointEnd;
 }
 
     return codepointEnd;
 }
 

-inline const UnicodeString& UnicodeSetIterator::getString() const {
-    return *string;
-}

 
 U_NAMESPACE_END
 
 
 U_NAMESPACE_END