intl/icu/source/common/unicode/uenum.h@6474c204b198
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.
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 */
17 #ifndef __UENUM_H
18 #define __UENUM_H
20 #include "unicode/utypes.h"
21 #include "unicode/localpointer.h"
23 #if U_SHOW_CPLUSPLUS_API
24 #include "unicode/strenum.h"
25 #endif
27 /**
28 * \file
29 * \brief C API: String Enumeration
30 */
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;
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);
51 #if U_SHOW_CPLUSPLUS_API
53 U_NAMESPACE_BEGIN
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);
66 U_NAMESPACE_END
68 #endif
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);
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);
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);
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);
158 #if U_SHOW_CPLUSPLUS_API
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);
172 #endif
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);
189 /* Note: next function is not hidden as draft, as it is used internally (it was formerly an internal function). */
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);
206 #endif
