1b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/* 2b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru******************************************************************************* 3b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru* 427f654740f2a26ad62a5c155af9199af9e69b889claireho* Copyright (C) 2002-2010, International Business Machines 5b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru* Corporation and others. All Rights Reserved. 6b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru* 7b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru******************************************************************************* 8b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru* file name: uenum.h 9b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru* encoding: US-ASCII 10b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru* tab size: 8 (not used) 11b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru* indentation:2 12b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru* 13b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru* created on: 2002jul08 14b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru* created by: Vladimir Weinstein 15b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru*/ 16b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 17b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#ifndef __UENUM_H 18b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#define __UENUM_H 19b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 20b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#include "unicode/utypes.h" 2150294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho#include "unicode/localpointer.h" 22b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 2350294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho#if U_SHOW_CPLUSPLUS_API 24b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru#include "unicode/strenum.h" 25b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru#endif 26b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru 27b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 28b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * \file 29b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * \brief C API: String Enumeration 30b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 31b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 32b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 33b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * An enumeration object. 34b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * For usage in C programs. 35b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.2 36b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 37b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Querustruct UEnumeration; 38b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** structure representing an enumeration object instance @stable ICU 2.2 */ 39b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Querutypedef struct UEnumeration UEnumeration; 40b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 41b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 42b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Disposes of resources in use by the iterator. If en is NULL, 43b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * does nothing. After this call, any char* or UChar* pointer 44b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * returned by uenum_unext() or uenum_next() is invalid. 45b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param en UEnumeration structure pointer 46b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.2 47b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 48b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 49b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruuenum_close(UEnumeration* en); 50b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 5150294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho#if U_SHOW_CPLUSPLUS_API 5250294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho 5350294ead5e5d23f5bbfed76e00e6b510bd41eee1clairehoU_NAMESPACE_BEGIN 5450294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho 5550294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho/** 5650294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho * \class LocalUEnumerationPointer 5750294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho * "Smart pointer" class, closes a UEnumeration via uenum_close(). 5850294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho * For most methods see the LocalPointerBase base class. 5950294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho * 6050294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho * @see LocalPointerBase 6150294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho * @see LocalPointer 6227f654740f2a26ad62a5c155af9199af9e69b889claireho * @stable ICU 4.4 6350294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho */ 6450294ead5e5d23f5bbfed76e00e6b510bd41eee1clairehoU_DEFINE_LOCAL_OPEN_POINTER(LocalUEnumerationPointer, UEnumeration, uenum_close); 6550294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho 6650294ead5e5d23f5bbfed76e00e6b510bd41eee1clairehoU_NAMESPACE_END 6750294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho 6850294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho#endif 6950294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho 70b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 71b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Returns the number of elements that the iterator traverses. If 72b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * the iterator is out-of-sync with its service, status is set to 73b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * U_ENUM_OUT_OF_SYNC_ERROR. 74b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This is a convenience function. It can end up being very 75b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * expensive as all the items might have to be pre-fetched (depending 76b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * on the type of data being traversed). Use with caution and only 77b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * when necessary. 78b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param en UEnumeration structure pointer 79b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param status error code, can be U_ENUM_OUT_OF_SYNC_ERROR if the 80b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * iterator is out of sync. 81b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return number of elements in the iterator 82b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.2 83b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 84b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE int32_t U_EXPORT2 85b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruuenum_count(UEnumeration* en, UErrorCode* status); 86b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 87b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 88b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Returns the next element in the iterator's list. If there are 89b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * no more elements, returns NULL. If the iterator is out-of-sync 90b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and 91b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * NULL is returned. If the native service string is a char* string, 92b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * it is converted to UChar* with the invariant converter. 93b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The result is terminated by (UChar)0. 94b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param en the iterator object 95b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param resultLength pointer to receive the length of the result 96b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (not including the terminating \\0). 97b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * If the pointer is NULL it is ignored. 98b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if 99b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * the iterator is out of sync with its service. 100b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return a pointer to the string. The string will be 101b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * zero-terminated. The return pointer is owned by this iterator 102b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and must not be deleted by the caller. The pointer is valid 103b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * until the next call to any uenum_... method, including 104b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * uenum_next() or uenum_unext(). When all strings have been 105b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * traversed, returns NULL. 106b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.2 107b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 108b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE const UChar* U_EXPORT2 109b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruuenum_unext(UEnumeration* en, 110b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru int32_t* resultLength, 111b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode* status); 112b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 113b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 114b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Returns the next element in the iterator's list. If there are 115b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * no more elements, returns NULL. If the iterator is out-of-sync 116b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and 117b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * NULL is returned. If the native service string is a UChar* 118b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * string, it is converted to char* with the invariant converter. 119b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The result is terminated by (char)0. If the conversion fails 120b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (because a character cannot be converted) then status is set to 121b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * U_INVARIANT_CONVERSION_ERROR and the return value is undefined 122b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (but non-NULL). 123b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param en the iterator object 124b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param resultLength pointer to receive the length of the result 125b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (not including the terminating \\0). 126b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * If the pointer is NULL it is ignored. 127b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if 128b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * the iterator is out of sync with its service. Set to 129b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * U_INVARIANT_CONVERSION_ERROR if the underlying native string is 130b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * UChar* and conversion to char* with the invariant converter 131b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * fails. This error pertains only to current string, so iteration 132b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * might be able to continue successfully. 133b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return a pointer to the string. The string will be 134b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * zero-terminated. The return pointer is owned by this iterator 135b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and must not be deleted by the caller. The pointer is valid 136b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * until the next call to any uenum_... method, including 137b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * uenum_next() or uenum_unext(). When all strings have been 138b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * traversed, returns NULL. 139b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.2 140b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 141b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE const char* U_EXPORT2 142b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruuenum_next(UEnumeration* en, 143b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru int32_t* resultLength, 144b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode* status); 145b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 146b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 147b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Resets the iterator to the current list of service IDs. This 148b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * re-establishes sync with the service and rewinds the iterator 149b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * to start at the first element. 150b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param en the iterator object 151b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if 152b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * the iterator is out of sync with its service. 153b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.2 154b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 155b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 156b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruuenum_reset(UEnumeration* en, UErrorCode* status); 157b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 15850294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho#if U_SHOW_CPLUSPLUS_API 159b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru 160b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru/** 161b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru * Given a StringEnumeration, wrap it in a UEnumeration. The 162b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru * StringEnumeration is adopted; after this call, the caller must not 163b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru * delete it (regardless of error status). 164b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru * @param adopted the C++ StringEnumeration to be wrapped in a UEnumeration. 165b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru * @param ec the error code. 166b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru * @return a UEnumeration wrapping the adopted StringEnumeration. 167b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru * @draft ICU 4.2 168b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru */ 169b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste QueruU_CAPI UEnumeration* U_EXPORT2 170b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queruuenum_openFromStringEnumeration(U_NAMESPACE_QUALIFIER StringEnumeration* adopted, UErrorCode* ec); 171b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru 172b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru#endif 173b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru 174b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#endif 175