Mercurial > repos > rliterman > csp2

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