2 *******************************************************************************
4 * Copyright (C) 2002-2005, International Business Machines
5 * Corporation and others. All Rights Reserved.
7 *******************************************************************************
10 * tab size: 8 (not used)
13 * created on: 2002jul08
14 * created by: Vladimir Weinstein
20 #include "unicode/utypes.h"
24 * \brief C API: String Enumeration
28 * An enumeration object.
29 * For usage in C programs.
33 /** structure representing an enumeration object instance @stable ICU 2.2 */
34 typedef struct UEnumeration UEnumeration;
37 * Disposes of resources in use by the iterator. If en is NULL,
38 * does nothing. After this call, any char* or UChar* pointer
39 * returned by uenum_unext() or uenum_next() is invalid.
40 * @param en UEnumeration structure pointer
43 U_STABLE void U_EXPORT2
44 uenum_close(UEnumeration* en);
47 * Returns the number of elements that the iterator traverses. If
48 * the iterator is out-of-sync with its service, status is set to
49 * U_ENUM_OUT_OF_SYNC_ERROR.
50 * This is a convenience function. It can end up being very
51 * expensive as all the items might have to be pre-fetched (depending
52 * on the type of data being traversed). Use with caution and only
54 * @param en UEnumeration structure pointer
55 * @param status error code, can be U_ENUM_OUT_OF_SYNC_ERROR if the
56 * iterator is out of sync.
57 * @return number of elements in the iterator
60 U_STABLE int32_t U_EXPORT2
61 uenum_count(UEnumeration* en, UErrorCode* status);
64 * Returns the next element in the iterator's list. If there are
65 * no more elements, returns NULL. If the iterator is out-of-sync
66 * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and
67 * NULL is returned. If the native service string is a char* string,
68 * it is converted to UChar* with the invariant converter.
69 * The result is terminated by (UChar)0.
70 * @param en the iterator object
71 * @param resultLength pointer to receive the length of the result
72 * (not including the terminating \\0).
73 * If the pointer is NULL it is ignored.
74 * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
75 * the iterator is out of sync with its service.
76 * @return a pointer to the string. The string will be
77 * zero-terminated. The return pointer is owned by this iterator
78 * and must not be deleted by the caller. The pointer is valid
79 * until the next call to any uenum_... method, including
80 * uenum_next() or uenum_unext(). When all strings have been
81 * traversed, returns NULL.
84 U_STABLE const UChar* U_EXPORT2
85 uenum_unext(UEnumeration* en,
86 int32_t* resultLength,
90 * Returns the next element in the iterator's list. If there are
91 * no more elements, returns NULL. If the iterator is out-of-sync
92 * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and
93 * NULL is returned. If the native service string is a UChar*
94 * string, it is converted to char* with the invariant converter.
95 * The result is terminated by (char)0. If the conversion fails
96 * (because a character cannot be converted) then status is set to
97 * U_INVARIANT_CONVERSION_ERROR and the return value is undefined
99 * @param en the iterator object
100 * @param resultLength pointer to receive the length of the result
101 * (not including the terminating \\0).
102 * If the pointer is NULL it is ignored.
103 * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
104 * the iterator is out of sync with its service. Set to
105 * U_INVARIANT_CONVERSION_ERROR if the underlying native string is
106 * UChar* and conversion to char* with the invariant converter
107 * fails. This error pertains only to current string, so iteration
108 * might be able to continue successfully.
109 * @return a pointer to the string. The string will be
110 * zero-terminated. The return pointer is owned by this iterator
111 * and must not be deleted by the caller. The pointer is valid
112 * until the next call to any uenum_... method, including
113 * uenum_next() or uenum_unext(). When all strings have been
114 * traversed, returns NULL.
117 U_STABLE const char* U_EXPORT2
118 uenum_next(UEnumeration* en,
119 int32_t* resultLength,
123 * Resets the iterator to the current list of service IDs. This
124 * re-establishes sync with the service and rewinds the iterator
125 * to start at the first element.
126 * @param en the iterator object
127 * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
128 * the iterator is out of sync with its service.
131 U_STABLE void U_EXPORT2
132 uenum_reset(UEnumeration* en, UErrorCode* status);