Base class for 'pure' C++ implementations of uenum api.
Adds a method that returns the next UnicodeString since in C++ this can be a common storage format for strings.
The model is that the enumeration is over strings maintained by a 'service.' At any point, the service might change, invalidating the enumerator (though this is expected to be rare). The iterator returns an error if this has occurred. Lack of the error is no guarantee that the service didn't change immediately after the call, so the returned string still might not be 'valid' on subsequent use.
Strings may take the form of const char*, const char16_t*, or const UnicodeString*. The type you get is determine by the variant of 'next' that you call. In general the StringEnumeration is optimized for one of these types, but all StringEnumerations can return all types. Returned strings are each terminated with a NUL. Depending on the service data, they might also include embedded NUL characters, so API is provided to optionally return the true length, counting the embedded NULs but not counting the terminating NUL.
The pointers returned by next, unext, and snext become invalid upon any subsequent call to the enumeration's destructor, next, unext, snext, or reset.
ICU 2.8 adds some default implementations and helper functions for subclasses.
- Stable:
- ICU 2.4
Definition at line 61 of file strenum.h.
virtual const char * icu::StringEnumeration::next |
( |
int32_t * |
resultLength, |
|
|
UErrorCode & |
status |
|
) |
| |
|
virtual |
Returns the next element as a NUL-terminated char*. If there are no more elements, returns NULL. If the resultLength pointer is not NULL, the length of the string (not counting the terminating NUL) is returned at that address. If an error status is returned, the value at resultLength is undefined.
The returned pointer is owned by this iterator and must not be deleted by the caller. The pointer is valid until the next call to next, unext, snext, reset, or the enumerator's destructor.
If the iterator is out of sync with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and NULL is returned.
If the native service string is a char16_t* string, it is converted to char* with the invariant converter. If the conversion fails (because a character cannot be converted) then status is set to U_INVARIANT_CONVERSION_ERROR and the return value is undefined (though not NULL).
Starting with ICU 2.8, the default implementation calls snext() and handles the conversion. Either next() or snext() must be implemented differently by a subclass.
- Parameters
-
status | the error code. |
resultLength | a pointer to receive the length, can be NULL. |
- Returns
- a pointer to the string, or NULL.
- Stable:
- ICU 2.4
Returns the next element a UnicodeString*. If there are no more elements, returns NULL.
The returned pointer is owned by this iterator and must not be deleted by the caller. The pointer is valid until the next call to next, unext, snext, reset, or the enumerator's destructor.
If the iterator is out of sync with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and NULL is returned.
Starting with ICU 2.8, the default implementation calls next() and handles the conversion. Either next() or snext() must be implemented differently by a subclass.
- Parameters
-
- Returns
- a pointer to the string, or NULL.
- Stable:
- ICU 2.4
virtual const char16_t * icu::StringEnumeration::unext |
( |
int32_t * |
resultLength, |
|
|
UErrorCode & |
status |
|
) |
| |
|
virtual |
Returns the next element as a NUL-terminated char16_t*. If there are no more elements, returns NULL. If the resultLength pointer is not NULL, the length of the string (not counting the terminating NUL) is returned at that address. If an error status is returned, the value at resultLength is undefined.
The returned pointer is owned by this iterator and must not be deleted by the caller. The pointer is valid until the next call to next, unext, snext, reset, or the enumerator's destructor.
If the iterator is out of sync with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and NULL is returned.
Starting with ICU 2.8, the default implementation calls snext() and handles the conversion.
- Parameters
-
status | the error code. |
resultLength | a pointer to receive the length, can be NULL. |
- Returns
- a pointer to the string, or NULL.
- Stable:
- ICU 2.4