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 | |
27 | U_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 | */ |
61 | class U_COMMON_API StringEnumeration : public UObject { |
62 | public: |
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 nullptr 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 nullptr. If the resultLength pointer |
105 | * is not nullptr, 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 nullptr 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 nullptr).</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 nullptr. |
128 | * @return a pointer to the string, or nullptr. |
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 nullptr. If the resultLength pointer |
137 | * is not nullptr, 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 nullptr 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 pointer to receive the length, can be nullptr. |
153 | * @return a pointer to the string, or nullptr. |
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 nullptr.</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 nullptr 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 nullptr. |
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 bool 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 bool operator!=(const StringEnumeration& that)const; |
211 | |
212 | protected: |
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 | |
276 | U_NAMESPACE_END |
277 | |
278 | #endif /* U_SHOW_CPLUSPLUS_API */ |
279 | |
280 | /* STRENUM_H */ |
281 | #endif |
282 | |