include/unicode/uenum.h

0001 // © 2016 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003 /*
0004 *******************************************************************************
0005 *
0006 *   Copyright (C) 2002-2013, International Business Machines
0007 *   Corporation and others.  All Rights Reserved.
0008 *
0009 *******************************************************************************
0010 *   file name:  uenum.h
0011 *   encoding:   UTF-8
0012 *   tab size:   8 (not used)
0013 *   indentation:2
0014 *
0015 *   created on: 2002jul08
0016 *   created by: Vladimir Weinstein
0017 */
0018
0019 #ifndef __UENUM_H
0020 #define __UENUM_H
0021
0022 #include "unicode/utypes.h"
0023
0024 #if U_SHOW_CPLUSPLUS_API
0025 #include "unicode/localpointer.h"
0026
0027 U_NAMESPACE_BEGIN
0028 class StringEnumeration;
0029 U_NAMESPACE_END
0030 #endif   // U_SHOW_CPLUSPLUS_API
0031
0032 /**
0033  * \file
0034  * \brief C API: String Enumeration
0035  */
0036
0037 /**
0038  * An enumeration object.
0039  * For usage in C programs.
0040  * @stable ICU 2.2
0041  */
0042 struct UEnumeration;
0043 /** structure representing an enumeration object instance @stable ICU 2.2 */
0044 typedef struct UEnumeration UEnumeration;
0045
0046 /**
0047  * Disposes of resources in use by the iterator.  If en is NULL,
0048  * does nothing.  After this call, any char* or UChar* pointer
0049  * returned by uenum_unext() or uenum_next() is invalid.
0050  * @param en UEnumeration structure pointer
0051  * @stable ICU 2.2
0052  */
0053 U_CAPI void U_EXPORT2
0054 uenum_close(UEnumeration* en);
0055
0056 #if U_SHOW_CPLUSPLUS_API
0057
0058 U_NAMESPACE_BEGIN
0059
0060 /**
0061  * \class LocalUEnumerationPointer
0062  * "Smart pointer" class, closes a UEnumeration via uenum_close().
0063  * For most methods see the LocalPointerBase base class.
0064  *
0065  * @see LocalPointerBase
0066  * @see LocalPointer
0067  * @stable ICU 4.4
0068  */
0069 U_DEFINE_LOCAL_OPEN_POINTER(LocalUEnumerationPointer, UEnumeration, uenum_close);
0070
0071 U_NAMESPACE_END
0072
0073 #endif
0074
0075 /**
0076  * Returns the number of elements that the iterator traverses.  If
0077  * the iterator is out-of-sync with its service, status is set to
0078  * U_ENUM_OUT_OF_SYNC_ERROR.
0079  * This is a convenience function. It can end up being very
0080  * expensive as all the items might have to be pre-fetched (depending
0081  * on the type of data being traversed). Use with caution and only
0082  * when necessary.
0083  * @param en UEnumeration structure pointer
0084  * @param status error code, can be U_ENUM_OUT_OF_SYNC_ERROR if the
0085  *               iterator is out of sync.
0086  * @return number of elements in the iterator
0087  * @stable ICU 2.2
0088  */
0089 U_CAPI int32_t U_EXPORT2
0090 uenum_count(UEnumeration* en, UErrorCode* status);
0091
0092 /**
0093  * Returns the next element in the iterator's list.  If there are
0094  * no more elements, returns NULL.  If the iterator is out-of-sync
0095  * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and
0096  * NULL is returned.  If the native service string is a char* string,
0097  * it is converted to UChar* with the invariant converter.
0098  * The result is terminated by (UChar)0.
0099  * @param en the iterator object
0100  * @param resultLength pointer to receive the length of the result
0101  *                     (not including the terminating \\0).
0102  *                     If the pointer is NULL it is ignored.
0103  * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
0104  *               the iterator is out of sync with its service.
0105  * @return a pointer to the string.  The string will be
0106  *         zero-terminated.  The return pointer is owned by this iterator
0107  *         and must not be deleted by the caller.  The pointer is valid
0108  *         until the next call to any uenum_... method, including
0109  *         uenum_next() or uenum_unext().  When all strings have been
0110  *         traversed, returns NULL.
0111  * @stable ICU 2.2
0112  */
0113 U_CAPI const UChar* U_EXPORT2
0114 uenum_unext(UEnumeration* en,
0115             int32_t* resultLength,
0116             UErrorCode* status);
0117
0118 /**
0119  * Returns the next element in the iterator's list.  If there are
0120  * no more elements, returns NULL.  If the iterator is out-of-sync
0121  * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and
0122  * NULL is returned.  If the native service string is a UChar*
0123  * string, it is converted to char* with the invariant converter.
0124  * The result is terminated by (char)0.  If the conversion fails
0125  * (because a character cannot be converted) then status is set to
0126  * U_INVARIANT_CONVERSION_ERROR and the return value is undefined
0127  * (but non-NULL).
0128  * @param en the iterator object
0129  * @param resultLength pointer to receive the length of the result
0130  *                     (not including the terminating \\0).
0131  *                     If the pointer is NULL it is ignored.
0132  * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
0133  *               the iterator is out of sync with its service.  Set to
0134  *               U_INVARIANT_CONVERSION_ERROR if the underlying native string is
0135  *               UChar* and conversion to char* with the invariant converter
0136  *               fails. This error pertains only to current string, so iteration
0137  *               might be able to continue successfully.
0138  * @return a pointer to the string.  The string will be
0139  *         zero-terminated.  The return pointer is owned by this iterator
0140  *         and must not be deleted by the caller.  The pointer is valid
0141  *         until the next call to any uenum_... method, including
0142  *         uenum_next() or uenum_unext().  When all strings have been
0143  *         traversed, returns NULL.
0144  * @stable ICU 2.2
0145  */
0146 U_CAPI const char* U_EXPORT2
0147 uenum_next(UEnumeration* en,
0148            int32_t* resultLength,
0149            UErrorCode* status);
0150
0151 /**
0152  * Resets the iterator to the current list of service IDs.  This
0153  * re-establishes sync with the service and rewinds the iterator
0154  * to start at the first element.
0155  * @param en the iterator object
0156  * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
0157  *               the iterator is out of sync with its service.
0158  * @stable ICU 2.2
0159  */
0160 U_CAPI void U_EXPORT2
0161 uenum_reset(UEnumeration* en, UErrorCode* status);
0162
0163 #if U_SHOW_CPLUSPLUS_API
0164
0165 /**
0166  * Given a StringEnumeration, wrap it in a UEnumeration.  The
0167  * StringEnumeration is adopted; after this call, the caller must not
0168  * delete it (regardless of error status).
0169  * @param adopted the C++ StringEnumeration to be wrapped in a UEnumeration.
0170  * @param ec the error code.
0171  * @return a UEnumeration wrapping the adopted StringEnumeration.
0172  * @stable ICU 4.2
0173  */
0174 U_CAPI UEnumeration* U_EXPORT2
0175 uenum_openFromStringEnumeration(icu::StringEnumeration* adopted, UErrorCode* ec);
0176
0177 #endif
0178
0179 /**
0180  * Given an array of const UChar* strings, return a UEnumeration.  String pointers from 0..count-1 must not be null.
0181  * Do not free or modify either the string array or the characters it points to until this object has been destroyed with uenum_close.
0182  * \snippet test/cintltst/uenumtst.c uenum_openUCharStringsEnumeration
0183  * @param strings array of const UChar* strings (each null terminated). All storage is owned by the caller.
0184  * @param count length of the array
0185  * @param ec error code
0186  * @return the new UEnumeration object. Caller is responsible for calling uenum_close to free memory.
0187  * @see uenum_close
0188  * @stable ICU 50
0189  */
0190 U_CAPI UEnumeration* U_EXPORT2
0191 uenum_openUCharStringsEnumeration(const UChar* const strings[], int32_t count,
0192                                  UErrorCode* ec);
0193
0194 /**
0195  * Given an array of const char* strings (invariant chars only), return a UEnumeration.  String pointers from 0..count-1 must not be null.
0196  * Do not free or modify either the string array or the characters it points to until this object has been destroyed with uenum_close.
0197  * \snippet test/cintltst/uenumtst.c uenum_openCharStringsEnumeration
0198  * @param strings array of char* strings (each null terminated).  All storage is owned by the caller.
0199  * @param count length of the array
0200  * @param ec error code
0201  * @return the new UEnumeration object. Caller is responsible for calling uenum_close to free memory
0202  * @see uenum_close
0203  * @stable ICU 50
0204  */
0205 U_CAPI UEnumeration* U_EXPORT2
0206 uenum_openCharStringsEnumeration(const char* const strings[], int32_t count,
0207                                  UErrorCode* ec);
0208
0209 #endif