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