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