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 */
39typedef 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 */
112U_STABLE UCollationElements* U_EXPORT2
113ucol_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 */
126U_STABLE int32_t U_EXPORT2
127ucol_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 */
135U_STABLE void U_EXPORT2
136ucol_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 */
147U_STABLE void U_EXPORT2
148ucol_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 */
159U_STABLE int32_t U_EXPORT2
160ucol_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 */
175U_STABLE int32_t U_EXPORT2
176ucol_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 */
189U_STABLE int32_t U_EXPORT2
190ucol_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 */
204U_STABLE void U_EXPORT2
205ucol_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 */
219U_STABLE int32_t U_EXPORT2
220ucol_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 */
234U_STABLE void U_EXPORT2
235ucol_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*/
245U_STABLE int32_t U_EXPORT2
246ucol_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*/
254U_STABLE int32_t U_EXPORT2
255ucol_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*/
263U_STABLE int32_t U_EXPORT2
264ucol_tertiaryOrder (int32_t order);
265
266#endif /* #if !UCONFIG_NO_COLLATION */
267
268#endif
269