sl@0: /*
sl@0: *******************************************************************************
sl@0: *
sl@0: *   Copyright (C) 2002-2005, International Business Machines
sl@0: *   Corporation and others.  All Rights Reserved.
sl@0: *
sl@0: *******************************************************************************
sl@0: *   file name:  uenum.h
sl@0: *   encoding:   US-ASCII
sl@0: *   tab size:   8 (not used)
sl@0: *   indentation:2
sl@0: *
sl@0: *   created on: 2002jul08
sl@0: *   created by: Vladimir Weinstein
sl@0: */
sl@0: 
sl@0: #ifndef __UENUM_H
sl@0: #define __UENUM_H
sl@0: 
sl@0: #include "unicode/utypes.h"
sl@0: 
sl@0: /**
sl@0:  * \file
sl@0:  * \brief C API: String Enumeration 
sl@0:  */
sl@0:  
sl@0: /**
sl@0:  * An enumeration object.
sl@0:  * For usage in C programs.
sl@0:  * @stable ICU 2.2
sl@0:  */
sl@0: struct UEnumeration;
sl@0: /** structure representing an enumeration object instance @stable ICU 2.2 */
sl@0: typedef struct UEnumeration UEnumeration;
sl@0: 
sl@0: /**
sl@0:  * Disposes of resources in use by the iterator.  If en is NULL,
sl@0:  * does nothing.  After this call, any char* or UChar* pointer
sl@0:  * returned by uenum_unext() or uenum_next() is invalid.
sl@0:  * @param en UEnumeration structure pointer
sl@0:  * @stable ICU 2.2
sl@0:  */
sl@0: U_STABLE void U_EXPORT2
sl@0: uenum_close(UEnumeration* en);
sl@0: 
sl@0: /**
sl@0:  * Returns the number of elements that the iterator traverses.  If
sl@0:  * the iterator is out-of-sync with its service, status is set to
sl@0:  * U_ENUM_OUT_OF_SYNC_ERROR.
sl@0:  * This is a convenience function. It can end up being very
sl@0:  * expensive as all the items might have to be pre-fetched (depending
sl@0:  * on the type of data being traversed). Use with caution and only 
sl@0:  * when necessary.
sl@0:  * @param en UEnumeration structure pointer
sl@0:  * @param status error code, can be U_ENUM_OUT_OF_SYNC_ERROR if the
sl@0:  *               iterator is out of sync.
sl@0:  * @return number of elements in the iterator
sl@0:  * @stable ICU 2.2
sl@0:  */
sl@0: U_STABLE int32_t U_EXPORT2
sl@0: uenum_count(UEnumeration* en, UErrorCode* status);
sl@0: 
sl@0: /**
sl@0:  * Returns the next element in the iterator's list.  If there are
sl@0:  * no more elements, returns NULL.  If the iterator is out-of-sync
sl@0:  * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and
sl@0:  * NULL is returned.  If the native service string is a char* string,
sl@0:  * it is converted to UChar* with the invariant converter.
sl@0:  * The result is terminated by (UChar)0.
sl@0:  * @param en the iterator object
sl@0:  * @param resultLength pointer to receive the length of the result
sl@0:  *                     (not including the terminating \\0).
sl@0:  *                     If the pointer is NULL it is ignored.
sl@0:  * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
sl@0:  *               the iterator is out of sync with its service.
sl@0:  * @return a pointer to the string.  The string will be
sl@0:  *         zero-terminated.  The return pointer is owned by this iterator
sl@0:  *         and must not be deleted by the caller.  The pointer is valid
sl@0:  *         until the next call to any uenum_... method, including
sl@0:  *         uenum_next() or uenum_unext().  When all strings have been
sl@0:  *         traversed, returns NULL.
sl@0:  * @stable ICU 2.2
sl@0:  */
sl@0: U_STABLE const UChar* U_EXPORT2
sl@0: uenum_unext(UEnumeration* en,
sl@0:             int32_t* resultLength,
sl@0:             UErrorCode* status);
sl@0: 
sl@0: /**
sl@0:  * Returns the next element in the iterator's list.  If there are
sl@0:  * no more elements, returns NULL.  If the iterator is out-of-sync
sl@0:  * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and
sl@0:  * NULL is returned.  If the native service string is a UChar*
sl@0:  * string, it is converted to char* with the invariant converter.
sl@0:  * The result is terminated by (char)0.  If the conversion fails
sl@0:  * (because a character cannot be converted) then status is set to
sl@0:  * U_INVARIANT_CONVERSION_ERROR and the return value is undefined
sl@0:  * (but non-NULL).
sl@0:  * @param en the iterator object
sl@0:  * @param resultLength pointer to receive the length of the result
sl@0:  *                     (not including the terminating \\0).
sl@0:  *                     If the pointer is NULL it is ignored.
sl@0:  * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
sl@0:  *               the iterator is out of sync with its service.  Set to
sl@0:  *               U_INVARIANT_CONVERSION_ERROR if the underlying native string is
sl@0:  *               UChar* and conversion to char* with the invariant converter
sl@0:  *               fails. This error pertains only to current string, so iteration
sl@0:  *               might be able to continue successfully.
sl@0:  * @return a pointer to the string.  The string will be
sl@0:  *         zero-terminated.  The return pointer is owned by this iterator
sl@0:  *         and must not be deleted by the caller.  The pointer is valid
sl@0:  *         until the next call to any uenum_... method, including
sl@0:  *         uenum_next() or uenum_unext().  When all strings have been
sl@0:  *         traversed, returns NULL.
sl@0:  * @stable ICU 2.2
sl@0:  */
sl@0: U_STABLE const char* U_EXPORT2
sl@0: uenum_next(UEnumeration* en,
sl@0:            int32_t* resultLength,
sl@0:            UErrorCode* status);
sl@0: 
sl@0: /**
sl@0:  * Resets the iterator to the current list of service IDs.  This
sl@0:  * re-establishes sync with the service and rewinds the iterator
sl@0:  * to start at the first element.
sl@0:  * @param en the iterator object
sl@0:  * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
sl@0:  *               the iterator is out of sync with its service.  
sl@0:  * @stable ICU 2.2
sl@0:  */
sl@0: U_STABLE void U_EXPORT2
sl@0: uenum_reset(UEnumeration* en, UErrorCode* status);
sl@0: 
sl@0: #endif