|
sl@0
|
1 |
/*
|
|
sl@0
|
2 |
*******************************************************************************
|
|
sl@0
|
3 |
*
|
|
sl@0
|
4 |
* Copyright (C) 2002-2005, International Business Machines
|
|
sl@0
|
5 |
* Corporation and others. All Rights Reserved.
|
|
sl@0
|
6 |
*
|
|
sl@0
|
7 |
*******************************************************************************
|
|
sl@0
|
8 |
* file name: uenum.h
|
|
sl@0
|
9 |
* encoding: US-ASCII
|
|
sl@0
|
10 |
* tab size: 8 (not used)
|
|
sl@0
|
11 |
* indentation:2
|
|
sl@0
|
12 |
*
|
|
sl@0
|
13 |
* created on: 2002jul08
|
|
sl@0
|
14 |
* created by: Vladimir Weinstein
|
|
sl@0
|
15 |
*/
|
|
sl@0
|
16 |
|
|
sl@0
|
17 |
#ifndef __UENUM_H
|
|
sl@0
|
18 |
#define __UENUM_H
|
|
sl@0
|
19 |
|
|
sl@0
|
20 |
#include "unicode/utypes.h"
|
|
sl@0
|
21 |
|
|
sl@0
|
22 |
/**
|
|
sl@0
|
23 |
* \file
|
|
sl@0
|
24 |
* \brief C API: String Enumeration
|
|
sl@0
|
25 |
*/
|
|
sl@0
|
26 |
|
|
sl@0
|
27 |
/**
|
|
sl@0
|
28 |
* An enumeration object.
|
|
sl@0
|
29 |
* For usage in C programs.
|
|
sl@0
|
30 |
* @stable ICU 2.2
|
|
sl@0
|
31 |
*/
|
|
sl@0
|
32 |
struct UEnumeration;
|
|
sl@0
|
33 |
/** structure representing an enumeration object instance @stable ICU 2.2 */
|
|
sl@0
|
34 |
typedef struct UEnumeration UEnumeration;
|
|
sl@0
|
35 |
|
|
sl@0
|
36 |
/**
|
|
sl@0
|
37 |
* Disposes of resources in use by the iterator. If en is NULL,
|
|
sl@0
|
38 |
* does nothing. After this call, any char* or UChar* pointer
|
|
sl@0
|
39 |
* returned by uenum_unext() or uenum_next() is invalid.
|
|
sl@0
|
40 |
* @param en UEnumeration structure pointer
|
|
sl@0
|
41 |
* @stable ICU 2.2
|
|
sl@0
|
42 |
*/
|
|
sl@0
|
43 |
U_STABLE void U_EXPORT2
|
|
sl@0
|
44 |
uenum_close(UEnumeration* en);
|
|
sl@0
|
45 |
|
|
sl@0
|
46 |
/**
|
|
sl@0
|
47 |
* Returns the number of elements that the iterator traverses. If
|
|
sl@0
|
48 |
* the iterator is out-of-sync with its service, status is set to
|
|
sl@0
|
49 |
* U_ENUM_OUT_OF_SYNC_ERROR.
|
|
sl@0
|
50 |
* This is a convenience function. It can end up being very
|
|
sl@0
|
51 |
* expensive as all the items might have to be pre-fetched (depending
|
|
sl@0
|
52 |
* on the type of data being traversed). Use with caution and only
|
|
sl@0
|
53 |
* when necessary.
|
|
sl@0
|
54 |
* @param en UEnumeration structure pointer
|
|
sl@0
|
55 |
* @param status error code, can be U_ENUM_OUT_OF_SYNC_ERROR if the
|
|
sl@0
|
56 |
* iterator is out of sync.
|
|
sl@0
|
57 |
* @return number of elements in the iterator
|
|
sl@0
|
58 |
* @stable ICU 2.2
|
|
sl@0
|
59 |
*/
|
|
sl@0
|
60 |
U_STABLE int32_t U_EXPORT2
|
|
sl@0
|
61 |
uenum_count(UEnumeration* en, UErrorCode* status);
|
|
sl@0
|
62 |
|
|
sl@0
|
63 |
/**
|
|
sl@0
|
64 |
* Returns the next element in the iterator's list. If there are
|
|
sl@0
|
65 |
* no more elements, returns NULL. If the iterator is out-of-sync
|
|
sl@0
|
66 |
* with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and
|
|
sl@0
|
67 |
* NULL is returned. If the native service string is a char* string,
|
|
sl@0
|
68 |
* it is converted to UChar* with the invariant converter.
|
|
sl@0
|
69 |
* The result is terminated by (UChar)0.
|
|
sl@0
|
70 |
* @param en the iterator object
|
|
sl@0
|
71 |
* @param resultLength pointer to receive the length of the result
|
|
sl@0
|
72 |
* (not including the terminating \\0).
|
|
sl@0
|
73 |
* If the pointer is NULL it is ignored.
|
|
sl@0
|
74 |
* @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
|
|
sl@0
|
75 |
* the iterator is out of sync with its service.
|
|
sl@0
|
76 |
* @return a pointer to the string. The string will be
|
|
sl@0
|
77 |
* zero-terminated. The return pointer is owned by this iterator
|
|
sl@0
|
78 |
* and must not be deleted by the caller. The pointer is valid
|
|
sl@0
|
79 |
* until the next call to any uenum_... method, including
|
|
sl@0
|
80 |
* uenum_next() or uenum_unext(). When all strings have been
|
|
sl@0
|
81 |
* traversed, returns NULL.
|
|
sl@0
|
82 |
* @stable ICU 2.2
|
|
sl@0
|
83 |
*/
|
|
sl@0
|
84 |
U_STABLE const UChar* U_EXPORT2
|
|
sl@0
|
85 |
uenum_unext(UEnumeration* en,
|
|
sl@0
|
86 |
int32_t* resultLength,
|
|
sl@0
|
87 |
UErrorCode* status);
|
|
sl@0
|
88 |
|
|
sl@0
|
89 |
/**
|
|
sl@0
|
90 |
* Returns the next element in the iterator's list. If there are
|
|
sl@0
|
91 |
* no more elements, returns NULL. If the iterator is out-of-sync
|
|
sl@0
|
92 |
* with its service, status is set to U_ENUM_OUT_OF_SYNC_ERROR and
|
|
sl@0
|
93 |
* NULL is returned. If the native service string is a UChar*
|
|
sl@0
|
94 |
* string, it is converted to char* with the invariant converter.
|
|
sl@0
|
95 |
* The result is terminated by (char)0. If the conversion fails
|
|
sl@0
|
96 |
* (because a character cannot be converted) then status is set to
|
|
sl@0
|
97 |
* U_INVARIANT_CONVERSION_ERROR and the return value is undefined
|
|
sl@0
|
98 |
* (but non-NULL).
|
|
sl@0
|
99 |
* @param en the iterator object
|
|
sl@0
|
100 |
* @param resultLength pointer to receive the length of the result
|
|
sl@0
|
101 |
* (not including the terminating \\0).
|
|
sl@0
|
102 |
* If the pointer is NULL it is ignored.
|
|
sl@0
|
103 |
* @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
|
|
sl@0
|
104 |
* the iterator is out of sync with its service. Set to
|
|
sl@0
|
105 |
* U_INVARIANT_CONVERSION_ERROR if the underlying native string is
|
|
sl@0
|
106 |
* UChar* and conversion to char* with the invariant converter
|
|
sl@0
|
107 |
* fails. This error pertains only to current string, so iteration
|
|
sl@0
|
108 |
* might be able to continue successfully.
|
|
sl@0
|
109 |
* @return a pointer to the string. The string will be
|
|
sl@0
|
110 |
* zero-terminated. The return pointer is owned by this iterator
|
|
sl@0
|
111 |
* and must not be deleted by the caller. The pointer is valid
|
|
sl@0
|
112 |
* until the next call to any uenum_... method, including
|
|
sl@0
|
113 |
* uenum_next() or uenum_unext(). When all strings have been
|
|
sl@0
|
114 |
* traversed, returns NULL.
|
|
sl@0
|
115 |
* @stable ICU 2.2
|
|
sl@0
|
116 |
*/
|
|
sl@0
|
117 |
U_STABLE const char* U_EXPORT2
|
|
sl@0
|
118 |
uenum_next(UEnumeration* en,
|
|
sl@0
|
119 |
int32_t* resultLength,
|
|
sl@0
|
120 |
UErrorCode* status);
|
|
sl@0
|
121 |
|
|
sl@0
|
122 |
/**
|
|
sl@0
|
123 |
* Resets the iterator to the current list of service IDs. This
|
|
sl@0
|
124 |
* re-establishes sync with the service and rewinds the iterator
|
|
sl@0
|
125 |
* to start at the first element.
|
|
sl@0
|
126 |
* @param en the iterator object
|
|
sl@0
|
127 |
* @param status the error code, set to U_ENUM_OUT_OF_SYNC_ERROR if
|
|
sl@0
|
128 |
* the iterator is out of sync with its service.
|
|
sl@0
|
129 |
* @stable ICU 2.2
|
|
sl@0
|
130 |
*/
|
|
sl@0
|
131 |
U_STABLE void U_EXPORT2
|
|
sl@0
|
132 |
uenum_reset(UEnumeration* en, UErrorCode* status);
|
|
sl@0
|
133 |
|
|
sl@0
|
134 |
#endif
|