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