1 // Copyright (C) 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-2013, International Business Machines 7 * Corporation and others. All Rights Reserved. 8 * 9 ******************************************************************************* 10 * file name: uenum.h 11 * encoding: US-ASCII 12 * tab size: 8 (not used) 13 * indentation:2 14 * 15 * created on: 2002jul08 16 * created by: Vladimir Weinstein 17 */ 18 19 #ifndef __UENUM_H 20 #define __UENUM_H 21 22 #include "unicode/utypes.h" 23 #include "unicode/localpointer.h" 24 25 #if U_SHOW_CPLUSPLUS_API 26 #include "unicode/strenum.h" 27 #endif 28 29 /** 30 * \file 31 * \brief C API: String Enumeration 32 */ 33 34 /** 35 * An enumeration object. 36 * For usage in C programs. 37 * @stable ICU 2.2 38 */ 39 struct UEnumeration; 40 /** structure representing an enumeration object instance @stable ICU 2.2 */ 41 typedef struct UEnumeration UEnumeration; 42 43 /** 44 * Disposes of resources in use by the iterator. If en is NULL, 45 * does nothing. After this call, any char* or UChar* pointer 46 * returned by uenum_unext() or uenum_next() is invalid. 47 * @param en UEnumeration structure pointer 48 * @stable ICU 2.2 49 */ 50 U_STABLE void U_EXPORT2 51 uenum_close(UEnumeration* en); 52 53 #if U_SHOW_CPLUSPLUS_API 54 55 U_NAMESPACE_BEGIN 56 57 /** 58 * \class LocalUEnumerationPointer 59 * "Smart pointer" class, closes a UEnumeration via uenum_close(). 60 * For most methods see the LocalPointerBase base class. 61 * 62 * @see LocalPointerBase 63 * @see LocalPointer 64 * @stable ICU 4.4 65 */ 66 U_DEFINE_LOCAL_OPEN_POINTER(LocalUEnumerationPointer, UEnumeration, uenum_close); 67 68 U_NAMESPACE_END 69 70 #endif 71 72 /** 73 * Returns the number of elements that the iterator traverses. If 74 * the iterator is out-of-sync with its service, status is set to 75 * U_ENUM_OUT_OF_SYNC_ERROR. 76 * This is a convenience function. It can end up being very 77 * expensive as all the items might have to be pre-fetched (depending 78 * on the type of data being traversed). Use with caution and only 79 * when necessary. 80 * @param en UEnumeration structure pointer 81 * @param status error code, can be U_ENUM_OUT_OF_SYNC_ERROR if the 82 * iterator is out of sync. 83 * @return number of elements in the iterator 84 * @stable ICU 2.2 85 */ 86 U_STABLE int32_t U_EXPORT2 87 uenum_count(UEnumeration* en, UErrorCode* status); 88 89 /** 90 * Returns the next element in the iterator's list. If there are 91 * no more elements, returns NULL. If the iterator is out-of-sync 92 * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and 93 * NULL is returned. If the native service string is a char* string, 94 * it is converted to UChar* with the invariant converter. 95 * The result is terminated by (UChar)0. 96 * @param en the iterator object 97 * @param resultLength pointer to receive the length of the result 98 * (not including the terminating \\0). 99 * If the pointer is NULL it is ignored. 100 * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if 101 * the iterator is out of sync with its service. 102 * @return a pointer to the string. The string will be 103 * zero-terminated. The return pointer is owned by this iterator 104 * and must not be deleted by the caller. The pointer is valid 105 * until the next call to any uenum_... method, including 106 * uenum_next() or uenum_unext(). When all strings have been 107 * traversed, returns NULL. 108 * @stable ICU 2.2 109 */ 110 U_STABLE const UChar* U_EXPORT2 111 uenum_unext(UEnumeration* en, 112 int32_t* resultLength, 113 UErrorCode* status); 114 115 /** 116 * Returns the next element in the iterator's list. If there are 117 * no more elements, returns NULL. If the iterator is out-of-sync 118 * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and 119 * NULL is returned. If the native service string is a UChar* 120 * string, it is converted to char* with the invariant converter. 121 * The result is terminated by (char)0. If the conversion fails 122 * (because a character cannot be converted) then status is set to 123 * U_INVARIANT_CONVERSION_ERROR and the return value is undefined 124 * (but non-NULL). 125 * @param en the iterator object 126 * @param resultLength pointer to receive the length of the result 127 * (not including the terminating \\0). 128 * If the pointer is NULL it is ignored. 129 * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if 130 * the iterator is out of sync with its service. Set to 131 * U_INVARIANT_CONVERSION_ERROR if the underlying native string is 132 * UChar* and conversion to char* with the invariant converter 133 * fails. This error pertains only to current string, so iteration 134 * might be able to continue successfully. 135 * @return a pointer to the string. The string will be 136 * zero-terminated. The return pointer is owned by this iterator 137 * and must not be deleted by the caller. The pointer is valid 138 * until the next call to any uenum_... method, including 139 * uenum_next() or uenum_unext(). When all strings have been 140 * traversed, returns NULL. 141 * @stable ICU 2.2 142 */ 143 U_STABLE const char* U_EXPORT2 144 uenum_next(UEnumeration* en, 145 int32_t* resultLength, 146 UErrorCode* status); 147 148 /** 149 * Resets the iterator to the current list of service IDs. This 150 * re-establishes sync with the service and rewinds the iterator 151 * to start at the first element. 152 * @param en the iterator object 153 * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if 154 * the iterator is out of sync with its service. 155 * @stable ICU 2.2 156 */ 157 U_STABLE void U_EXPORT2 158 uenum_reset(UEnumeration* en, UErrorCode* status); 159 160 #if U_SHOW_CPLUSPLUS_API 161 162 /** 163 * Given a StringEnumeration, wrap it in a UEnumeration. The 164 * StringEnumeration is adopted; after this call, the caller must not 165 * delete it (regardless of error status). 166 * @param adopted the C++ StringEnumeration to be wrapped in a UEnumeration. 167 * @param ec the error code. 168 * @return a UEnumeration wrapping the adopted StringEnumeration. 169 * @stable ICU 4.2 170 */ 171 U_STABLE UEnumeration* U_EXPORT2 172 uenum_openFromStringEnumeration(icu::StringEnumeration* adopted, UErrorCode* ec); 173 174 #endif 175 176 /** 177 * Given an array of const UChar* strings, return a UEnumeration. String pointers from 0..count-1 must not be null. 178 * Do not free or modify either the string array or the characters it points to until this object has been destroyed with uenum_close. 179 * \snippet test/cintltst/uenumtst.c uenum_openUCharStringsEnumeration 180 * @param strings array of const UChar* strings (each null terminated). All storage is owned by the caller. 181 * @param count length of the array 182 * @param ec error code 183 * @return the new UEnumeration object. Caller is responsible for calling uenum_close to free memory. 184 * @see uenum_close 185 * @stable ICU 50 186 */ 187 U_STABLE UEnumeration* U_EXPORT2 188 uenum_openUCharStringsEnumeration(const UChar* const strings[], int32_t count, 189 UErrorCode* ec); 190 191 /* Note: next function is not hidden as draft, as it is used internally (it was formerly an internal function). */ 192 193 /** 194 * Given an array of const char* strings (invariant chars only), return a UEnumeration. String pointers from 0..count-1 must not be null. 195 * Do not free or modify either the string array or the characters it points to until this object has been destroyed with uenum_close. 196 * \snippet test/cintltst/uenumtst.c uenum_openCharStringsEnumeration 197 * @param strings array of char* strings (each null terminated). All storage is owned by the caller. 198 * @param count length of the array 199 * @param ec error code 200 * @return the new UEnumeration object. Caller is responsible for calling uenum_close to free memory 201 * @see uenum_close 202 * @stable ICU 50 203 */ 204 U_STABLE UEnumeration* U_EXPORT2 205 uenum_openCharStringsEnumeration(const char* const strings[], int32_t count, 206 UErrorCode* ec); 207 208 #endif 209