Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/ucoleitr.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 69:33d812a61356
1 // © 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
3 /*
4 *******************************************************************************
5 * Copyright (C) 2001-2014, International Business Machines
6 * Corporation and others. All Rights Reserved.
7 *******************************************************************************
8 *
9 * File ucoleitr.h
10 *
11 * Modification History:
12 *
13 * Date Name Description
14 * 02/15/2001 synwee Modified all methods to process its own function
15 * instead of calling the equivalent c++ api (coleitr.h)
16 *******************************************************************************/
17
18 #ifndef UCOLEITR_H
19 #define UCOLEITR_H
20
21 #include "unicode/utypes.h"
22
23 #if !UCONFIG_NO_COLLATION
24
25 /**
26 * This indicates an error has occured during processing or if no more CEs is
27 * to be returned.
28 * @stable ICU 2.0
29 */
30 #define UCOL_NULLORDER ((int32_t)0xFFFFFFFF)
31
32 #include "unicode/ucol.h"
33
34 /**
35 * The UCollationElements struct.
36 * For usage in C programs.
37 * @stable ICU 2.0
38 */
39 typedef struct UCollationElements UCollationElements;
40
41 /**
42 * \file
43 * \brief C API: UCollationElements
44 *
45 * The UCollationElements API is used as an iterator to walk through each
46 * character of an international string. Use the iterator to return the
47 * ordering priority of the positioned character. The ordering priority of a
48 * character, which we refer to as a key, defines how a character is collated
49 * in the given collation object.
50 * For example, consider the following in Slovak and in traditional Spanish collation:
51 * <pre>
52 * . "ca" -> the first key is key('c') and second key is key('a').
53 * . "cha" -> the first key is key('ch') and second key is key('a').
54 * </pre>
55 * And in German phonebook collation,
56 * <pre>
57 * . "<ae ligature>b"-> the first key is key('a'), the second key is key('e'), and
58 * . the third key is key('b').
59 * </pre>
60 * <p>Example of the iterator usage: (without error checking)
61 * <pre>
62 * . void CollationElementIterator_Example()
63 * . {
64 * . UChar *s;
65 * . t_int32 order, primaryOrder;
66 * . UCollationElements *c;
67 * . UCollatorOld *coll;
68 * . UErrorCode success = U_ZERO_ERROR;
69 * . s=(UChar*)malloc(sizeof(UChar) * (strlen("This is a test")+1) );
70 * . u_uastrcpy(s, "This is a test");
71 * . coll = ucol_open(NULL, &success);
72 * . c = ucol_openElements(coll, str, u_strlen(str), &status);
73 * . order = ucol_next(c, &success);
74 * . ucol_reset(c);
75 * . order = ucol_prev(c, &success);
76 * . free(s);
77 * . ucol_close(coll);
78 * . ucol_closeElements(c);
79 * . }
80 * </pre>
81 * <p>
82 * ucol_next() returns the collation order of the next.
83 * ucol_prev() returns the collation order of the previous character.
84 * The Collation Element Iterator moves only in one direction between calls to
85 * ucol_reset. That is, ucol_next() and ucol_prev can not be inter-used.
86 * Whenever ucol_prev is to be called after ucol_next() or vice versa,
87 * ucol_reset has to be called first to reset the status, shifting pointers to
88 * either the end or the start of the string. Hence at the next call of
89 * ucol_prev or ucol_next, the first or last collation order will be returned.
90 * If a change of direction is done without a ucol_reset, the result is
91 * undefined.
92 * The result of a forward iterate (ucol_next) and reversed result of the
93 * backward iterate (ucol_prev) on the same string are equivalent, if
94 * collation orders with the value 0 are ignored.
95 * Character based on the comparison level of the collator. A collation order
96 * consists of primary order, secondary order and tertiary order. The data
97 * type of the collation order is <strong>int32_t</strong>.
98 *
99 * @see UCollator
100 */
101
102 /**
103 * Open the collation elements for a string.
104 *
105 * @param coll The collator containing the desired collation rules.
106 * @param text The text to iterate over.
107 * @param textLength The number of characters in text, or -1 if null-terminated
108 * @param status A pointer to a UErrorCode to receive any errors.
109 * @return a struct containing collation element information
110 * @stable ICU 2.0
111 */
112 U_STABLE UCollationElements* U_EXPORT2
113 ucol_openElements(const UCollator *coll,
114 const UChar *text,
115 int32_t textLength,
116 UErrorCode *status);
117
118
119 /**
120 * get a hash code for a key... Not very useful!
121 * @param key the given key.
122 * @param length the size of the key array.
123 * @return the hash code.
124 * @stable ICU 2.0
125 */
126 U_STABLE int32_t U_EXPORT2
127 ucol_keyHashCode(const uint8_t* key, int32_t length);
128
129 /**
130 * Close a UCollationElements.
131 * Once closed, a UCollationElements may no longer be used.
132 * @param elems The UCollationElements to close.
133 * @stable ICU 2.0
134 */
135 U_STABLE void U_EXPORT2
136 ucol_closeElements(UCollationElements *elems);
137
138 /**
139 * Reset the collation elements to their initial state.
140 * This will move the 'cursor' to the beginning of the text.
141 * Property settings for collation will be reset to the current status.
142 * @param elems The UCollationElements to reset.
143 * @see ucol_next
144 * @see ucol_previous
145 * @stable ICU 2.0
146 */
147 U_STABLE void U_EXPORT2
148 ucol_reset(UCollationElements *elems);
149
150 /**
151 * Get the ordering priority of the next collation element in the text.
152 * A single character may contain more than one collation element.
153 * @param elems The UCollationElements containing the text.
154 * @param status A pointer to a UErrorCode to receive any errors.
155 * @return The next collation elements ordering, otherwise returns UCOL_NULLORDER
156 * if an error has occured or if the end of string has been reached
157 * @stable ICU 2.0
158 */
159 U_STABLE int32_t U_EXPORT2
160 ucol_next(UCollationElements *elems, UErrorCode *status);
161
162 /**
163 * Get the ordering priority of the previous collation element in the text.
164 * A single character may contain more than one collation element.
165 * Note that internally a stack is used to store buffered collation elements.
166 * @param elems The UCollationElements containing the text.
167 * @param status A pointer to a UErrorCode to receive any errors. Noteably
168 * a U_BUFFER_OVERFLOW_ERROR is returned if the internal stack
169 * buffer has been exhausted.
170 * @return The previous collation elements ordering, otherwise returns
171 * UCOL_NULLORDER if an error has occured or if the start of string has
172 * been reached.
173 * @stable ICU 2.0
174 */
175 U_STABLE int32_t U_EXPORT2
176 ucol_previous(UCollationElements *elems, UErrorCode *status);
177
178 /**
179 * Get the maximum length of any expansion sequences that end with the
180 * specified comparison order.
181 * This is useful for .... ?
182 * @param elems The UCollationElements containing the text.
183 * @param order A collation order returned by previous or next.
184 * @return maximum size of the expansion sequences ending with the collation
185 * element or 1 if collation element does not occur at the end of any
186 * expansion sequence
187 * @stable ICU 2.0
188 */
189 U_STABLE int32_t U_EXPORT2
190 ucol_getMaxExpansion(const UCollationElements *elems, int32_t order);
191
192 /**
193 * Set the text containing the collation elements.
194 * Property settings for collation will remain the same.
195 * In order to reset the iterator to the current collation property settings,
196 * the API reset() has to be called.
197 * @param elems The UCollationElements to set.
198 * @param text The source text containing the collation elements.
199 * @param textLength The length of text, or -1 if null-terminated.
200 * @param status A pointer to a UErrorCode to receive any errors.
201 * @see ucol_getText
202 * @stable ICU 2.0
203 */
204 U_STABLE void U_EXPORT2
205 ucol_setText( UCollationElements *elems,
206 const UChar *text,
207 int32_t textLength,
208 UErrorCode *status);
209
210 /**
211 * Get the offset of the current source character.
212 * This is an offset into the text of the character containing the current
213 * collation elements.
214 * @param elems The UCollationElements to query.
215 * @return The offset of the current source character.
216 * @see ucol_setOffset
217 * @stable ICU 2.0
218 */
219 U_STABLE int32_t U_EXPORT2
220 ucol_getOffset(const UCollationElements *elems);
221
222 /**
223 * Set the offset of the current source character.
224 * This is an offset into the text of the character to be processed.
225 * Property settings for collation will remain the same.
226 * In order to reset the iterator to the current collation property settings,
227 * the API reset() has to be called.
228 * @param elems The UCollationElements to set.
229 * @param offset The desired character offset.
230 * @param status A pointer to a UErrorCode to receive any errors.
231 * @see ucol_getOffset
232 * @stable ICU 2.0
233 */
234 U_STABLE void U_EXPORT2
235 ucol_setOffset(UCollationElements *elems,
236 int32_t offset,
237 UErrorCode *status);
238
239 /**
240 * Get the primary order of a collation order.
241 * @param order the collation order
242 * @return the primary order of a collation order.
243 * @stable ICU 2.6
244 */
245 U_STABLE int32_t U_EXPORT2
246 ucol_primaryOrder (int32_t order);
247
248 /**
249 * Get the secondary order of a collation order.
250 * @param order the collation order
251 * @return the secondary order of a collation order.
252 * @stable ICU 2.6
253 */
254 U_STABLE int32_t U_EXPORT2
255 ucol_secondaryOrder (int32_t order);
256
257 /**
258 * Get the tertiary order of a collation order.
259 * @param order the collation order
260 * @return the tertiary order of a collation order.
261 * @stable ICU 2.6
262 */
263 U_STABLE int32_t U_EXPORT2
264 ucol_tertiaryOrder (int32_t order);
265
266 #endif /* #if !UCONFIG_NO_COLLATION */
267
268 #endif