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