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
27U_NAMESPACE_BEGIN
28class StringEnumeration;
29U_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 */
42struct UEnumeration;
43/** structure representing an enumeration object instance @stable ICU 2.2 */
44typedef 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 */
53U_CAPI void U_EXPORT2
54uenum_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 */
71U_CAPI int32_t U_EXPORT2
72uenum_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 */
95U_CAPI const UChar* U_EXPORT2
96uenum_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 */
128U_CAPI const char* U_EXPORT2
129uenum_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 */
142U_CAPI void U_EXPORT2
143uenum_reset(UEnumeration* en, UErrorCode* status);
144#endif
145