class StringEnumeration

Defined at line 61 of file ../../third_party/icu/default/source/common/unicode/strenum.h

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.

ICU 2.4

Protected Members

UnicodeString unistr

char[32] charsBuffer

char * chars

int32_t charsCapacity

Public Methods

void ~StringEnumeration ()

Destructor.

ICU 2.4

StringEnumeration * clone ()

Clone this object, an instance of a subclass of StringEnumeration.

Clones can be used concurrently in multiple threads.

If a subclass does not implement clone(), or if an error occurs,

then nullptr is returned.

The caller must delete the clone.

Returns

a clone of this object

int32_t count (UErrorCode & status)

Return the number of elements that the iterator traverses. If

the iterator is out of sync with its service, status is set to

U_ENUM_OUT_OF_SYNC_ERROR, and the return value is zero.

The return value will not change except possibly as a result of

a subsequent call to reset, or if the iterator becomes out of sync.

This is a convenience function. It can end up being very

expensive as all the items might have to be pre-fetched

(depending on the storage format of the data being

traversed).

ICU 2.4

Parameters

status the error code.

Returns

number of elements in the iterator.

const char * next (int32_t * resultLength, UErrorCode & status)

Returns the next element as a NUL-terminated char*. If there

are no more elements, returns nullptr. If the resultLength pointer

is not nullptr, 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 nullptr 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 nullptr).

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.

ICU 2.4

Parameters

status the error code.

resultLength a pointer to receive the length, can be nullptr.

Returns

a pointer to the string, or nullptr.

const char16_t * unext (int32_t * resultLength, UErrorCode & status)

Returns the next element as a NUL-terminated char16_t*. If there

are no more elements, returns nullptr. If the resultLength pointer

is not nullptr, 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 nullptr is returned.

Starting with ICU 2.8, the default implementation calls snext()

and handles the conversion.

ICU 2.4

Parameters

status the error code.

resultLength a pointer to receive the length, can be nullptr.

Returns

a pointer to the string, or nullptr.

const UnicodeString * snext (UErrorCode & status)

Returns the next element a UnicodeString*. If there are no

more elements, returns nullptr.

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 nullptr 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.

ICU 2.4

Parameters

status the error code.

Returns

a pointer to the string, or nullptr.

void reset (UErrorCode & status)

Resets the iterator. This re-establishes sync with the

service and rewinds the iterator to start at the first

element.

Previous pointers returned by next, unext, or snext become

invalid, and the value returned by count might change.

ICU 2.4

Parameters

status the error code.

bool operator== (const StringEnumeration & that)

Compares this enumeration to other to check if both are equal

Parameters

that The other string enumeration to compare this object to

Returns

true if the enumerations are equal. false if not.

ICU 3.6

bool operator!= (const StringEnumeration & that)

Compares this enumeration to other to check if both are not equal

Parameters

that The other string enumeration to compare this object to

Returns

true if the enumerations are equal. false if not.

ICU 3.6

Protected Methods

void StringEnumeration ()

Default constructor for use with default implementations and subclasses.

ICU 2.8

void ensureCharsCapacity (int32_t capacity, UErrorCode & status)

Ensures that chars is at least as large as the requested capacity.

For use with default implementations and subclasses.

Parameters

capacity Requested capacity.

status ICU in/out error code. ICU 2.8

UnicodeString * setChars (const char * s, int32_t length, UErrorCode & status)

Converts s to Unicode and sets unistr to the result.

For use with default implementations and subclasses,

especially for implementations of snext() in terms of next().

This is provided with a helper function instead of a default implementation

of snext() to avoid potential infinite loops between next() and snext().

For example:

Parameters

s String to be converted to Unicode.

length Length of the string.

status ICU in/out error code.

Returns

A pointer to unistr.

ICU 2.8

Code

                                            
                                                 const UnicodeString* snext(UErrorCode& status) {
                                                   int32_t resultLength=0;
                                                   const char *s=next(&resultLength, status);
                                                   return setChars(s, resultLength, status);
                                                 }