| /* |
| ******************************************************************************* |
| * |
| * Copyright (C) 2002-2013, International Business Machines |
| * Corporation and others. All Rights Reserved. |
| * |
| ******************************************************************************* |
| * file name: uenum.h |
| * encoding: US-ASCII |
| * tab size: 8 (not used) |
| * indentation:2 |
| * |
| * created on: 2002jul08 |
| * created by: Vladimir Weinstein |
| */ |
| |
| #ifndef __UENUM_H |
| #define __UENUM_H |
| |
| #include "unicode/utypes.h" |
| #include "unicode/localpointer.h" |
| |
| #if U_SHOW_CPLUSPLUS_API |
| #include "unicode/strenum.h" |
| #endif |
| |
| /** |
| * \file |
| * \brief C API: String Enumeration |
| */ |
| |
| /** |
| * An enumeration object. |
| * For usage in C programs. |
| * @stable ICU 2.2 |
| */ |
| struct UEnumeration; |
| /** structure representing an enumeration object instance @stable ICU 2.2 */ |
| typedef struct UEnumeration UEnumeration; |
| |
| /** |
| * Disposes of resources in use by the iterator. If en is NULL, |
| * does nothing. After this call, any char* or UChar* pointer |
| * returned by uenum_unext() or uenum_next() is invalid. |
| * @param en UEnumeration structure pointer |
| * @stable ICU 2.2 |
| */ |
| U_STABLE void U_EXPORT2 |
| uenum_close(UEnumeration* en); |
| |
| #if U_SHOW_CPLUSPLUS_API |
| |
| U_NAMESPACE_BEGIN |
| |
| /** |
| * \class LocalUEnumerationPointer |
| * "Smart pointer" class, closes a UEnumeration via uenum_close(). |
| * For most methods see the LocalPointerBase base class. |
| * |
| * @see LocalPointerBase |
| * @see LocalPointer |
| * @stable ICU 4.4 |
| */ |
| U_DEFINE_LOCAL_OPEN_POINTER(LocalUEnumerationPointer, UEnumeration, uenum_close); |
| |
| U_NAMESPACE_END |
| |
| #endif |
| |
| /** |
| * Returns 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. |
| * 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 type of data being traversed). Use with caution and only |
| * when necessary. |
| * @param en UEnumeration structure pointer |
| * @param status error code, can be U_ENUM_OUT_OF_SYNC_ERROR if the |
| * iterator is out of sync. |
| * @return number of elements in the iterator |
| * @stable ICU 2.2 |
| */ |
| U_STABLE int32_t U_EXPORT2 |
| uenum_count(UEnumeration* en, UErrorCode* status); |
| |
| /** |
| * Returns the next element in the iterator's list. If there are |
| * no more elements, returns NULL. 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 char* string, |
| * it is converted to UChar* with the invariant converter. |
| * The result is terminated by (UChar)0. |
| * @param en the iterator object |
| * @param resultLength pointer to receive the length of the result |
| * (not including the terminating \\0). |
| * If the pointer is NULL it is ignored. |
| * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if |
| * the iterator is out of sync with its service. |
| * @return a pointer to the string. The string will be |
| * zero-terminated. The return pointer is owned by this iterator |
| * and must not be deleted by the caller. The pointer is valid |
| * until the next call to any uenum_... method, including |
| * uenum_next() or uenum_unext(). When all strings have been |
| * traversed, returns NULL. |
| * @stable ICU 2.2 |
| */ |
| U_STABLE const UChar* U_EXPORT2 |
| uenum_unext(UEnumeration* en, |
| int32_t* resultLength, |
| UErrorCode* status); |
| |
| /** |
| * Returns the next element in the iterator's list. If there are |
| * no more elements, returns NULL. 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 UChar* |
| * string, it is converted to char* with the invariant converter. |
| * The result is terminated by (char)0. 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 |
| * (but non-NULL). |
| * @param en the iterator object |
| * @param resultLength pointer to receive the length of the result |
| * (not including the terminating \\0). |
| * If the pointer is NULL it is ignored. |
| * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if |
| * the iterator is out of sync with its service. Set to |
| * U_INVARIANT_CONVERSION_ERROR if the underlying native string is |
| * UChar* and conversion to char* with the invariant converter |
| * fails. This error pertains only to current string, so iteration |
| * might be able to continue successfully. |
| * @return a pointer to the string. The string will be |
| * zero-terminated. The return pointer is owned by this iterator |
| * and must not be deleted by the caller. The pointer is valid |
| * until the next call to any uenum_... method, including |
| * uenum_next() or uenum_unext(). When all strings have been |
| * traversed, returns NULL. |
| * @stable ICU 2.2 |
| */ |
| U_STABLE const char* U_EXPORT2 |
| uenum_next(UEnumeration* en, |
| int32_t* resultLength, |
| UErrorCode* status); |
| |
| /** |
| * Resets the iterator to the current list of service IDs. This |
| * re-establishes sync with the service and rewinds the iterator |
| * to start at the first element. |
| * @param en the iterator object |
| * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if |
| * the iterator is out of sync with its service. |
| * @stable ICU 2.2 |
| */ |
| U_STABLE void U_EXPORT2 |
| uenum_reset(UEnumeration* en, UErrorCode* status); |
| |
| #if U_SHOW_CPLUSPLUS_API |
| |
| /** |
| * Given a StringEnumeration, wrap it in a UEnumeration. The |
| * StringEnumeration is adopted; after this call, the caller must not |
| * delete it (regardless of error status). |
| * @param adopted the C++ StringEnumeration to be wrapped in a UEnumeration. |
| * @param ec the error code. |
| * @return a UEnumeration wrapping the adopted StringEnumeration. |
| * @stable ICU 4.2 |
| */ |
| U_STABLE UEnumeration* U_EXPORT2 |
| uenum_openFromStringEnumeration(icu::StringEnumeration* adopted, UErrorCode* ec); |
| |
| #endif |
| |
| /** |
| * Given an array of const UChar* strings, return a UEnumeration. String pointers from 0..count-1 must not be null. |
| * Do not free or modify either the string array or the characters it points to until this object has been destroyed with uenum_close. |
| * \snippet test/cintltst/uenumtst.c uenum_openUCharStringsEnumeration |
| * @param strings array of const UChar* strings (each null terminated). All storage is owned by the caller. |
| * @param count length of the array |
| * @param ec error code |
| * @return the new UEnumeration object. Caller is responsible for calling uenum_close to free memory. |
| * @see uenum_close |
| * @stable ICU 50 |
| */ |
| U_STABLE UEnumeration* U_EXPORT2 |
| uenum_openUCharStringsEnumeration(const UChar* const strings[], int32_t count, |
| UErrorCode* ec); |
| |
| /* Note: next function is not hidden as draft, as it is used internally (it was formerly an internal function). */ |
| |
| /** |
| * Given an array of const char* strings (invariant chars only), return a UEnumeration. String pointers from 0..count-1 must not be null. |
| * Do not free or modify either the string array or the characters it points to until this object has been destroyed with uenum_close. |
| * \snippet test/cintltst/uenumtst.c uenum_openCharStringsEnumeration |
| * @param strings array of char* strings (each null terminated). All storage is owned by the caller. |
| * @param count length of the array |
| * @param ec error code |
| * @return the new UEnumeration object. Caller is responsible for calling uenum_close to free memory |
| * @see uenum_close |
| * @stable ICU 50 |
| */ |
| U_STABLE UEnumeration* U_EXPORT2 |
| uenum_openCharStringsEnumeration(const char* const strings[], int32_t count, |
| UErrorCode* ec); |
| |
| #endif |
