2010-09-08 Ryuan Choi <ryuan.choi@samsung.com>
[WebKit-https.git] / JavaScriptGlue / icu / unicode / uenum.h
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