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