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