1 // © 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
3 /*
4 *******************************************************************************
5 *
6 *   Copyright (C) 2002-2013, International Business Machines
7 *   Corporation and others.  All Rights Reserved.
8 *
9 *******************************************************************************
10 *   file name:  uenum.h
11 *   encoding:   UTF-8
12 *   tab size:   8 (not used)
13 *   indentation:2
14 *
15 *   created on: 2002jul08
16 *   created by: Vladimir Weinstein
17 */
18 
19 #ifndef __UENUM_H
20 #define __UENUM_H
21 
22 #include "unicode/utypes.h"
23 
24 #if U_SHOW_CPLUSPLUS_API
25 #include "unicode/localpointer.h"
26 
27 U_NAMESPACE_BEGIN
28 class StringEnumeration;
29 U_NAMESPACE_END
30 #endif   // U_SHOW_CPLUSPLUS_API
31 
32 /**
33  * \file
34  * \brief C API: String Enumeration
35  */
36 
37 /**
38  * An enumeration object.
39  * For usage in C programs.
40  * @stable ICU 2.2
41  */
42 struct UEnumeration;
43 /** structure representing an enumeration object instance @stable ICU 2.2 */
44 typedef struct UEnumeration UEnumeration;
45 
46 /**
47  * Disposes of resources in use by the iterator.  If en is NULL,
48  * does nothing.  After this call, any char* or UChar* pointer
49  * returned by uenum_unext() or uenum_next() is invalid.
50  * @param en UEnumeration structure pointer
51  * @stable ICU 2.2
52  */
53 U_CAPI void U_EXPORT2
54 uenum_close(UEnumeration* en);
55 
56 
57 /**
58  * Returns the number of elements that the iterator traverses.  If
59  * the iterator is out-of-sync with its service, status is set to
60  * U_ENUM_OUT_OF_SYNC_ERROR.
61  * This is a convenience function. It can end up being very
62  * expensive as all the items might have to be pre-fetched (depending
63  * on the type of data being traversed). Use with caution and only
64  * when necessary.
65  * @param en UEnumeration structure pointer
66  * @param status error code, can be U_ENUM_OUT_OF_SYNC_ERROR if the
67  *               iterator is out of sync.
68  * @return number of elements in the iterator
69  * @stable ICU 2.2
70  */
71 U_CAPI int32_t U_EXPORT2
72 uenum_count(UEnumeration* en, UErrorCode* status);
73 
74 /**
75  * Returns the next element in the iterator's list.  If there are
76  * no more elements, returns NULL.  If the iterator is out-of-sync
77  * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and
78  * NULL is returned.  If the native service string is a char* string,
79  * it is converted to UChar* with the invariant converter.
80  * The result is terminated by (UChar)0.
81  * @param en the iterator object
82  * @param resultLength pointer to receive the length of the result
83  *                     (not including the terminating \\0).
84  *                     If the pointer is NULL it is ignored.
85  * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
86  *               the iterator is out of sync with its service.
87  * @return a pointer to the string.  The string will be
88  *         zero-terminated.  The return pointer is owned by this iterator
89  *         and must not be deleted by the caller.  The pointer is valid
90  *         until the next call to any uenum_... method, including
91  *         uenum_next() or uenum_unext().  When all strings have been
92  *         traversed, returns NULL.
93  * @stable ICU 2.2
94  */
95 U_CAPI const UChar* U_EXPORT2
96 uenum_unext(UEnumeration* en,
97             int32_t* resultLength,
98             UErrorCode* status);
99 
100 /**
101  * Returns the next element in the iterator's list.  If there are
102  * no more elements, returns NULL.  If the iterator is out-of-sync
103  * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and
104  * NULL is returned.  If the native service string is a UChar*
105  * string, it is converted to char* with the invariant converter.
106  * The result is terminated by (char)0.  If the conversion fails
107  * (because a character cannot be converted) then status is set to
108  * U_INVARIANT_CONVERSION_ERROR and the return value is undefined
109  * (but non-NULL).
110  * @param en the iterator object
111  * @param resultLength pointer to receive the length of the result
112  *                     (not including the terminating \\0).
113  *                     If the pointer is NULL it is ignored.
114  * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
115  *               the iterator is out of sync with its service.  Set to
116  *               U_INVARIANT_CONVERSION_ERROR if the underlying native string is
117  *               UChar* and conversion to char* with the invariant converter
118  *               fails. This error pertains only to current string, so iteration
119  *               might be able to continue successfully.
120  * @return a pointer to the string.  The string will be
121  *         zero-terminated.  The return pointer is owned by this iterator
122  *         and must not be deleted by the caller.  The pointer is valid
123  *         until the next call to any uenum_... method, including
124  *         uenum_next() or uenum_unext().  When all strings have been
125  *         traversed, returns NULL.
126  * @stable ICU 2.2
127  */
128 U_CAPI const char* U_EXPORT2
129 uenum_next(UEnumeration* en,
130            int32_t* resultLength,
131            UErrorCode* status);
132 
133 /**
134  * Resets the iterator to the current list of service IDs.  This
135  * re-establishes sync with the service and rewinds the iterator
136  * to start at the first element.
137  * @param en the iterator object
138  * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
139  *               the iterator is out of sync with its service.
140  * @stable ICU 2.2
141  */
142 U_CAPI void U_EXPORT2
143 uenum_reset(UEnumeration* en, UErrorCode* status);
144 #endif
145