codekingpro/portable-devtools

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#include "unicode/localpointer.h"
24
25#if U_SHOW_CPLUSPLUS_API
26U_NAMESPACE_BEGIN
27class StringEnumeration;
28U_NAMESPACE_END
29#endif
30
31/**
32 * \file
33 * \brief C API: String Enumeration 
34 */
35 
36/**
37 * An enumeration object.
38 * For usage in C programs.
39 * @stable ICU 2.2
40 */
41struct UEnumeration;
42/** structure representing an enumeration object instance @stable ICU 2.2 */
43typedef struct UEnumeration UEnumeration;
44
45/**
46 * Disposes of resources in use by the iterator.  If en is NULL,
47 * does nothing.  After this call, any char* or UChar* pointer
48 * returned by uenum_unext() or uenum_next() is invalid.
49 * @param en UEnumeration structure pointer
50 * @stable ICU 2.2
51 */
52U_STABLE void U_EXPORT2
53uenum_close(UEnumeration* en);
54
55#if U_SHOW_CPLUSPLUS_API
56
57U_NAMESPACE_BEGIN
58
59/**
60 * \class LocalUEnumerationPointer
61 * "Smart pointer" class, closes a UEnumeration via uenum_close().
62 * For most methods see the LocalPointerBase base class.
63 *
64 * @see LocalPointerBase
65 * @see LocalPointer
66 * @stable ICU 4.4
67 */
68U_DEFINE_LOCAL_OPEN_POINTER(LocalUEnumerationPointer, UEnumeration, uenum_close);
69
70U_NAMESPACE_END
71
72#endif
73
74/**
75 * Returns the number of elements that the iterator traverses.  If
76 * the iterator is out-of-sync with its service, status is set to
77 * U_ENUM_OUT_OF_SYNC_ERROR.
78 * This is a convenience function. It can end up being very
79 * expensive as all the items might have to be pre-fetched (depending
80 * on the type of data being traversed). Use with caution and only 
81 * when necessary.
82 * @param en UEnumeration structure pointer
83 * @param status error code, can be U_ENUM_OUT_OF_SYNC_ERROR if the
84 *               iterator is out of sync.
85 * @return number of elements in the iterator
86 * @stable ICU 2.2
87 */
88U_STABLE int32_t U_EXPORT2
89uenum_count(UEnumeration* en, UErrorCode* status);
90
91/**
92 * Returns the next element in the iterator's list.  If there are
93 * no more elements, returns NULL.  If the iterator is out-of-sync
94 * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and
95 * NULL is returned.  If the native service string is a char* string,
96 * it is converted to UChar* with the invariant converter.
97 * The result is terminated by (UChar)0.
98 * @param en the iterator object
99 * @param resultLength pointer to receive the length of the result
100 *                     (not including the terminating \\0).
101 *                     If the pointer is NULL it is ignored.
102 * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
103 *               the iterator is out of sync with its service.
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 */
112U_STABLE const UChar* U_EXPORT2
113uenum_unext(UEnumeration* en,
114            int32_t* resultLength,
115            UErrorCode* status);
116
117/**
118 * Returns the next element in the iterator's list.  If there are
119 * no more elements, returns NULL.  If the iterator is out-of-sync
120 * with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and
121 * NULL is returned.  If the native service string is a UChar*
122 * string, it is converted to char* with the invariant converter.
123 * The result is terminated by (char)0.  If the conversion fails
124 * (because a character cannot be converted) then status is set to
125 * U_INVARIANT_CONVERSION_ERROR and the return value is undefined
126 * (but non-NULL).
127 * @param en the iterator object
128 * @param resultLength pointer to receive the length of the result
129 *                     (not including the terminating \\0).
130 *                     If the pointer is NULL it is ignored.
131 * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
132 *               the iterator is out of sync with its service.  Set to
133 *               U_INVARIANT_CONVERSION_ERROR if the underlying native string is
134 *               UChar* and conversion to char* with the invariant converter
135 *               fails. This error pertains only to current string, so iteration
136 *               might be able to continue successfully.
137 * @return a pointer to the string.  The string will be
138 *         zero-terminated.  The return pointer is owned by this iterator
139 *         and must not be deleted by the caller.  The pointer is valid
140 *         until the next call to any uenum_... method, including
141 *         uenum_next() or uenum_unext().  When all strings have been
142 *         traversed, returns NULL.
143 * @stable ICU 2.2
144 */
145U_STABLE const char* U_EXPORT2
146uenum_next(UEnumeration* en,
147           int32_t* resultLength,
148           UErrorCode* status);
149
150/**
151 * Resets the iterator to the current list of service IDs.  This
152 * re-establishes sync with the service and rewinds the iterator
153 * to start at the first element.
154 * @param en the iterator object
155 * @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
156 *               the iterator is out of sync with its service.  
157 * @stable ICU 2.2
158 */
159U_STABLE void U_EXPORT2
160uenum_reset(UEnumeration* en, UErrorCode* status);
161
162#if U_SHOW_CPLUSPLUS_API
163
164/**
165 * Given a StringEnumeration, wrap it in a UEnumeration.  The
166 * StringEnumeration is adopted; after this call, the caller must not
167 * delete it (regardless of error status).
168 * @param adopted the C++ StringEnumeration to be wrapped in a UEnumeration.
169 * @param ec the error code.
170 * @return a UEnumeration wrapping the adopted StringEnumeration.
171 * @stable ICU 4.2
172 */
173U_STABLE UEnumeration* U_EXPORT2
174uenum_openFromStringEnumeration(icu::StringEnumeration* adopted, UErrorCode* ec);
175
176#endif
177
178/**
179 * Given an array of const UChar* strings, return a UEnumeration.  String pointers from 0..count-1 must not be null.
180 * Do not free or modify either the string array or the characters it points to until this object has been destroyed with uenum_close.
181 * \snippet test/cintltst/uenumtst.c uenum_openUCharStringsEnumeration
182 * @param strings array of const UChar* strings (each null terminated). All storage is owned by the caller.
183 * @param count length of the array
184 * @param ec error code
185 * @return the new UEnumeration object. Caller is responsible for calling uenum_close to free memory.
186 * @see uenum_close
187 * @stable ICU 50
188 */
189U_STABLE UEnumeration* U_EXPORT2
190uenum_openUCharStringsEnumeration(const UChar* const strings[], int32_t count,
191                                 UErrorCode* ec);
192
193/**
194 * Given an array of const char* strings (invariant chars only), return a UEnumeration.  String pointers from 0..count-1 must not be null.
195 * Do not free or modify either the string array or the characters it points to until this object has been destroyed with uenum_close.
196 * \snippet test/cintltst/uenumtst.c uenum_openCharStringsEnumeration
197 * @param strings array of char* strings (each null terminated).  All storage is owned by the caller.
198 * @param count length of the array
199 * @param ec error code
200 * @return the new UEnumeration object. Caller is responsible for calling uenum_close to free memory
201 * @see uenum_close
202 * @stable ICU 50
203 */
204U_STABLE UEnumeration* U_EXPORT2
205uenum_openCharStringsEnumeration(const char* const strings[], int32_t count,
206                                 UErrorCode* ec);
207
208#endif
209