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