icuSources/common/unicode/strenum.h

   1 // © 2016 and later: Unicode, Inc. and others.
   2 // License & terms of use: http://www.unicode.org/copyright.html
   3 /*
   4 *******************************************************************************
   5 *
   6 *   Copyright (C) 2002-2012, International Business Machines
   7 *   Corporation and others.  All Rights Reserved.
   8 *
   9 *******************************************************************************
  10 */
  11
  12 #ifndef STRENUM_H
  13 #define STRENUM_H
  14
  15 #include "unicode/uobject.h"
  16 #include "unicode/unistr.h"
  17
  18 /**
  19  * \file
  20  * \brief C++ API: String Enumeration
  21  */
  22
  23 #if U_SHOW_CPLUSPLUS_API
  24 U_NAMESPACE_BEGIN
  25
  26 /**
  27  * Base class for 'pure' C++ implementations of uenum api.  Adds a
  28  * method that returns the next UnicodeString since in C++ this can
  29  * be a common storage format for strings.
  30  *
  31  * <p>The model is that the enumeration is over strings maintained by
  32  * a 'service.'  At any point, the service might change, invalidating
  33  * the enumerator (though this is expected to be rare).  The iterator
  34  * returns an error if this has occurred.  Lack of the error is no
  35  * guarantee that the service didn't change immediately after the
  36  * call, so the returned string still might not be 'valid' on
  37  * subsequent use.</p>
  38  *
  39  * <p>Strings may take the form of const char*, const char16_t*, or const
  40  * UnicodeString*.  The type you get is determine by the variant of
  41  * 'next' that you call.  In general the StringEnumeration is
  42  * optimized for one of these types, but all StringEnumerations can
  43  * return all types.  Returned strings are each terminated with a NUL.
  44  * Depending on the service data, they might also include embedded NUL
  45  * characters, so API is provided to optionally return the true
  46  * length, counting the embedded NULs but not counting the terminating
  47  * NUL.</p>
  48  *
  49  * <p>The pointers returned by next, unext, and snext become invalid
  50  * upon any subsequent call to the enumeration's destructor, next,
  51  * unext, snext, or reset.</p>
  52  *
  53  * ICU 2.8 adds some default implementations and helper functions
  54  * for subclasses.
  55  *
  56  * @stable ICU 2.4
  57  */
  58 class U_COMMON_API StringEnumeration : public UObject {
  59 public:
  60     /**
  61      * Destructor.
  62      * @stable ICU 2.4
  63      */
  64     virtual ~StringEnumeration();
  65
  66     /**
  67      * Clone this object, an instance of a subclass of StringEnumeration.
  68      * Clones can be used concurrently in multiple threads.
  69      * If a subclass does not implement clone(), or if an error occurs,
  70      * then NULL is returned.
  71      * The clone functions in all subclasses return a base class pointer
  72      * because some compilers do not support covariant (same-as-this)
  73      * return types; cast to the appropriate subclass if necessary.
  74      * The caller must delete the clone.
  75      *
  76      * @return a clone of this object
  77      *
  78      * @see getDynamicClassID
  79      * @stable ICU 2.8
  80      */
  81     virtual StringEnumeration *clone() const;
  82
  83     /**
  84      * <p>Return the number of elements that the iterator traverses.  If
  85      * the iterator is out of sync with its service, status is set to
  86      * U_ENUM_OUT_OF_SYNC_ERROR, and the return value is zero.</p>
  87      *
  88      * <p>The return value will not change except possibly as a result of
  89      * a subsequent call to reset, or if the iterator becomes out of sync.</p>
  90      *
  91      * <p>This is a convenience function. It can end up being very
  92      * expensive as all the items might have to be pre-fetched
  93      * (depending on the storage format of the data being
  94      * traversed).</p>
  95      *
  96      * @param status the error code.
  97      * @return number of elements in the iterator.
  98      *
  99      * @stable ICU 2.4 */
 100     virtual int32_t count(UErrorCode& status) const = 0;
 101
 102     /**
 103      * <p>Returns the next element as a NUL-terminated char*.  If there
 104      * are no more elements, returns NULL.  If the resultLength pointer
 105      * is not NULL, the length of the string (not counting the
 106      * terminating NUL) is returned at that address.  If an error
 107      * status is returned, the value at resultLength is undefined.</p>
 108      *
 109      * <p>The returned pointer is owned by this iterator and must not be
 110      * deleted by the caller.  The pointer is valid until the next call
 111      * to next, unext, snext, reset, or the enumerator's destructor.</p>
 112      *
 113      * <p>If the iterator is out of sync with its service, status is set
 114      * to U_ENUM_OUT_OF_SYNC_ERROR and NULL is returned.</p>
 115      *
 116      * <p>If the native service string is a char16_t* string, it is
 117      * converted to char* with the invariant converter.  If the
 118      * conversion fails (because a character cannot be converted) then
 119      * status is set to U_INVARIANT_CONVERSION_ERROR and the return
 120      * value is undefined (though not NULL).</p>
 121      *
 122      * Starting with ICU 2.8, the default implementation calls snext()
 123      * and handles the conversion.
 124      * Either next() or snext() must be implemented differently by a subclass.
 125      *
 126      * @param status the error code.
 127      * @param resultLength a pointer to receive the length, can be NULL.
 128      * @return a pointer to the string, or NULL.
 129      *
 130      * @stable ICU 2.4
 131      */
 132     virtual const char* next(int32_t *resultLength, UErrorCode& status);
 133
 134     /**
 135      * <p>Returns the next element as a NUL-terminated char16_t*.  If there
 136      * are no more elements, returns NULL.  If the resultLength pointer
 137      * is not NULL, the length of the string (not counting the
 138      * terminating NUL) is returned at that address.  If an error
 139      * status is returned, the value at resultLength is undefined.</p>
 140      *
 141      * <p>The returned pointer is owned by this iterator and must not be
 142      * deleted by the caller.  The pointer is valid until the next call
 143      * to next, unext, snext, reset, or the enumerator's destructor.</p>
 144      *
 145      * <p>If the iterator is out of sync with its service, status is set
 146      * to U_ENUM_OUT_OF_SYNC_ERROR and NULL is returned.</p>
 147      *
 148      * Starting with ICU 2.8, the default implementation calls snext()
 149      * and handles the conversion.
 150      *
 151      * @param status the error code.
 152      * @param resultLength a ponter to receive the length, can be NULL.
 153      * @return a pointer to the string, or NULL.
 154      *
 155      * @stable ICU 2.4
 156      */
 157     virtual const char16_t* unext(int32_t *resultLength, UErrorCode& status);
 158
 159     /**
 160      * <p>Returns the next element a UnicodeString*.  If there are no
 161      * more elements, returns NULL.</p>
 162      *
 163      * <p>The returned pointer is owned by this iterator and must not be
 164      * deleted by the caller.  The pointer is valid until the next call
 165      * to next, unext, snext, reset, or the enumerator's destructor.</p>
 166      *
 167      * <p>If the iterator is out of sync with its service, status is set
 168      * to U_ENUM_OUT_OF_SYNC_ERROR and NULL is returned.</p>
 169      *
 170      * Starting with ICU 2.8, the default implementation calls next()
 171      * and handles the conversion.
 172      * Either next() or snext() must be implemented differently by a subclass.
 173      *
 174      * @param status the error code.
 175      * @return a pointer to the string, or NULL.
 176      *
 177      * @stable ICU 2.4
 178      */
 179     virtual const UnicodeString* snext(UErrorCode& status);
 180
 181     /**
 182      * <p>Resets the iterator.  This re-establishes sync with the
 183      * service and rewinds the iterator to start at the first
 184      * element.</p>
 185      *
 186      * <p>Previous pointers returned by next, unext, or snext become
 187      * invalid, and the value returned by count might change.</p>
 188      *
 189      * @param status the error code.
 190      *
 191      * @stable ICU 2.4
 192      */
 193     virtual void reset(UErrorCode& status) = 0;
 194
 195     /**
 196      * Compares this enumeration to other to check if both are equal
 197      *
 198      * @param that The other string enumeration to compare this object to
 199      * @return TRUE if the enumerations are equal. FALSE if not.
 200      * @stable ICU 3.6
 201      */
 202     virtual UBool operator==(const StringEnumeration& that)const;
 203     /**
 204      * Compares this enumeration to other to check if both are not equal
 205      *
 206      * @param that The other string enumeration to compare this object to
 207      * @return TRUE if the enumerations are equal. FALSE if not.
 208      * @stable ICU 3.6
 209      */
 210     virtual UBool operator!=(const StringEnumeration& that)const;
 211
 212 protected:
 213     /**
 214      * UnicodeString field for use with default implementations and subclasses.
 215      * @stable ICU 2.8
 216      */
 217     UnicodeString unistr;
 218     /**
 219      * char * default buffer for use with default implementations and subclasses.
 220      * @stable ICU 2.8
 221      */
 222     char charsBuffer[32];
 223     /**
 224      * char * buffer for use with default implementations and subclasses.
 225      * Allocated in constructor and in ensureCharsCapacity().
 226      * @stable ICU 2.8
 227      */
 228     char *chars;
 229     /**
 230      * Capacity of chars, for use with default implementations and subclasses.
 231      * @stable ICU 2.8
 232      */
 233     int32_t charsCapacity;
 234
 235     /**
 236      * Default constructor for use with default implementations and subclasses.
 237      * @stable ICU 2.8
 238      */
 239     StringEnumeration();
 240
 241     /**
 242      * Ensures that chars is at least as large as the requested capacity.
 243      * For use with default implementations and subclasses.
 244      *
 245      * @param capacity Requested capacity.
 246      * @param status ICU in/out error code.
 247      * @stable ICU 2.8
 248      */
 249     void ensureCharsCapacity(int32_t capacity, UErrorCode &status);
 250
 251     /**
 252      * Converts s to Unicode and sets unistr to the result.
 253      * For use with default implementations and subclasses,
 254      * especially for implementations of snext() in terms of next().
 255      * This is provided with a helper function instead of a default implementation
 256      * of snext() to avoid potential infinite loops between next() and snext().
 257      *
 258      * For example:
 259      * \code
 260      * const UnicodeString* snext(UErrorCode& status) {
 261      *   int32_t resultLength=0;
 262      *   const char *s=next(&resultLength, status);
 263      *   return setChars(s, resultLength, status);
 264      * }
 265      * \endcode
 266      *
 267      * @param s String to be converted to Unicode.
 268      * @param length Length of the string.
 269      * @param status ICU in/out error code.
 270      * @return A pointer to unistr.
 271      * @stable ICU 2.8
 272      */
 273     UnicodeString *setChars(const char *s, int32_t length, UErrorCode &status);
 274 };
 275
 276 U_NAMESPACE_END
 277 #endif // U_SHOW_CPLUSPLUS_API
 278
 279 /* STRENUM_H */
 280 #endif