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