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-2012, International Business Machines |
7 | * Corporation and others. All Rights Reserved. |
8 | * |
9 | ******************************************************************************* |
10 | */ |
11 | |
12 | #ifndef STRENUM_H |
13 | #define STRENUM_H |
14 | |
15 | #include "unicode/uobject.h" |
16 | #include "unicode/unistr.h" |
17 | |
18 | /** |
19 | * \file |
20 | * \brief C++ API: String Enumeration |
21 | */ |
22 | |
23 | U_NAMESPACE_BEGIN |
24 | |
25 | /** |
26 | * Base class for 'pure' C++ implementations of uenum api. Adds a |
27 | * method that returns the next UnicodeString since in C++ this can |
28 | * be a common storage format for strings. |
29 | * |
30 | * <p>The model is that the enumeration is over strings maintained by |
31 | * a 'service.' At any point, the service might change, invalidating |
32 | * the enumerator (though this is expected to be rare). The iterator |
33 | * returns an error if this has occurred. Lack of the error is no |
34 | * guarantee that the service didn't change immediately after the |
35 | * call, so the returned string still might not be 'valid' on |
36 | * subsequent use.</p> |
37 | * |
38 | * <p>Strings may take the form of const char*, const char16_t*, or const |
39 | * UnicodeString*. The type you get is determine by the variant of |
40 | * 'next' that you call. In general the StringEnumeration is |
41 | * optimized for one of these types, but all StringEnumerations can |
42 | * return all types. Returned strings are each terminated with a NUL. |
43 | * Depending on the service data, they might also include embedded NUL |
44 | * characters, so API is provided to optionally return the true |
45 | * length, counting the embedded NULs but not counting the terminating |
46 | * NUL.</p> |
47 | * |
48 | * <p>The pointers returned by next, unext, and snext become invalid |
49 | * upon any subsequent call to the enumeration's destructor, next, |
50 | * unext, snext, or reset.</p> |
51 | * |
52 | * ICU 2.8 adds some default implementations and helper functions |
53 | * for subclasses. |
54 | * |
55 | * @stable ICU 2.4 |
56 | */ |
57 | class U_COMMON_API StringEnumeration : public UObject { |
58 | public: |
59 | /** |
60 | * Destructor. |
61 | * @stable ICU 2.4 |
62 | */ |
63 | virtual ~StringEnumeration(); |
64 | |
65 | /** |
66 | * Clone this object, an instance of a subclass of StringEnumeration. |
67 | * Clones can be used concurrently in multiple threads. |
68 | * If a subclass does not implement clone(), or if an error occurs, |
69 | * then NULL is returned. |
70 | * The clone functions in all subclasses return a base class pointer |
71 | * because some compilers do not support covariant (same-as-this) |
72 | * return types; cast to the appropriate subclass if necessary. |
73 | * The caller must delete the clone. |
74 | * |
75 | * @return a clone of this object |
76 | * |
77 | * @see getDynamicClassID |
78 | * @stable ICU 2.8 |
79 | */ |
80 | virtual StringEnumeration *clone() const; |
81 | |
82 | /** |
83 | * <p>Return the number of elements that the iterator traverses. If |
84 | * the iterator is out of sync with its service, status is set to |
85 | * U_ENUM_OUT_OF_SYNC_ERROR, and the return value is zero.</p> |
86 | * |
87 | * <p>The return value will not change except possibly as a result of |
88 | * a subsequent call to reset, or if the iterator becomes out of sync.</p> |
89 | * |
90 | * <p>This is a convenience function. It can end up being very |
91 | * expensive as all the items might have to be pre-fetched |
92 | * (depending on the storage format of the data being |
93 | * traversed).</p> |
94 | * |
95 | * @param status the error code. |
96 | * @return number of elements in the iterator. |
97 | * |
98 | * @stable ICU 2.4 */ |
99 | virtual int32_t count(UErrorCode& status) const = 0; |
100 | |
101 | /** |
102 | * <p>Returns the next element as a NUL-terminated char*. If there |
103 | * are no more elements, returns NULL. If the resultLength pointer |
104 | * is not NULL, the length of the string (not counting the |
105 | * terminating NUL) is returned at that address. If an error |
106 | * status is returned, the value at resultLength is undefined.</p> |
107 | * |
108 | * <p>The returned pointer is owned by this iterator and must not be |
109 | * deleted by the caller. The pointer is valid until the next call |
110 | * to next, unext, snext, reset, or the enumerator's destructor.</p> |
111 | * |
112 | * <p>If the iterator is out of sync with its service, status is set |
113 | * to U_ENUM_OUT_OF_SYNC_ERROR and NULL is returned.</p> |
114 | * |
115 | * <p>If the native service string is a char16_t* string, it is |
116 | * converted to char* with the invariant converter. If the |
117 | * conversion fails (because a character cannot be converted) then |
118 | * status is set to U_INVARIANT_CONVERSION_ERROR and the return |
119 | * value is undefined (though not NULL).</p> |
120 | * |
121 | * Starting with ICU 2.8, the default implementation calls snext() |
122 | * and handles the conversion. |
123 | * Either next() or snext() must be implemented differently by a subclass. |
124 | * |
125 | * @param status the error code. |
126 | * @param resultLength a pointer to receive the length, can be NULL. |
127 | * @return a pointer to the string, or NULL. |
128 | * |
129 | * @stable ICU 2.4 |
130 | */ |
131 | virtual const char* next(int32_t *resultLength, UErrorCode& status); |
132 | |
133 | /** |
134 | * <p>Returns the next element as a NUL-terminated char16_t*. If there |
135 | * are no more elements, returns NULL. If the resultLength pointer |
136 | * is not NULL, the length of the string (not counting the |
137 | * terminating NUL) is returned at that address. If an error |
138 | * status is returned, the value at resultLength is undefined.</p> |
139 | * |
140 | * <p>The returned pointer is owned by this iterator and must not be |
141 | * deleted by the caller. The pointer is valid until the next call |
142 | * to next, unext, snext, reset, or the enumerator's destructor.</p> |
143 | * |
144 | * <p>If the iterator is out of sync with its service, status is set |
145 | * to U_ENUM_OUT_OF_SYNC_ERROR and NULL is returned.</p> |
146 | * |
147 | * Starting with ICU 2.8, the default implementation calls snext() |
148 | * and handles the conversion. |
149 | * |
150 | * @param status the error code. |
151 | * @param resultLength a ponter to receive the length, can be NULL. |
152 | * @return a pointer to the string, or NULL. |
153 | * |
154 | * @stable ICU 2.4 |
155 | */ |
156 | virtual const char16_t* unext(int32_t *resultLength, UErrorCode& status); |
157 | |
158 | /** |
159 | * <p>Returns the next element a UnicodeString*. If there are no |
160 | * more elements, returns NULL.</p> |
161 | * |
162 | * <p>The returned pointer is owned by this iterator and must not be |
163 | * deleted by the caller. The pointer is valid until the next call |
164 | * to next, unext, snext, reset, or the enumerator's destructor.</p> |
165 | * |
166 | * <p>If the iterator is out of sync with its service, status is set |
167 | * to U_ENUM_OUT_OF_SYNC_ERROR and NULL is returned.</p> |
168 | * |
169 | * Starting with ICU 2.8, the default implementation calls next() |
170 | * and handles the conversion. |
171 | * Either next() or snext() must be implemented differently by a subclass. |
172 | * |
173 | * @param status the error code. |
174 | * @return a pointer to the string, or NULL. |
175 | * |
176 | * @stable ICU 2.4 |
177 | */ |
178 | virtual const UnicodeString* snext(UErrorCode& status); |
179 | |
180 | /** |
181 | * <p>Resets the iterator. This re-establishes sync with the |
182 | * service and rewinds the iterator to start at the first |
183 | * element.</p> |
184 | * |
185 | * <p>Previous pointers returned by next, unext, or snext become |
186 | * invalid, and the value returned by count might change.</p> |
187 | * |
188 | * @param status the error code. |
189 | * |
190 | * @stable ICU 2.4 |
191 | */ |
192 | virtual void reset(UErrorCode& status) = 0; |
193 | |
194 | /** |
195 | * Compares this enumeration to other to check if both are equal |
196 | * |
197 | * @param that The other string enumeration to compare this object to |
198 | * @return TRUE if the enumerations are equal. FALSE if not. |
199 | * @stable ICU 3.6 |
200 | */ |
201 | virtual UBool operator==(const StringEnumeration& that)const; |
202 | /** |
203 | * Compares this enumeration to other to check if both are not equal |
204 | * |
205 | * @param that The other string enumeration to compare this object to |
206 | * @return TRUE if the enumerations are equal. FALSE if not. |
207 | * @stable ICU 3.6 |
208 | */ |
209 | virtual UBool operator!=(const StringEnumeration& that)const; |
210 | |
211 | protected: |
212 | /** |
213 | * UnicodeString field for use with default implementations and subclasses. |
214 | * @stable ICU 2.8 |
215 | */ |
216 | UnicodeString unistr; |
217 | /** |
218 | * char * default buffer for use with default implementations and subclasses. |
219 | * @stable ICU 2.8 |
220 | */ |
221 | char charsBuffer[32]; |
222 | /** |
223 | * char * buffer for use with default implementations and subclasses. |
224 | * Allocated in constructor and in ensureCharsCapacity(). |
225 | * @stable ICU 2.8 |
226 | */ |
227 | char *chars; |
228 | /** |
229 | * Capacity of chars, for use with default implementations and subclasses. |
230 | * @stable ICU 2.8 |
231 | */ |
232 | int32_t charsCapacity; |
233 | |
234 | /** |
235 | * Default constructor for use with default implementations and subclasses. |
236 | * @stable ICU 2.8 |
237 | */ |
238 | StringEnumeration(); |
239 | |
240 | /** |
241 | * Ensures that chars is at least as large as the requested capacity. |
242 | * For use with default implementations and subclasses. |
243 | * |
244 | * @param capacity Requested capacity. |
245 | * @param status ICU in/out error code. |
246 | * @stable ICU 2.8 |
247 | */ |
248 | void ensureCharsCapacity(int32_t capacity, UErrorCode &status); |
249 | |
250 | /** |
251 | * Converts s to Unicode and sets unistr to the result. |
252 | * For use with default implementations and subclasses, |
253 | * especially for implementations of snext() in terms of next(). |
254 | * This is provided with a helper function instead of a default implementation |
255 | * of snext() to avoid potential infinite loops between next() and snext(). |
256 | * |
257 | * For example: |
258 | * \code |
259 | * const UnicodeString* snext(UErrorCode& status) { |
260 | * int32_t resultLength=0; |
261 | * const char *s=next(&resultLength, status); |
262 | * return setChars(s, resultLength, status); |
263 | * } |
264 | * \endcode |
265 | * |
266 | * @param s String to be converted to Unicode. |
267 | * @param length Length of the string. |
268 | * @param status ICU in/out error code. |
269 | * @return A pointer to unistr. |
270 | * @stable ICU 2.8 |
271 | */ |
272 | UnicodeString *setChars(const char *s, int32_t length, UErrorCode &status); |
273 | }; |
274 | |
275 | U_NAMESPACE_END |
276 | |
277 | /* STRENUM_H */ |
278 | #endif |
279 | |