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