OLD | NEW |
1 /* | 1 /* |
2 ******************************************************************************* | 2 ******************************************************************************* |
3 * Copyright (C) 2001-2011, International Business Machines | 3 * Copyright (C) 2001-2014, International Business Machines |
4 * Corporation and others. All Rights Reserved. | 4 * Corporation and others. All Rights Reserved. |
5 ******************************************************************************* | 5 ******************************************************************************* |
6 * | 6 * |
7 * File ucoleitr.cpp | 7 * File ucoleitr.h |
8 * | 8 * |
9 * Modification History: | 9 * Modification History: |
10 * | 10 * |
11 * Date Name Description | 11 * Date Name Description |
12 * 02/15/2001 synwee Modified all methods to process its own function | 12 * 02/15/2001 synwee Modified all methods to process its own function |
13 * instead of calling the equivalent c++ api (coleitr.h) | 13 * instead of calling the equivalent c++ api (coleitr.h) |
14 *******************************************************************************/ | 14 *******************************************************************************/ |
15 | 15 |
16 #ifndef UCOLEITR_H | 16 #ifndef UCOLEITR_H |
17 #define UCOLEITR_H | 17 #define UCOLEITR_H |
18 | 18 |
19 #include "unicode/utypes.h" | 19 #include "unicode/utypes.h" |
20 | 20 |
21 #if !UCONFIG_NO_COLLATION | 21 #if !UCONFIG_NO_COLLATION |
22 | 22 |
23 /** | 23 /** |
24 * This indicates an error has occured during processing or if no more CEs is | 24 * This indicates an error has occured during processing or if no more CEs is |
25 * to be returned. | 25 * to be returned. |
26 * @stable ICU 2.0 | 26 * @stable ICU 2.0 |
27 */ | 27 */ |
28 #define UCOL_NULLORDER ((int32_t)0xFFFFFFFF) | 28 #define UCOL_NULLORDER ((int32_t)0xFFFFFFFF) |
29 | 29 |
30 #ifndef U_HIDE_INTERNAL_API | |
31 /** | |
32 * This indicates an error has occured during processing or there are no more CE
s | |
33 * to be returned. | |
34 * | |
35 * @internal | |
36 */ | |
37 #define UCOL_PROCESSED_NULLORDER ((int64_t)U_INT64_MAX) | |
38 #endif /* U_HIDE_INTERNAL_API */ | |
39 | |
40 #include "unicode/ucol.h" | 30 #include "unicode/ucol.h" |
41 | 31 |
42 /** | 32 /** |
43 * The UCollationElements struct. | 33 * The UCollationElements struct. |
44 * For usage in C programs. | 34 * For usage in C programs. |
45 * @stable ICU 2.0 | 35 * @stable ICU 2.0 |
46 */ | 36 */ |
47 typedef struct UCollationElements UCollationElements; | 37 typedef struct UCollationElements UCollationElements; |
48 | 38 |
49 /** | 39 /** |
50 * \file | 40 * \file |
51 * \brief C API: UCollationElements | 41 * \brief C API: UCollationElements |
52 * | 42 * |
53 * The UCollationElements API is used as an iterator to walk through each | 43 * The UCollationElements API is used as an iterator to walk through each |
54 * character of an international string. Use the iterator to return the | 44 * character of an international string. Use the iterator to return the |
55 * ordering priority of the positioned character. The ordering priority of a | 45 * ordering priority of the positioned character. The ordering priority of a |
56 * character, which we refer to as a key, defines how a character is collated | 46 * character, which we refer to as a key, defines how a character is collated |
57 * in the given collation object. | 47 * in the given collation object. |
58 * For example, consider the following in Spanish: | 48 * For example, consider the following in Slovak and in traditional Spanish coll
ation: |
59 * <pre> | 49 * <pre> |
60 * . "ca" -> the first key is key('c') and second key is key('a'). | 50 * . "ca" -> the first key is key('c') and second key is key('a'). |
61 * . "cha" -> the first key is key('ch') and second key is key('a'). | 51 * . "cha" -> the first key is key('ch') and second key is key('a'). |
62 * </pre> | 52 * </pre> |
63 * And in German, | 53 * And in German phonebook collation, |
64 * <pre> | 54 * <pre> |
65 * . "<ae ligature>b"-> the first key is key('a'), the second key is key('
e'), and | 55 * . "<ae ligature>b"-> the first key is key('a'), the second key is key('
e'), and |
66 * . the third key is key('b'). | 56 * . the third key is key('b'). |
67 * </pre> | 57 * </pre> |
68 * <p>Example of the iterator usage: (without error checking) | 58 * <p>Example of the iterator usage: (without error checking) |
69 * <pre> | 59 * <pre> |
70 * . void CollationElementIterator_Example() | 60 * . void CollationElementIterator_Example() |
71 * . { | 61 * . { |
72 * . UChar *s; | 62 * . UChar *s; |
73 * . t_int32 order, primaryOrder; | 63 * . t_int32 order, primaryOrder; |
(...skipping 18 matching lines...) Expand all Loading... |
92 * The Collation Element Iterator moves only in one direction between calls to | 82 * The Collation Element Iterator moves only in one direction between calls to |
93 * ucol_reset. That is, ucol_next() and ucol_prev can not be inter-used. | 83 * ucol_reset. That is, ucol_next() and ucol_prev can not be inter-used. |
94 * Whenever ucol_prev is to be called after ucol_next() or vice versa, | 84 * Whenever ucol_prev is to be called after ucol_next() or vice versa, |
95 * ucol_reset has to be called first to reset the status, shifting pointers to | 85 * ucol_reset has to be called first to reset the status, shifting pointers to |
96 * either the end or the start of the string. Hence at the next call of | 86 * either the end or the start of the string. Hence at the next call of |
97 * ucol_prev or ucol_next, the first or last collation order will be returned. | 87 * ucol_prev or ucol_next, the first or last collation order will be returned. |
98 * If a change of direction is done without a ucol_reset, the result is | 88 * If a change of direction is done without a ucol_reset, the result is |
99 * undefined. | 89 * undefined. |
100 * The result of a forward iterate (ucol_next) and reversed result of the | 90 * The result of a forward iterate (ucol_next) and reversed result of the |
101 * backward iterate (ucol_prev) on the same string are equivalent, if | 91 * backward iterate (ucol_prev) on the same string are equivalent, if |
102 * collation orders with the value UCOL_IGNORABLE are ignored. | 92 * collation orders with the value 0 are ignored. |
103 * Character based on the comparison level of the collator. A collation order | 93 * Character based on the comparison level of the collator. A collation order |
104 * consists of primary order, secondary order and tertiary order. The data | 94 * consists of primary order, secondary order and tertiary order. The data |
105 * type of the collation order is <strong>t_int32</strong>. | 95 * type of the collation order is <strong>int32_t</strong>. |
106 * | 96 * |
107 * @see UCollator | 97 * @see UCollator |
108 */ | 98 */ |
109 | 99 |
110 /** | 100 /** |
111 * Open the collation elements for a string. | 101 * Open the collation elements for a string. |
112 * | 102 * |
113 * @param coll The collator containing the desired collation rules. | 103 * @param coll The collator containing the desired collation rules. |
114 * @param text The text to iterate over. | 104 * @param text The text to iterate over. |
115 * @param textLength The number of characters in text, or -1 if null-terminated | 105 * @param textLength The number of characters in text, or -1 if null-terminated |
116 * @param status A pointer to an UErrorCode to receive any errors. | 106 * @param status A pointer to a UErrorCode to receive any errors. |
117 * @return a struct containing collation element information | 107 * @return a struct containing collation element information |
118 * @stable ICU 2.0 | 108 * @stable ICU 2.0 |
119 */ | 109 */ |
120 U_STABLE UCollationElements* U_EXPORT2 | 110 U_STABLE UCollationElements* U_EXPORT2 |
121 ucol_openElements(const UCollator *coll, | 111 ucol_openElements(const UCollator *coll, |
122 const UChar *text, | 112 const UChar *text, |
123 int32_t textLength, | 113 int32_t textLength, |
124 UErrorCode *status); | 114 UErrorCode *status); |
125 | 115 |
126 | 116 |
(...skipping 21 matching lines...) Expand all Loading... |
148 * This will move the 'cursor' to the beginning of the text. | 138 * This will move the 'cursor' to the beginning of the text. |
149 * Property settings for collation will be reset to the current status. | 139 * Property settings for collation will be reset to the current status. |
150 * @param elems The UCollationElements to reset. | 140 * @param elems The UCollationElements to reset. |
151 * @see ucol_next | 141 * @see ucol_next |
152 * @see ucol_previous | 142 * @see ucol_previous |
153 * @stable ICU 2.0 | 143 * @stable ICU 2.0 |
154 */ | 144 */ |
155 U_STABLE void U_EXPORT2 | 145 U_STABLE void U_EXPORT2 |
156 ucol_reset(UCollationElements *elems); | 146 ucol_reset(UCollationElements *elems); |
157 | 147 |
158 #ifndef U_HIDE_INTERNAL_API | |
159 /** | |
160 * Set the collation elements to use implicit ordering for Han | |
161 * even if they've been tailored. This will also force Hangul | |
162 * syllables to be ordered by decomposing them to their component | |
163 * Jamo. | |
164 * | |
165 * @param elems The UCollationElements containing the text. | |
166 * @param status A pointer to a UErrorCode to reveive any errors. | |
167 * | |
168 * @internal | |
169 */ | |
170 U_INTERNAL void U_EXPORT2 | |
171 ucol_forceHanImplicit(UCollationElements *elems, UErrorCode *status); | |
172 #endif /* U_HIDE_INTERNAL_API */ | |
173 | |
174 /** | 148 /** |
175 * Get the ordering priority of the next collation element in the text. | 149 * Get the ordering priority of the next collation element in the text. |
176 * A single character may contain more than one collation element. | 150 * A single character may contain more than one collation element. |
177 * @param elems The UCollationElements containing the text. | 151 * @param elems The UCollationElements containing the text. |
178 * @param status A pointer to an UErrorCode to receive any errors. | 152 * @param status A pointer to a UErrorCode to receive any errors. |
179 * @return The next collation elements ordering, otherwise returns NULLORDER | 153 * @return The next collation elements ordering, otherwise returns NULLORDER |
180 * if an error has occured or if the end of string has been reached | 154 * if an error has occured or if the end of string has been reached |
181 * @stable ICU 2.0 | 155 * @stable ICU 2.0 |
182 */ | 156 */ |
183 U_STABLE int32_t U_EXPORT2 | 157 U_STABLE int32_t U_EXPORT2 |
184 ucol_next(UCollationElements *elems, UErrorCode *status); | 158 ucol_next(UCollationElements *elems, UErrorCode *status); |
185 | 159 |
186 /** | 160 /** |
187 * Get the ordering priority of the previous collation element in the text. | 161 * Get the ordering priority of the previous collation element in the text. |
188 * A single character may contain more than one collation element. | 162 * A single character may contain more than one collation element. |
189 * Note that internally a stack is used to store buffered collation elements. | 163 * Note that internally a stack is used to store buffered collation elements. |
190 * It is very rare that the stack will overflow, however if such a case is | |
191 * encountered, the problem can be solved by increasing the size | |
192 * UCOL_EXPAND_CE_BUFFER_SIZE in ucol_imp.h. | |
193 * @param elems The UCollationElements containing the text. | 164 * @param elems The UCollationElements containing the text. |
194 * @param status A pointer to an UErrorCode to receive any errors. Noteably | 165 * @param status A pointer to a UErrorCode to receive any errors. Noteably |
195 * a U_BUFFER_OVERFLOW_ERROR is returned if the internal stack | 166 * a U_BUFFER_OVERFLOW_ERROR is returned if the internal stack |
196 * buffer has been exhausted. | 167 * buffer has been exhausted. |
197 * @return The previous collation elements ordering, otherwise returns | 168 * @return The previous collation elements ordering, otherwise returns |
198 * NULLORDER if an error has occured or if the start of string has | 169 * NULLORDER if an error has occured or if the start of string has |
199 * been reached. | 170 * been reached. |
200 * @stable ICU 2.0 | 171 * @stable ICU 2.0 |
201 */ | 172 */ |
202 U_STABLE int32_t U_EXPORT2 | 173 U_STABLE int32_t U_EXPORT2 |
203 ucol_previous(UCollationElements *elems, UErrorCode *status); | 174 ucol_previous(UCollationElements *elems, UErrorCode *status); |
204 | 175 |
205 #ifndef U_HIDE_INTERNAL_API | |
206 /** | |
207 * Get the processed ordering priority of the next collation element in the text
. | |
208 * A single character may contain more than one collation element. | |
209 * | |
210 * @param elems The UCollationElements containing the text. | |
211 * @param ixLow a pointer to an int32_t to receive the iterator index before fet
ching the CE. | |
212 * @param ixHigh a pointer to an int32_t to receive the iterator index after fet
ching the CE. | |
213 * @param status A pointer to an UErrorCode to receive any errors. | |
214 * @return The next collation elements ordering, otherwise returns UCOL_PROCESSE
D_NULLORDER | |
215 * if an error has occured or if the end of string has been reached | |
216 * | |
217 * @internal | |
218 */ | |
219 U_INTERNAL int64_t U_EXPORT2 | |
220 ucol_nextProcessed(UCollationElements *elems, int32_t *ixLow, int32_t *ixHigh, U
ErrorCode *status); | |
221 | |
222 /** | |
223 * Get the processed ordering priority of the previous collation element in the
text. | |
224 * A single character may contain more than one collation element. | |
225 * Note that internally a stack is used to store buffered collation elements. | |
226 * It is very rare that the stack will overflow, however if such a case is | |
227 * encountered, the problem can be solved by increasing the size | |
228 * UCOL_EXPAND_CE_BUFFER_SIZE in ucol_imp.h. | |
229 * | |
230 * @param elems The UCollationElements containing the text. | |
231 * @param ixLow A pointer to an int32_t to receive the iterator index after fetc
hing the CE | |
232 * @param ixHigh A pointer to an int32_t to receiver the iterator index before f
etching the CE | |
233 * @param status A pointer to an UErrorCode to receive any errors. Noteably | |
234 * a U_BUFFER_OVERFLOW_ERROR is returned if the internal stack | |
235 * buffer has been exhausted. | |
236 * @return The previous collation elements ordering, otherwise returns | |
237 * UCOL_PROCESSED_NULLORDER if an error has occured or if the start of | |
238 * string has been reached. | |
239 * | |
240 * @internal | |
241 */ | |
242 U_INTERNAL int64_t U_EXPORT2 | |
243 ucol_previousProcessed(UCollationElements *elems, int32_t *ixLow, int32_t *ixHig
h, UErrorCode *status); | |
244 #endif /* U_HIDE_INTERNAL_API */ | |
245 | |
246 /** | 176 /** |
247 * Get the maximum length of any expansion sequences that end with the | 177 * Get the maximum length of any expansion sequences that end with the |
248 * specified comparison order. | 178 * specified comparison order. |
249 * This is useful for .... ? | 179 * This is useful for .... ? |
250 * @param elems The UCollationElements containing the text. | 180 * @param elems The UCollationElements containing the text. |
251 * @param order A collation order returned by previous or next. | 181 * @param order A collation order returned by previous or next. |
252 * @return maximum size of the expansion sequences ending with the collation | 182 * @return maximum size of the expansion sequences ending with the collation |
253 * element or 1 if collation element does not occur at the end of any | 183 * element or 1 if collation element does not occur at the end of any |
254 * expansion sequence | 184 * expansion sequence |
255 * @stable ICU 2.0 | 185 * @stable ICU 2.0 |
256 */ | 186 */ |
257 U_STABLE int32_t U_EXPORT2 | 187 U_STABLE int32_t U_EXPORT2 |
258 ucol_getMaxExpansion(const UCollationElements *elems, int32_t order); | 188 ucol_getMaxExpansion(const UCollationElements *elems, int32_t order); |
259 | 189 |
260 /** | 190 /** |
261 * Set the text containing the collation elements. | 191 * Set the text containing the collation elements. |
262 * Property settings for collation will remain the same. | 192 * Property settings for collation will remain the same. |
263 * In order to reset the iterator to the current collation property settings, | 193 * In order to reset the iterator to the current collation property settings, |
264 * the API reset() has to be called. | 194 * the API reset() has to be called. |
265 * @param elems The UCollationElements to set. | 195 * @param elems The UCollationElements to set. |
266 * @param text The source text containing the collation elements. | 196 * @param text The source text containing the collation elements. |
267 * @param textLength The length of text, or -1 if null-terminated. | 197 * @param textLength The length of text, or -1 if null-terminated. |
268 * @param status A pointer to an UErrorCode to receive any errors. | 198 * @param status A pointer to a UErrorCode to receive any errors. |
269 * @see ucol_getText | 199 * @see ucol_getText |
270 * @stable ICU 2.0 | 200 * @stable ICU 2.0 |
271 */ | 201 */ |
272 U_STABLE void U_EXPORT2 | 202 U_STABLE void U_EXPORT2 |
273 ucol_setText( UCollationElements *elems, | 203 ucol_setText( UCollationElements *elems, |
274 const UChar *text, | 204 const UChar *text, |
275 int32_t textLength, | 205 int32_t textLength, |
276 UErrorCode *status); | 206 UErrorCode *status); |
277 | 207 |
278 /** | 208 /** |
279 * Get the offset of the current source character. | 209 * Get the offset of the current source character. |
280 * This is an offset into the text of the character containing the current | 210 * This is an offset into the text of the character containing the current |
281 * collation elements. | 211 * collation elements. |
282 * @param elems The UCollationElements to query. | 212 * @param elems The UCollationElements to query. |
283 * @return The offset of the current source character. | 213 * @return The offset of the current source character. |
284 * @see ucol_setOffset | 214 * @see ucol_setOffset |
285 * @stable ICU 2.0 | 215 * @stable ICU 2.0 |
286 */ | 216 */ |
287 U_STABLE int32_t U_EXPORT2 | 217 U_STABLE int32_t U_EXPORT2 |
288 ucol_getOffset(const UCollationElements *elems); | 218 ucol_getOffset(const UCollationElements *elems); |
289 | 219 |
290 /** | 220 /** |
291 * Set the offset of the current source character. | 221 * Set the offset of the current source character. |
292 * This is an offset into the text of the character to be processed. | 222 * This is an offset into the text of the character to be processed. |
293 * Property settings for collation will remain the same. | 223 * Property settings for collation will remain the same. |
294 * In order to reset the iterator to the current collation property settings, | 224 * In order to reset the iterator to the current collation property settings, |
295 * the API reset() has to be called. | 225 * the API reset() has to be called. |
296 * @param elems The UCollationElements to set. | 226 * @param elems The UCollationElements to set. |
297 * @param offset The desired character offset. | 227 * @param offset The desired character offset. |
298 * @param status A pointer to an UErrorCode to receive any errors. | 228 * @param status A pointer to a UErrorCode to receive any errors. |
299 * @see ucol_getOffset | 229 * @see ucol_getOffset |
300 * @stable ICU 2.0 | 230 * @stable ICU 2.0 |
301 */ | 231 */ |
302 U_STABLE void U_EXPORT2 | 232 U_STABLE void U_EXPORT2 |
303 ucol_setOffset(UCollationElements *elems, | 233 ucol_setOffset(UCollationElements *elems, |
304 int32_t offset, | 234 int32_t offset, |
305 UErrorCode *status); | 235 UErrorCode *status); |
306 | 236 |
307 /** | 237 /** |
308 * Get the primary order of a collation order. | 238 * Get the primary order of a collation order. |
(...skipping 18 matching lines...) Expand all Loading... |
327 * @param order the collation order | 257 * @param order the collation order |
328 * @return the tertiary order of a collation order. | 258 * @return the tertiary order of a collation order. |
329 * @stable ICU 2.6 | 259 * @stable ICU 2.6 |
330 */ | 260 */ |
331 U_STABLE int32_t U_EXPORT2 | 261 U_STABLE int32_t U_EXPORT2 |
332 ucol_tertiaryOrder (int32_t order); | 262 ucol_tertiaryOrder (int32_t order); |
333 | 263 |
334 #endif /* #if !UCONFIG_NO_COLLATION */ | 264 #endif /* #if !UCONFIG_NO_COLLATION */ |
335 | 265 |
336 #endif | 266 #endif |
OLD | NEW |