| /* |
| ******************************************************************************* |
| * Copyright (c) {1996-2001}, International Business Machines Corporation and others. |
| * All Rights Reserved. |
| ******************************************************************************* |
| */ |
| |
| #ifndef UCOL_H |
| #define UCOL_H |
| |
| #include "unicode/utypes.h" |
| #include "unicode/unorm.h" |
| #include "unicode/parseerr.h" |
| |
| /** |
| * \file |
| * \brief C API: Collator |
| * |
| * <h2> Collator C API </h2> |
| * |
| * The C API for Collator performs locale-sensitive |
| * string comparison. You use this class to build |
| * searching and sorting routines for natural language text. |
| * <em>Important: </em>The ICU collation service has been reimplemented |
| * in order to achieve better performance and UCA compliance. |
| * For details, see the |
| * <a href="http://oss.software.ibm.com/cvs/icu/~checkout~/icuhtml/design/collation/ICU_collation_design.htm"> |
| * collation design document</a>. |
| * <p> |
| * For more information about the collation service see |
| * <a href="http://oss.software.ibm.com/icu/userguide/Collate_Intro.html">the users guide</a>. |
| * <p> |
| * Collation service provides correct sorting orders for most locales supported in ICU. |
| * If specific data for a locale is not available, the orders eventually falls back |
| * to the <a href="http://www.unicode.org/unicode/reports/tr10/">UCA sort order</a>. |
| * <p> |
| * Sort ordering may be customized by providing your own set of rules. For more on |
| * this subject see the |
| * <a href="http://oss.software.ibm.com/icu/userguide/Collate_Customization.html"> |
| * Collation customization</a> section of the users guide. |
| * <p> |
| * @see UCollationResult |
| * @see UNormalizationMode |
| * @see UCollationStrength |
| * @see UCollationElements |
| */ |
| |
| /** A collation element iterator. |
| * For usage in C programs. |
| */ |
| struct collIterate; |
| /** structure representing collation element iterator instance */ |
| typedef struct collIterate collIterate; |
| |
| /** A collator. |
| * For usage in C programs. |
| */ |
| struct UCollator; |
| /** structure representing a collator object instance */ |
| typedef struct UCollator UCollator; |
| |
| |
| /** |
| * UCOL_LESS is returned if source string is compared to be less than target |
| * string in the u_strcoll() method. |
| * UCOL_EQUAL is returned if source string is compared to be equal to target |
| * string in the u_strcoll() method. |
| * UCOL_GREATER is returned if source string is compared to be greater than |
| * target string in the u_strcoll() method. |
| * @see u_strcoll() |
| * <p> |
| * Possible values for a comparison result */ |
| typedef enum { |
| /** string a == string b */ |
| UCOL_EQUAL = 0, |
| /** string a > string b */ |
| UCOL_GREATER = 1, |
| /** string a < string b */ |
| UCOL_LESS = -1 |
| } UCollationResult ; |
| |
| |
| /** Enum containing attribute values for controling collation behavior. */ |
| /* Here are all the allowable values. Not every attribute can take every value. The only */ |
| /* universal value is UCOL_DEFAULT, which resets the attribute value to the predefined */ |
| /* value for that locale */ |
| typedef enum { |
| /** accepted by most attributes */ |
| UCOL_DEFAULT = -1, |
| |
| /** Primary collation strength */ |
| UCOL_PRIMARY = 0, |
| /** Secondary collation strength */ |
| UCOL_SECONDARY = 1, |
| /** Tertiary collation strength */ |
| UCOL_TERTIARY = 2, |
| /** Default collation strength */ |
| UCOL_DEFAULT_STRENGTH = UCOL_TERTIARY, |
| UCOL_CE_STRENGTH_LIMIT, |
| /** Quaternary collation strength */ |
| UCOL_QUATERNARY=3, |
| /** Identical collation strength */ |
| UCOL_IDENTICAL=15, |
| UCOL_STRENGTH_LIMIT, |
| |
| /** Turn the feature off - works for UCOL_FRENCH_COLLATION, |
| UCOL_CASE_LEVEL, UCOL_HIRAGANA_QUATERNARY_MODE |
| & UCOL_DECOMPOSITION_MODE*/ |
| UCOL_OFF = 16, |
| /** Turn the feature on - works for UCOL_FRENCH_COLLATION, |
| UCOL_CASE_LEVEL, UCOL_HIRAGANA_QUATERNARY_MODE |
| & UCOL_DECOMPOSITION_MODE*/ |
| UCOL_ON = 17, |
| |
| /** Valid for UCOL_ALTERNATE_HANDLING. Alternate handling will be shifted */ |
| UCOL_SHIFTED = 20, |
| /** Valid for UCOL_ALTERNATE_HANDLING. Alternate handling will be non ignorable */ |
| UCOL_NON_IGNORABLE = 21, |
| |
| /** Valid for UCOL_CASE_FIRST - |
| lower case sorts before upper case */ |
| UCOL_LOWER_FIRST = 24, |
| /** upper case sorts before lower case */ |
| UCOL_UPPER_FIRST = 25, |
| |
| /** Valid for UCOL_NORMALIZATION_MODE |
| UCOL_ON & UCOL_OFF are also allowed |
| for this attribute */ |
| UCOL_ON_WITHOUT_HANGUL = 28, |
| |
| UCOL_ATTRIBUTE_VALUE_COUNT |
| |
| } UColAttributeValue; |
| |
| /** |
| * Base letter represents a primary difference. Set comparison |
| * level to UCOL_PRIMARY to ignore secondary and tertiary differences. |
| * Use this to set the strength of a Collator object. |
| * Example of primary difference, "abc" < "abd" |
| * |
| * Diacritical differences on the same base letter represent a secondary |
| * difference. Set comparison level to UCOL_SECONDARY to ignore tertiary |
| * differences. Use this to set the strength of a Collator object. |
| * Example of secondary difference, "ä" >> "a". |
| * |
| * Uppercase and lowercase versions of the same character represents a |
| * tertiary difference. Set comparison level to UCOL_TERTIARY to include |
| * all comparison differences. Use this to set the strength of a Collator |
| * object. |
| * Example of tertiary difference, "abc" <<< "ABC". |
| * |
| * Two characters are considered "identical" when they have the same |
| * unicode spellings. UCOL_IDENTICAL. |
| * For example, "ä" == "ä". |
| * |
| * UCollationStrength is also used to determine the strength of sort keys |
| * generated from UCollator objects |
| * These values can be now found in the UColAttributeValue enum. |
| **/ |
| typedef UColAttributeValue UCollationStrength; |
| |
| /** Attributes that collation service understands. All the attributes can take UCOL_DEFAULT |
| * value, as well as the values specific to each one. */ |
| typedef enum { |
| /** Attribute for direction of secondary weights - used in French.\ |
| * Acceptable values are UCOL_ON, which results in secondary weights |
| * being considered backwards and UCOL_OFF which treats secondary |
| * weights in the order they appear.*/ |
| UCOL_FRENCH_COLLATION, |
| /** Attribute for handling variable elements.\ |
| * Acceptable values are UCOL_NON_IGNORABLE (default) |
| * which treats all the codepoints with non-ignorable |
| * primary weights in the same way, |
| * and UCOL_SHIFTED which causes codepoints with primary |
| * weights that are equal or below the variable top value |
| * to be ignored on primary level and moved to the quaternary |
| * level.*/ |
| UCOL_ALTERNATE_HANDLING, |
| /** Controls the ordering of upper and lower case letters.\ |
| * Acceptable values are UCOL_OFF (default), which orders |
| * upper and lower case letters in accordance to their tertiary |
| * weights, UCOL_UPPER_FIRST which forces upper case letters to |
| * sort before lower case letters, and UCOL_LOWER_FIRST which does |
| * the opposite. */ |
| UCOL_CASE_FIRST, |
| /** Controls whether an extra case level (positioned before the third |
| * level) is generated or not.\ Acceptable values are UCOL_OFF (default), |
| * when case level is not generated, and UCOL_ON which causes the case |
| * level to be generated.\ Contents of the case level are affected by |
| * the value of UCOL_CASE_FIRST attribute.\ A simple way to ignore |
| * accent differences in a string is to set the strength to UCOL_PRIMARY |
| * and enable case level. */ |
| UCOL_CASE_LEVEL, |
| /** Controls whether the normalization check and necessary normalizations |
| * are performed.\ When set to UCOL_OFF (default) no normalization check |
| * is performed.\ The correctness of the result is guaranteed only if the |
| * input data is in so-called FCD form (see users manual for more info).\ |
| * When set to UCOL_ON, an incremental check is performed to see whether the input data |
| * is in the FCD form.\ If the data is not in the FCD form, incremental |
| * NFD normalization is performed. */ |
| UCOL_NORMALIZATION_MODE, |
| /** An alias for UCOL_NORMALIZATION_MODE attribute */ |
| UCOL_DECOMPOSITION_MODE = UCOL_NORMALIZATION_MODE, |
| /** The strength attribute.\ Can be either UCOL_PRIMARY, UCOL_SECONDARY, |
| * UCOL_TERTIARY, UCOL_QUATERNARY or UCOL_IDENTICAL.\ The usual strength |
| * for most locales (except Japanese) is tertiary.\ Quaternary strength |
| * is useful when combined with shifted setting for alternate handling |
| * attribute and for JIS x 4061 collation, when it is used to distinguish |
| * between Katakana and Hiragana (this is achieved by setting the |
| * UCOL_HIRAGANA_QUATERNARY mode to on.\ Otherwise, quaternary level |
| * is affected only by the number of non ignorable code points in |
| * the string.\ Identical strength is rarely useful, as it amounts |
| * to codepoints of the NFD form of the string. */ |
| UCOL_STRENGTH, |
| /** when turned on, this attribute |
| * positions Hiragana before all |
| * non-ignorables on quaternary level |
| * This is a sneaky way to produce JIS |
| * sort order */ |
| UCOL_HIRAGANA_QUATERNARY_MODE, |
| UCOL_ATTRIBUTE_COUNT |
| } UColAttribute; |
| |
| /** Options for retrieving the rule string */ |
| typedef enum { |
| UCOL_TAILORING_ONLY, /** Retrieve tailoring only */ |
| UCOL_FULL_RULES /** Retrieve UCA rules and tailoring */ |
| } UColRuleOption ; |
| |
| /** |
| * Open a UCollator for comparing strings. |
| * The UCollator pointer is used in all the calls to the Collation |
| * service. After finished, collator must be disposed of by calling |
| * \Ref{ucol_close}. |
| * @param loc The locale containing the required collation rules. |
| * if NULL is passed for the locale, UCA rules will be |
| * used. |
| * @param status A pointer to an UErrorCode to receive any errors |
| * @return A pointer to a UCollator, or 0 if an error occurred. |
| * @see ucol_openRules |
| * @see ucol_safeClone |
| * @see ucol_close |
| * @stable |
| */ |
| U_CAPI UCollator* U_EXPORT2 |
| ucol_open(const char *loc, UErrorCode *status); |
| |
| /** |
| * Produce an UCollator instance according to the rules supplied. |
| * The rules are used to change the default ordering, defined in the |
| * UCA in a process called tailoring. The resulting UCollator pointer |
| * can be used in the same way as the one obtained by \Ref{ucol_strcoll}. |
| * @param rules A string describing the collation rules. For the syntax |
| * of the rules please see users guide. |
| * @param rulesLength The length of rules, or -1 if null-terminated. |
| * @param normalizationMode The normalization mode: One of |
| * UCOL_OFF (expect the text to not need normalization), |
| * UCOL_ON (normalize), or |
| * UCOL_DEFAULT (set the mode according to the rules) |
| * @param strength The default collation strength; one of UCOL_PRIMARY, UCOL_SECONDARY, |
| * UCOL_TERTIARY, UCOL_IDENTICAL,UCOL_DEFAULT_STRENGTH - can be also set in the rules. |
| * @param parseError A pointer to UParseError to recieve information about errors |
| * occurred during parsing. This argument can currently be set |
| * to NULL, but at users own risk. Please provide a real structure. |
| * @param status A pointer to an UErrorCode to receive any errors |
| * @return A pointer to a UCollator.\ It is not guaranteed that NULL be returned in case |
| * of error - please use status argument to check for errors. |
| * @see ucol_open |
| * @see ucol_safeClone |
| * @see ucol_close |
| * @stable |
| */ |
| U_CAPI UCollator* U_EXPORT2 |
| ucol_openRules( const UChar *rules, |
| int32_t rulesLength, |
| UColAttributeValue normalizationMode, |
| UCollationStrength strength, |
| UParseError *parseError, |
| UErrorCode *status); |
| |
| /** |
| * Close a UCollator. |
| * Once closed, a UCollator should not be used.\ Every open collator should |
| * be closed.\ Otherwise, a memory leak will result. |
| * @param coll The UCollator to close. |
| * @see ucol_open |
| * @see ucol_openRules |
| * @see ucol_safeClone |
| * @stable |
| */ |
| U_CAPI void U_EXPORT2 |
| ucol_close(UCollator *coll); |
| |
| /** |
| * Compare two strings. |
| * The strings will be compared using the options already specified. |
| * @param coll The UCollator containing the comparison rules. |
| * @param source The source string. |
| * @param sourceLength The length of source, or -1 if null-terminated. |
| * @param target The target string. |
| * @param targetLength The length of target, or -1 if null-terminated. |
| * @return The result of comparing the strings; one of UCOL_EQUAL, |
| * UCOL_GREATER, UCOL_LESS |
| * @see ucol_greater |
| * @see ucol_greaterOrEqual |
| * @see ucol_equal |
| * @stable |
| */ |
| U_CAPI UCollationResult U_EXPORT2 |
| ucol_strcoll( const UCollator *coll, |
| const UChar *source, |
| int32_t sourceLength, |
| const UChar *target, |
| int32_t targetLength); |
| |
| /** |
| * Determine if one string is greater than another. |
| * This function is equivalent to \Ref{ucol_strcoll} == UCOL_GREATER |
| * @param coll The UCollator containing the comparison rules. |
| * @param source The source string. |
| * @param sourceLength The length of source, or -1 if null-terminated. |
| * @param target The target string. |
| * @param targetLength The length of target, or -1 if null-terminated. |
| * @return TRUE if source is greater than target, FALSE otherwise. |
| * @see ucol_strcoll |
| * @see ucol_greaterOrEqual |
| * @see ucol_equal |
| * @stable |
| */ |
| U_CAPI UBool U_EXPORT2 |
| ucol_greater(const UCollator *coll, |
| const UChar *source, int32_t sourceLength, |
| const UChar *target, int32_t targetLength); |
| |
| /** |
| * Determine if one string is greater than or equal to another. |
| * This function is equivalent to \Ref{ucol_strcoll} != UCOL_LESS |
| * @param coll The UCollator containing the comparison rules. |
| * @param source The source string. |
| * @param sourceLength The length of source, or -1 if null-terminated. |
| * @param target The target string. |
| * @param targetLength The length of target, or -1 if null-terminated. |
| * @return TRUE if source is greater than or equal to target, FALSE otherwise. |
| * @see ucol_strcoll |
| * @see ucol_greater |
| * @see ucol_equal |
| * @stable |
| */ |
| U_CAPI UBool U_EXPORT2 |
| ucol_greaterOrEqual(const UCollator *coll, |
| const UChar *source, int32_t sourceLength, |
| const UChar *target, int32_t targetLength); |
| |
| /** |
| * Compare two strings for equality. |
| * This function is equivalent to \Ref{ucol_strcoll} == UCOL_EQUAL |
| * @param coll The UCollator containing the comparison rules. |
| * @param source The source string. |
| * @param sourceLength The length of source, or -1 if null-terminated. |
| * @param target The target string. |
| * @param targetLength The length of target, or -1 if null-terminated. |
| * @return TRUE if source is equal to target, FALSE otherwise |
| * @see ucol_strcoll |
| * @see ucol_greater |
| * @see ucol_greaterOrEqual |
| * @stable |
| */ |
| U_CAPI UBool U_EXPORT2 |
| ucol_equal(const UCollator *coll, |
| const UChar *source, int32_t sourceLength, |
| const UChar *target, int32_t targetLength); |
| |
| /** |
| * Get the collation strength used in a UCollator. |
| * The strength influences how strings are compared. |
| * @param coll The UCollator to query. |
| * @return The collation strength; one of UCOL_PRIMARY, UCOL_SECONDARY, |
| * UCOL_TERTIARY, UCOL_QUATERNARY, UCOL_IDENTICAL |
| * @see ucol_setStrength |
| * @stable |
| */ |
| U_CAPI UCollationStrength U_EXPORT2 |
| ucol_getStrength(const UCollator *coll); |
| |
| /** |
| * Set the collation strength used in a UCollator. |
| * The strength influences how strings are compared. |
| * @param coll The UCollator to set. |
| * @param strength The desired collation strength; one of UCOL_PRIMARY, |
| * UCOL_SECONDARY, UCOL_TERTIARY, UCOL_QUATERNARY, UCOL_IDENTICAL, UCOL_DEFAULT |
| * @see ucol_getStrength |
| * @stable |
| */ |
| U_CAPI void U_EXPORT2 |
| ucol_setStrength(UCollator *coll, |
| UCollationStrength strength); |
| |
| /** |
| * Get the display name for a UCollator. |
| * The display name is suitable for presentation to a user. |
| * @param objLoc The locale of the collator in question. |
| * @param dispLoc The locale for display. |
| * @param result A pointer to a buffer to receive the attribute. |
| * @param resultLength The maximum size of result. |
| * @param status A pointer to an UErrorCode to receive any errors |
| * @return The total buffer size needed; if greater than resultLength, |
| * the output was truncated. |
| * @stable |
| */ |
| U_CAPI int32_t U_EXPORT2 |
| ucol_getDisplayName( const char *objLoc, |
| const char *dispLoc, |
| UChar *result, |
| int32_t resultLength, |
| UErrorCode *status); |
| |
| /** |
| * Get a locale for which collation rules are available. |
| * A UCollator in a locale returned by this function will perform the correct |
| * collation for the locale. |
| * @param index The index of the desired locale. |
| * @return A locale for which collation rules are available, or 0 if none. |
| * @see ucol_countAvailable |
| * @stable |
| */ |
| U_CAPI const char* U_EXPORT2 |
| ucol_getAvailable(int32_t index); |
| |
| /** |
| * Determine how many locales have collation rules available. |
| * This function is most useful as determining the loop ending condition for |
| * calls to \Ref{ucol_getAvailable}. |
| * @return The number of locales for which collation rules are available. |
| * @see ucol_getAvailable |
| * @stable |
| */ |
| U_CAPI int32_t U_EXPORT2 |
| ucol_countAvailable(void); |
| |
| /** |
| * Get the collation rules from a UCollator. |
| * The rules will follow the rule syntax. |
| * @param coll The UCollator to query. |
| * @param length |
| * @return The collation rules. |
| * @stable |
| */ |
| U_CAPI const UChar* U_EXPORT2 |
| ucol_getRules( const UCollator *coll, |
| int32_t *length); |
| |
| /** |
| * Get a sort key for a string from a UCollator. |
| * Sort keys may be compared using <TT>strcmp</TT>. |
| * @param coll The UCollator containing the collation rules. |
| * @param source The string to transform. |
| * @param sourecLength The length of source, or -1 if null-terminated. |
| * @param result A pointer to a buffer to receive the attribute. |
| * @param resultLength The maximum size of result. |
| * @return The size needed to fully store the sort key.. |
| * @see ucol_keyHashCode |
| * @stable |
| */ |
| U_CAPI int32_t U_EXPORT2 |
| ucol_getSortKey(const UCollator *coll, |
| const UChar *source, |
| int32_t sourceLength, |
| uint8_t *result, |
| int32_t resultLength); |
| |
| |
| |
| /** |
| * Gets the version information for a Collator. |
| * @param info the version # information, the result will be filled in |
| * @stable |
| */ |
| U_CAPI void U_EXPORT2 |
| ucol_getVersion(const UCollator* coll, UVersionInfo info); |
| |
| |
| /** |
| * Merge two sort keys. The levels are merged with their corresponding counterparts |
| * (primaries with primaries, secondaries with secondaries etc.). Between the values |
| * from the same level a separator is inserted. |
| * example (uncompressed): |
| * 191B1D 01 050505 01 910505 00 and 1F2123 01 050505 01 910505 00 |
| * will be merged as |
| * 191B1D 02 1F212301 050505 02 050505 01 910505 02 910505 00 |
| * This allows for concatenating of first and last names for sorting, among other things. |
| * If the destination buffer is not big enough, the results are undefined. |
| * @param src1 pointer to the first sortkey |
| * @param src1Length length of the first sortkey |
| * @param src2 pointer to the second sortkey |
| * @param src2Length length of the second sortkey |
| * @param dest buffer to hold the result |
| * @param destCapacity size of the buffer for the result |
| * @return size of the result. If the buffer is big enough size is always |
| * src1Length+src2Length-1 |
| * @draft ICU 2.0 |
| */ |
| U_CAPI int32_t U_EXPORT2 |
| ucol_mergeSortkeys(const uint8_t *src1, int32_t src1Length, |
| const uint8_t *src2, int32_t src2Length, |
| uint8_t *dest, int32_t destCapacity); |
| |
| /** |
| * Universal attribute setter |
| * @param coll collator which attributes are to be changed |
| * @param attr attribute type |
| * @param value attribute value |
| * @param status to indicate whether the operation went on smoothly or there were errors |
| * @see UColAttribute |
| * @see UColAttributeValue |
| * @see ucol_getAttribute |
| * @draft ICU 1.8 |
| */ |
| U_CAPI void U_EXPORT2 |
| ucol_setAttribute(UCollator *coll, UColAttribute attr, UColAttributeValue value, UErrorCode *status); |
| |
| /** |
| * Universal attribute getter |
| * @param coll collator which attributes are to be changed |
| * @param attr attribute type |
| * @return attribute value |
| * @param status to indicate whether the operation went on smoothly or there were errors |
| * @see UColAttribute |
| * @see UColAttributeValue |
| * @see ucol_setAttribute |
| * @draft ICU 1.8 |
| */ |
| U_CAPI UColAttributeValue U_EXPORT2 |
| ucol_getAttribute(const UCollator *coll, UColAttribute attr, UErrorCode *status); |
| |
| /** Variable top |
| * is a two byte primary value which causes all the codepoints with primary values that |
| * are less or equal than the variable top to be shifted when alternate handling is set |
| * to UCOL_SHIFTED. |
| * Sets the variable top to a collation element value of a string supplied. |
| * @param coll collator which variable top needs to be changed |
| * @param varTop one or more (if contraction) UChars to which the variable top should be set |
| * @param len length of variable top string. If -1 it is considered to be zero terminated. |
| * @param status error code. If error code is set, the return value is undefined. |
| * Errors set by this function are: <br> |
| * U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no such |
| * a contraction<br> |
| * U_PRIMARY_TOO_LONG_ERROR if the primary for the variable top has more than two bytes |
| * @return a 32 bit value containing the value of the variable top in upper 16 bits. |
| * Lower 16 bits are undefined |
| * @see ucol_getVariableTop |
| * @see ucol_restoreVariableTop |
| * @draft ICU 2.0 |
| */ |
| U_CAPI uint32_t U_EXPORT2 |
| ucol_setVariableTop(UCollator *coll, |
| const UChar *varTop, int32_t len, |
| UErrorCode *status); |
| |
| /** |
| * Gets the variable top value of a Collator. |
| * Lower 16 bits are undefined and should be ignored. |
| * @param coll collator which variable top needs to be retrieved |
| * @param status error code (not changed by function). If error code is set, |
| * the return value is undefined. |
| * @see ucol_setVariableTop |
| * @see ucol_restoreVariableTop |
| * @draft ICU 2.0 |
| */ |
| U_CAPI uint32_t ucol_getVariableTop(const UCollator *coll, UErrorCode *status); |
| |
| /** |
| * Sets the variable top to a collation element value supplied. Variable top is |
| * set to the upper 16 bits. |
| * Lower 16 bits are ignored. |
| * @param coll collator which variable top needs to be changed |
| * @param varTop CE value, as returned by ucol_setVariableTop or ucol)getVariableTop |
| * @param status error code (not changed by function) |
| * @see ucol_getVariableTop |
| * @see ucol_setVariableTop |
| * @draft ICU 2.0 |
| */ |
| U_CAPI void U_EXPORT2 |
| ucol_restoreVariableTop(UCollator *coll, const uint32_t varTop, UErrorCode *status); |
| |
| /** |
| * Thread safe cloning operation. The result is a clone of a given collator. |
| * @param coll collator to be cloned |
| * @param stackBuffer user allocated space for the new clone. |
| * If NULL new memory will be allocated. |
| * If buffer is not large enough, new memory will be allocated. |
| * Clients can use the U_COL_SAFECLONE_BUFFERSIZE. |
| * This will probably be enough to avoid memory allocations. |
| * @param pBufferSize pointer to size of allocated space. |
| * If *pBufferSize == 0, a sufficient size for use in cloning will |
| * be returned ('pre-flighting') |
| * If *pBufferSize is not enough for a stack-based safe clone, |
| * new memory will be allocated. |
| * @param status to indicate whether the operation went on smoothly or there were errors |
| * An informational status value, U_SAFECLONE_ALLOCATED_ERROR, is used if any |
| * allocations were necessary. |
| * @return pointer to the new clone |
| * @see ucol_open |
| * @see ucol_openRules |
| * @see ucol_close |
| * @draft ICU 1.8 |
| */ |
| U_CAPI UCollator* U_EXPORT2 |
| ucol_safeClone(const UCollator *coll, |
| void *stackBuffer, |
| int32_t *pBufferSize, |
| UErrorCode *status); |
| |
| /** default memory size for the new clone */ |
| #define U_COL_SAFECLONE_BUFFERSIZE 384 |
| |
| /** |
| * Returns current rules. Delta defines whether full rules are returned or just the tailoring. |
| * Returns number of UChars needed to store rules. If buffer is NULL or bufferLen is not enough |
| * to store rules, will store up to available space. |
| * @param coll collator to get the rules from |
| * @param delta one of UCOL_TAILORING_ONLY, UCOL_FULL_RULES. |
| * @param buffer buffer to store the result in. If NULL, you'll get no rules. |
| * @param bufferLen lenght of buffer to store rules in. If less then needed you'll get only the part that fits in. |
| * @draft ICU 1.8 |
| */ |
| U_CAPI int32_t U_EXPORT2 |
| ucol_getRulesEx(const UCollator *coll, UColRuleOption delta, UChar *buffer, int32_t bufferLen); |
| |
| |
| /********************************* Deprecated API ********************************/ |
| /* This is the C API wrapper for CollationIterator that got booted out from here, including just for */ |
| /* include backward compatibility */ |
| /* @deprecated remove after nov-2002 */ |
| #include "unicode/ucoleitr.h" |
| |
| /** |
| * Open a UCollator with a specific version. |
| * This is the same as ucol_open() except that ucol_getVersion() of |
| * the returned object is guaranteed to be the same as the version |
| * parameter. |
| * This is designed to be used to open the same collator for a given |
| * locale even when ICU is updated. |
| * The same locale and version guarantees the same sort keys and |
| * comparison results. |
| * |
| * @param loc The locale ID for which to open a collator. |
| * @param version The requested collator version. |
| * @param status A pointer to a UErrorCode, |
| * must not indicate a failure before calling this function. |
| * @return A pointer to a UCollator, or NULL if an error occurred |
| * or a collator with the requested version is not available. |
| * |
| * @see ucol_open |
| * @see ucol_getVersion |
| * @deprecated to be removed by nov-2002. Use support for running multiple versions of ICU |
| */ |
| U_CAPI UCollator * U_EXPORT2 |
| ucol_openVersion(const char *loc, |
| UVersionInfo version, |
| UErrorCode *status); |
| |
| /** |
| * Get the normalization mode used in a UCollator. |
| * The normalization mode influences how strings are compared. |
| * @param coll The UCollator to query. |
| * @return The normalization mode, UNORM_NONE or UNORM_NFD. |
| * @see ucol_setNormalization |
| * @deprecated To be removed after 2002-sep-30; use ucol_getAttribute(). |
| */ |
| U_CAPI UNormalizationMode U_EXPORT2 |
| ucol_getNormalization(const UCollator* coll); |
| |
| /** |
| * Set the normalization mode used in a UCollator. |
| * The normalization mode influences how strings are compared. |
| * @param coll The UCollator to set. |
| * @param mode The desired normalization mode: One of |
| * UNORM_NONE (expect the text to not need normalization), |
| * UNORM_NFD (normalize) |
| * @see ucol_getNormalization |
| * @deprecated To be removed after 2002-sep-30; use ucol_setAttribute(). |
| */ |
| U_CAPI void U_EXPORT2 |
| ucol_setNormalization( UCollator *coll, |
| UNormalizationMode mode); |
| |
| /** |
| *@deprecated Remove after Aug 2002 |
| */ |
| #ifdef U_USE_DEPRECATED_FORMAT_API |
| |
| #if ((U_ICU_VERSION_MAJOR_NUM != 2) || (U_ICU_VERSION_MINOR_NUM !=0)) |
| # error "ICU version has changed. Please redefine the macros under U_USE_DEPRECATED_FORMAT_API pre-processor definition" |
| #else |
| # define ucol_openRules_2_0(rules,rulesLength,normalizationMode,strength,status) ucol_openRules(rules,rulesLength,(UColAttributeValue)normalizationMode,strength,NULL,status) |
| #endif |
| |
| #endif |
| /********************************* End *******************************************/ |
| |
| #endif |