The Tor Browser / file comparison
comparison: intl/icu/source/common/unicode/uenum.h
intl/icu/source/common/unicode/uenum.h
- branch
- TOR_BUG_3246
- changeset 4
- fc2d59ddac77
equal
deleted
inserted
replaced
| -1:000000000000 | 0:a91d4aaff4f2 |
|---|---|
| 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 |
