|
1 /* |
|
2 ******************************************************************************* |
|
3 * |
|
4 * Copyright (C) 2002-2005, 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 * \file |
|
24 * \brief C API: String Enumeration |
|
25 */ |
|
26 |
|
27 /** |
|
28 * An enumeration object. |
|
29 * For usage in C programs. |
|
30 * @stable ICU 2.2 |
|
31 */ |
|
32 struct UEnumeration; |
|
33 /** structure representing an enumeration object instance @stable ICU 2.2 */ |
|
34 typedef struct UEnumeration UEnumeration; |
|
35 |
|
36 /** |
|
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 |
|
41 * @stable ICU 2.2 |
|
42 */ |
|
43 U_STABLE void U_EXPORT2 |
|
44 uenum_close(UEnumeration* en); |
|
45 |
|
46 /** |
|
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 |
|
53 * when necessary. |
|
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 |
|
58 * @stable ICU 2.2 |
|
59 */ |
|
60 U_STABLE int32_t U_EXPORT2 |
|
61 uenum_count(UEnumeration* en, UErrorCode* status); |
|
62 |
|
63 /** |
|
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. |
|
82 * @stable ICU 2.2 |
|
83 */ |
|
84 U_STABLE const UChar* U_EXPORT2 |
|
85 uenum_unext(UEnumeration* en, |
|
86 int32_t* resultLength, |
|
87 UErrorCode* status); |
|
88 |
|
89 /** |
|
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 |
|
98 * (but non-NULL). |
|
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. |
|
115 * @stable ICU 2.2 |
|
116 */ |
|
117 U_STABLE const char* U_EXPORT2 |
|
118 uenum_next(UEnumeration* en, |
|
119 int32_t* resultLength, |
|
120 UErrorCode* status); |
|
121 |
|
122 /** |
|
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. |
|
129 * @stable ICU 2.2 |
|
130 */ |
|
131 U_STABLE void U_EXPORT2 |
|
132 uenum_reset(UEnumeration* en, UErrorCode* status); |
|
133 |
|
134 #endif |