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