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 */
27struct UEnumeration;
28/** structure representing an enumeration object instance @stable ICU 2.2 */
29typedef 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 */
38U_STABLE void U_EXPORT2
39uenum_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 */
55U_STABLE int32_t U_EXPORT2
56uenum_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 */
79U_STABLE const UChar* U_EXPORT2
80uenum_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 */
112U_STABLE const char* U_EXPORT2
113uenum_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 */
126U_STABLE void U_EXPORT2
127uenum_reset(UEnumeration* en, UErrorCode* status);
128
129#endif
130