Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/strenum.h @ 69:33d812a61356

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