1/* 2******************************************************************************* 3* 4* Copyright (C) 2002-2010, 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 */ 37struct UEnumeration; 38/** structure representing an enumeration object instance @stable ICU 2.2 */ 39typedef 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 */ 48U_STABLE void U_EXPORT2 49uenum_close(UEnumeration* en); 50 51#if U_SHOW_CPLUSPLUS_API 52 53U_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 */ 64U_DEFINE_LOCAL_OPEN_POINTER(LocalUEnumerationPointer, UEnumeration, uenum_close); 65 66U_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 */ 84U_STABLE int32_t U_EXPORT2 85uenum_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 */ 108U_STABLE const UChar* U_EXPORT2 109uenum_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 */ 141U_STABLE const char* U_EXPORT2 142uenum_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 */ 155U_STABLE void U_EXPORT2 156uenum_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 * @draft ICU 4.2 168 */ 169U_CAPI UEnumeration* U_EXPORT2 170uenum_openFromStringEnumeration(U_NAMESPACE_QUALIFIER StringEnumeration* adopted, UErrorCode* ec); 171 172#endif 173 174#endif 175