1 /* 2 ******************************************************************************* 3 * 4 * Copyright (C) 2002-2004, 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 22 /** 23 * An enumeration object. 24 * For usage in C programs. 25 * @stable ICU 2.2 26 */ 27 struct UEnumeration; 28 /** structure representing an enumeration object instance @stable ICU 2.2 */ 29 typedef struct UEnumeration UEnumeration; 30 31 /** 32 * Disposes of resources in use by the iterator. If en is NULL, 33 * does nothing. After this call, any char* or UChar* pointer 34 * returned by uenum_unext() or uenum_next() is invalid. 35 * @param en UEnumeration structure pointer 36 * @stable ICU 2.2 37 */ 38 U_STABLE void U_EXPORT2 39 uenum_close(UEnumeration* en); 40 41 /** 42 * Returns the number of elements that the iterator traverses. If 43 * the iterator is out-of-sync with its service, status is set to 44 * U_ENUM_OUT_OF_SYNC_ERROR. 45 * This is a convenience function. It can end up being very 46 * expensive as all the items might have to be pre-fetched (depending 47 * on the type of data being traversed). Use with caution and only 48 * when necessary. 49 * @param en UEnumeration structure pointer 50 * @param status error code, can be U_ENUM_OUT_OF_SYNC_ERROR if the 51 * iterator is out of sync. 52 * @return number of elements in the iterator 53 * @stable ICU 2.2 54 */ 55 U_STABLE int32_t U_EXPORT2 56 uenum_count(UEnumeration* en, UErrorCode* status); 57 58 /** 59 * Returns the next element in the iterator's list. If there are 60 * no more elements, returns NULL. If the iterator is out-of-sync 61 * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and 62 * NULL is returned. If the native service string is a char* string, 63 * it is converted to UChar* with the invariant converter. 64 * The result is terminated by (UChar)0. 65 * @param en the iterator object 66 * @param resultLength pointer to receive the length of the result 67 * (not including the terminating \\0). 68 * If the pointer is NULL it is ignored. 69 * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if 70 * the iterator is out of sync with its service. 71 * @return a pointer to the string. The string will be 72 * zero-terminated. The return pointer is owned by this iterator 73 * and must not be deleted by the caller. The pointer is valid 74 * until the next call to any uenum_... method, including 75 * uenum_next() or uenum_unext(). When all strings have been 76 * traversed, returns NULL. 77 * @stable ICU 2.2 78 */ 79 U_STABLE const UChar* U_EXPORT2 80 uenum_unext(UEnumeration* en, 81 int32_t* resultLength, 82 UErrorCode* status); 83 84 /** 85 * Returns the next element in the iterator's list. If there are 86 * no more elements, returns NULL. If the iterator is out-of-sync 87 * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and 88 * NULL is returned. If the native service string is a UChar* 89 * string, it is converted to char* with the invariant converter. 90 * The result is terminated by (char)0. If the conversion fails 91 * (because a character cannot be converted) then status is set to 92 * U_INVARIANT_CONVERSION_ERROR and the return value is undefined 93 * (but non-NULL). 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. Set to 100 * U_INVARIANT_CONVERSION_ERROR if the underlying native string is 101 * UChar* and conversion to char* with the invariant converter 102 * fails. This error pertains only to current string, so iteration 103 * might be able to continue successfully. 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 char* U_EXPORT2 113 uenum_next(UEnumeration* en, 114 int32_t* resultLength, 115 UErrorCode* status); 116 117 /** 118 * Resets the iterator to the current list of service IDs. This 119 * re-establishes sync with the service and rewinds the iterator 120 * to start at the first element. 121 * @param en the iterator object 122 * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if 123 * the iterator is out of sync with its service. 124 * @stable ICU 2.2 125 */ 126 U_STABLE void U_EXPORT2 127 uenum_reset(UEnumeration* en, UErrorCode* status); 128 129 #endif 130
