1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/i18n/unicode/ucoleitr.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,336 @@
1.4 +/*
1.5 +*******************************************************************************
1.6 +* Copyright (C) 2001-2011, International Business Machines
1.7 +* Corporation and others. All Rights Reserved.
1.8 +*******************************************************************************
1.9 +*
1.10 +* File ucoleitr.cpp
1.11 +*
1.12 +* Modification History:
1.13 +*
1.14 +* Date Name Description
1.15 +* 02/15/2001 synwee Modified all methods to process its own function
1.16 +* instead of calling the equivalent c++ api (coleitr.h)
1.17 +*******************************************************************************/
1.18 +
1.19 +#ifndef UCOLEITR_H
1.20 +#define UCOLEITR_H
1.21 +
1.22 +#include "unicode/utypes.h"
1.23 +
1.24 +#if !UCONFIG_NO_COLLATION
1.25 +
1.26 +/**
1.27 + * This indicates an error has occured during processing or if no more CEs is
1.28 + * to be returned.
1.29 + * @stable ICU 2.0
1.30 + */
1.31 +#define UCOL_NULLORDER ((int32_t)0xFFFFFFFF)
1.32 +
1.33 +#ifndef U_HIDE_INTERNAL_API
1.34 +/**
1.35 + * This indicates an error has occured during processing or there are no more CEs
1.36 + * to be returned.
1.37 + *
1.38 + * @internal
1.39 + */
1.40 +#define UCOL_PROCESSED_NULLORDER ((int64_t)U_INT64_MAX)
1.41 +#endif /* U_HIDE_INTERNAL_API */
1.42 +
1.43 +#include "unicode/ucol.h"
1.44 +
1.45 +/**
1.46 + * The UCollationElements struct.
1.47 + * For usage in C programs.
1.48 + * @stable ICU 2.0
1.49 + */
1.50 +typedef struct UCollationElements UCollationElements;
1.51 +
1.52 +/**
1.53 + * \file
1.54 + * \brief C API: UCollationElements
1.55 + *
1.56 + * The UCollationElements API is used as an iterator to walk through each
1.57 + * character of an international string. Use the iterator to return the
1.58 + * ordering priority of the positioned character. The ordering priority of a
1.59 + * character, which we refer to as a key, defines how a character is collated
1.60 + * in the given collation object.
1.61 + * For example, consider the following in Spanish:
1.62 + * <pre>
1.63 + * . "ca" -> the first key is key('c') and second key is key('a').
1.64 + * . "cha" -> the first key is key('ch') and second key is key('a').
1.65 + * </pre>
1.66 + * And in German,
1.67 + * <pre>
1.68 + * . "<ae ligature>b"-> the first key is key('a'), the second key is key('e'), and
1.69 + * . the third key is key('b').
1.70 + * </pre>
1.71 + * <p>Example of the iterator usage: (without error checking)
1.72 + * <pre>
1.73 + * . void CollationElementIterator_Example()
1.74 + * . {
1.75 + * . UChar *s;
1.76 + * . t_int32 order, primaryOrder;
1.77 + * . UCollationElements *c;
1.78 + * . UCollatorOld *coll;
1.79 + * . UErrorCode success = U_ZERO_ERROR;
1.80 + * . s=(UChar*)malloc(sizeof(UChar) * (strlen("This is a test")+1) );
1.81 + * . u_uastrcpy(s, "This is a test");
1.82 + * . coll = ucol_open(NULL, &success);
1.83 + * . c = ucol_openElements(coll, str, u_strlen(str), &status);
1.84 + * . order = ucol_next(c, &success);
1.85 + * . ucol_reset(c);
1.86 + * . order = ucol_prev(c, &success);
1.87 + * . free(s);
1.88 + * . ucol_close(coll);
1.89 + * . ucol_closeElements(c);
1.90 + * . }
1.91 + * </pre>
1.92 + * <p>
1.93 + * ucol_next() returns the collation order of the next.
1.94 + * ucol_prev() returns the collation order of the previous character.
1.95 + * The Collation Element Iterator moves only in one direction between calls to
1.96 + * ucol_reset. That is, ucol_next() and ucol_prev can not be inter-used.
1.97 + * Whenever ucol_prev is to be called after ucol_next() or vice versa,
1.98 + * ucol_reset has to be called first to reset the status, shifting pointers to
1.99 + * either the end or the start of the string. Hence at the next call of
1.100 + * ucol_prev or ucol_next, the first or last collation order will be returned.
1.101 + * If a change of direction is done without a ucol_reset, the result is
1.102 + * undefined.
1.103 + * The result of a forward iterate (ucol_next) and reversed result of the
1.104 + * backward iterate (ucol_prev) on the same string are equivalent, if
1.105 + * collation orders with the value UCOL_IGNORABLE are ignored.
1.106 + * Character based on the comparison level of the collator. A collation order
1.107 + * consists of primary order, secondary order and tertiary order. The data
1.108 + * type of the collation order is <strong>t_int32</strong>.
1.109 + *
1.110 + * @see UCollator
1.111 + */
1.112 +
1.113 +/**
1.114 + * Open the collation elements for a string.
1.115 + *
1.116 + * @param coll The collator containing the desired collation rules.
1.117 + * @param text The text to iterate over.
1.118 + * @param textLength The number of characters in text, or -1 if null-terminated
1.119 + * @param status A pointer to an UErrorCode to receive any errors.
1.120 + * @return a struct containing collation element information
1.121 + * @stable ICU 2.0
1.122 + */
1.123 +U_STABLE UCollationElements* U_EXPORT2
1.124 +ucol_openElements(const UCollator *coll,
1.125 + const UChar *text,
1.126 + int32_t textLength,
1.127 + UErrorCode *status);
1.128 +
1.129 +
1.130 +/**
1.131 + * get a hash code for a key... Not very useful!
1.132 + * @param key the given key.
1.133 + * @param length the size of the key array.
1.134 + * @return the hash code.
1.135 + * @stable ICU 2.0
1.136 + */
1.137 +U_STABLE int32_t U_EXPORT2
1.138 +ucol_keyHashCode(const uint8_t* key, int32_t length);
1.139 +
1.140 +/**
1.141 + * Close a UCollationElements.
1.142 + * Once closed, a UCollationElements may no longer be used.
1.143 + * @param elems The UCollationElements to close.
1.144 + * @stable ICU 2.0
1.145 + */
1.146 +U_STABLE void U_EXPORT2
1.147 +ucol_closeElements(UCollationElements *elems);
1.148 +
1.149 +/**
1.150 + * Reset the collation elements to their initial state.
1.151 + * This will move the 'cursor' to the beginning of the text.
1.152 + * Property settings for collation will be reset to the current status.
1.153 + * @param elems The UCollationElements to reset.
1.154 + * @see ucol_next
1.155 + * @see ucol_previous
1.156 + * @stable ICU 2.0
1.157 + */
1.158 +U_STABLE void U_EXPORT2
1.159 +ucol_reset(UCollationElements *elems);
1.160 +
1.161 +#ifndef U_HIDE_INTERNAL_API
1.162 +/**
1.163 + * Set the collation elements to use implicit ordering for Han
1.164 + * even if they've been tailored. This will also force Hangul
1.165 + * syllables to be ordered by decomposing them to their component
1.166 + * Jamo.
1.167 + *
1.168 + * @param elems The UCollationElements containing the text.
1.169 + * @param status A pointer to a UErrorCode to reveive any errors.
1.170 + *
1.171 + * @internal
1.172 + */
1.173 +U_INTERNAL void U_EXPORT2
1.174 +ucol_forceHanImplicit(UCollationElements *elems, UErrorCode *status);
1.175 +#endif /* U_HIDE_INTERNAL_API */
1.176 +
1.177 +/**
1.178 + * Get the ordering priority of the next collation element in the text.
1.179 + * A single character may contain more than one collation element.
1.180 + * @param elems The UCollationElements containing the text.
1.181 + * @param status A pointer to an UErrorCode to receive any errors.
1.182 + * @return The next collation elements ordering, otherwise returns NULLORDER
1.183 + * if an error has occured or if the end of string has been reached
1.184 + * @stable ICU 2.0
1.185 + */
1.186 +U_STABLE int32_t U_EXPORT2
1.187 +ucol_next(UCollationElements *elems, UErrorCode *status);
1.188 +
1.189 +/**
1.190 + * Get the ordering priority of the previous collation element in the text.
1.191 + * A single character may contain more than one collation element.
1.192 + * Note that internally a stack is used to store buffered collation elements.
1.193 + * It is very rare that the stack will overflow, however if such a case is
1.194 + * encountered, the problem can be solved by increasing the size
1.195 + * UCOL_EXPAND_CE_BUFFER_SIZE in ucol_imp.h.
1.196 + * @param elems The UCollationElements containing the text.
1.197 + * @param status A pointer to an UErrorCode to receive any errors. Noteably
1.198 + * a U_BUFFER_OVERFLOW_ERROR is returned if the internal stack
1.199 + * buffer has been exhausted.
1.200 + * @return The previous collation elements ordering, otherwise returns
1.201 + * NULLORDER if an error has occured or if the start of string has
1.202 + * been reached.
1.203 + * @stable ICU 2.0
1.204 + */
1.205 +U_STABLE int32_t U_EXPORT2
1.206 +ucol_previous(UCollationElements *elems, UErrorCode *status);
1.207 +
1.208 +#ifndef U_HIDE_INTERNAL_API
1.209 +/**
1.210 + * Get the processed ordering priority of the next collation element in the text.
1.211 + * A single character may contain more than one collation element.
1.212 + *
1.213 + * @param elems The UCollationElements containing the text.
1.214 + * @param ixLow a pointer to an int32_t to receive the iterator index before fetching the CE.
1.215 + * @param ixHigh a pointer to an int32_t to receive the iterator index after fetching the CE.
1.216 + * @param status A pointer to an UErrorCode to receive any errors.
1.217 + * @return The next collation elements ordering, otherwise returns UCOL_PROCESSED_NULLORDER
1.218 + * if an error has occured or if the end of string has been reached
1.219 + *
1.220 + * @internal
1.221 + */
1.222 +U_INTERNAL int64_t U_EXPORT2
1.223 +ucol_nextProcessed(UCollationElements *elems, int32_t *ixLow, int32_t *ixHigh, UErrorCode *status);
1.224 +
1.225 +/**
1.226 + * Get the processed ordering priority of the previous collation element in the text.
1.227 + * A single character may contain more than one collation element.
1.228 + * Note that internally a stack is used to store buffered collation elements.
1.229 + * It is very rare that the stack will overflow, however if such a case is
1.230 + * encountered, the problem can be solved by increasing the size
1.231 + * UCOL_EXPAND_CE_BUFFER_SIZE in ucol_imp.h.
1.232 + *
1.233 + * @param elems The UCollationElements containing the text.
1.234 + * @param ixLow A pointer to an int32_t to receive the iterator index after fetching the CE
1.235 + * @param ixHigh A pointer to an int32_t to receiver the iterator index before fetching the CE
1.236 + * @param status A pointer to an UErrorCode to receive any errors. Noteably
1.237 + * a U_BUFFER_OVERFLOW_ERROR is returned if the internal stack
1.238 + * buffer has been exhausted.
1.239 + * @return The previous collation elements ordering, otherwise returns
1.240 + * UCOL_PROCESSED_NULLORDER if an error has occured or if the start of
1.241 + * string has been reached.
1.242 + *
1.243 + * @internal
1.244 + */
1.245 +U_INTERNAL int64_t U_EXPORT2
1.246 +ucol_previousProcessed(UCollationElements *elems, int32_t *ixLow, int32_t *ixHigh, UErrorCode *status);
1.247 +#endif /* U_HIDE_INTERNAL_API */
1.248 +
1.249 +/**
1.250 + * Get the maximum length of any expansion sequences that end with the
1.251 + * specified comparison order.
1.252 + * This is useful for .... ?
1.253 + * @param elems The UCollationElements containing the text.
1.254 + * @param order A collation order returned by previous or next.
1.255 + * @return maximum size of the expansion sequences ending with the collation
1.256 + * element or 1 if collation element does not occur at the end of any
1.257 + * expansion sequence
1.258 + * @stable ICU 2.0
1.259 + */
1.260 +U_STABLE int32_t U_EXPORT2
1.261 +ucol_getMaxExpansion(const UCollationElements *elems, int32_t order);
1.262 +
1.263 +/**
1.264 + * Set the text containing the collation elements.
1.265 + * Property settings for collation will remain the same.
1.266 + * In order to reset the iterator to the current collation property settings,
1.267 + * the API reset() has to be called.
1.268 + * @param elems The UCollationElements to set.
1.269 + * @param text The source text containing the collation elements.
1.270 + * @param textLength The length of text, or -1 if null-terminated.
1.271 + * @param status A pointer to an UErrorCode to receive any errors.
1.272 + * @see ucol_getText
1.273 + * @stable ICU 2.0
1.274 + */
1.275 +U_STABLE void U_EXPORT2
1.276 +ucol_setText( UCollationElements *elems,
1.277 + const UChar *text,
1.278 + int32_t textLength,
1.279 + UErrorCode *status);
1.280 +
1.281 +/**
1.282 + * Get the offset of the current source character.
1.283 + * This is an offset into the text of the character containing the current
1.284 + * collation elements.
1.285 + * @param elems The UCollationElements to query.
1.286 + * @return The offset of the current source character.
1.287 + * @see ucol_setOffset
1.288 + * @stable ICU 2.0
1.289 + */
1.290 +U_STABLE int32_t U_EXPORT2
1.291 +ucol_getOffset(const UCollationElements *elems);
1.292 +
1.293 +/**
1.294 + * Set the offset of the current source character.
1.295 + * This is an offset into the text of the character to be processed.
1.296 + * Property settings for collation will remain the same.
1.297 + * In order to reset the iterator to the current collation property settings,
1.298 + * the API reset() has to be called.
1.299 + * @param elems The UCollationElements to set.
1.300 + * @param offset The desired character offset.
1.301 + * @param status A pointer to an UErrorCode to receive any errors.
1.302 + * @see ucol_getOffset
1.303 + * @stable ICU 2.0
1.304 + */
1.305 +U_STABLE void U_EXPORT2
1.306 +ucol_setOffset(UCollationElements *elems,
1.307 + int32_t offset,
1.308 + UErrorCode *status);
1.309 +
1.310 +/**
1.311 +* Get the primary order of a collation order.
1.312 +* @param order the collation order
1.313 +* @return the primary order of a collation order.
1.314 +* @stable ICU 2.6
1.315 +*/
1.316 +U_STABLE int32_t U_EXPORT2
1.317 +ucol_primaryOrder (int32_t order);
1.318 +
1.319 +/**
1.320 +* Get the secondary order of a collation order.
1.321 +* @param order the collation order
1.322 +* @return the secondary order of a collation order.
1.323 +* @stable ICU 2.6
1.324 +*/
1.325 +U_STABLE int32_t U_EXPORT2
1.326 +ucol_secondaryOrder (int32_t order);
1.327 +
1.328 +/**
1.329 +* Get the tertiary order of a collation order.
1.330 +* @param order the collation order
1.331 +* @return the tertiary order of a collation order.
1.332 +* @stable ICU 2.6
1.333 +*/
1.334 +U_STABLE int32_t U_EXPORT2
1.335 +ucol_tertiaryOrder (int32_t order);
1.336 +
1.337 +#endif /* #if !UCONFIG_NO_COLLATION */
1.338 +
1.339 +#endif
