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