michael@0: * For more information about the collation service see michael@0: * the users guide. michael@0: *
michael@0: * Collation service provides correct sorting orders for most locales supported in ICU. michael@0: * If specific data for a locale is not available, the orders eventually falls back michael@0: * to the UCA sort order. michael@0: *
michael@0: * Sort ordering may be customized by providing your own set of rules. For more on michael@0: * this subject see the michael@0: * michael@0: * Collation customization section of the users guide. michael@0: *
michael@0: * @see UCollationResult michael@0: * @see UNormalizationMode michael@0: * @see UCollationStrength michael@0: * @see UCollationElements michael@0: */ michael@0: michael@0: /** A collator. michael@0: * For usage in C programs. michael@0: */ michael@0: struct UCollator; michael@0: /** structure representing a collator object instance michael@0: * @stable ICU 2.0 michael@0: */ michael@0: typedef struct UCollator UCollator; michael@0: michael@0: michael@0: /** michael@0: * UCOL_LESS is returned if source string is compared to be less than target michael@0: * string in the ucol_strcoll() method. michael@0: * UCOL_EQUAL is returned if source string is compared to be equal to target michael@0: * string in the ucol_strcoll() method. michael@0: * UCOL_GREATER is returned if source string is compared to be greater than michael@0: * target string in the ucol_strcoll() method. michael@0: * @see ucol_strcoll() michael@0: *
michael@0: * Possible values for a comparison result michael@0: * @stable ICU 2.0 michael@0: */ michael@0: typedef enum { michael@0: /** string a == string b */ michael@0: UCOL_EQUAL = 0, michael@0: /** string a > string b */ michael@0: UCOL_GREATER = 1, michael@0: /** string a < string b */ michael@0: UCOL_LESS = -1 michael@0: } UCollationResult ; michael@0: michael@0: michael@0: /** Enum containing attribute values for controling collation behavior. michael@0: * Here are all the allowable values. Not every attribute can take every value. The only michael@0: * universal value is UCOL_DEFAULT, which resets the attribute value to the predefined michael@0: * value for that locale michael@0: * @stable ICU 2.0 michael@0: */ michael@0: typedef enum { michael@0: /** accepted by most attributes */ michael@0: UCOL_DEFAULT = -1, michael@0: michael@0: /** Primary collation strength */ michael@0: UCOL_PRIMARY = 0, michael@0: /** Secondary collation strength */ michael@0: UCOL_SECONDARY = 1, michael@0: /** Tertiary collation strength */ michael@0: UCOL_TERTIARY = 2, michael@0: /** Default collation strength */ michael@0: UCOL_DEFAULT_STRENGTH = UCOL_TERTIARY, michael@0: UCOL_CE_STRENGTH_LIMIT, michael@0: /** Quaternary collation strength */ michael@0: UCOL_QUATERNARY=3, michael@0: /** Identical collation strength */ michael@0: UCOL_IDENTICAL=15, michael@0: UCOL_STRENGTH_LIMIT, michael@0: michael@0: /** Turn the feature off - works for UCOL_FRENCH_COLLATION, michael@0: UCOL_CASE_LEVEL, UCOL_HIRAGANA_QUATERNARY_MODE michael@0: & UCOL_DECOMPOSITION_MODE*/ michael@0: UCOL_OFF = 16, michael@0: /** Turn the feature on - works for UCOL_FRENCH_COLLATION, michael@0: UCOL_CASE_LEVEL, UCOL_HIRAGANA_QUATERNARY_MODE michael@0: & UCOL_DECOMPOSITION_MODE*/ michael@0: UCOL_ON = 17, michael@0: michael@0: /** Valid for UCOL_ALTERNATE_HANDLING. Alternate handling will be shifted */ michael@0: UCOL_SHIFTED = 20, michael@0: /** Valid for UCOL_ALTERNATE_HANDLING. Alternate handling will be non ignorable */ michael@0: UCOL_NON_IGNORABLE = 21, michael@0: michael@0: /** Valid for UCOL_CASE_FIRST - michael@0: lower case sorts before upper case */ michael@0: UCOL_LOWER_FIRST = 24, michael@0: /** upper case sorts before lower case */ michael@0: UCOL_UPPER_FIRST = 25, michael@0: michael@0: UCOL_ATTRIBUTE_VALUE_COUNT michael@0: michael@0: } UColAttributeValue; michael@0: michael@0: /** michael@0: * Enum containing the codes for reordering segments of the collation table that are not script michael@0: * codes. These reordering codes are to be used in conjunction with the script codes. michael@0: * @see ucol_getReorderCodes michael@0: * @see ucol_setReorderCodes michael@0: * @see ucol_getEquivalentReorderCodes michael@0: * @see UScriptCode michael@0: * @stable ICU 4.8 michael@0: */ michael@0: typedef enum { michael@0: /** michael@0: * A special reordering code that is used to specify the default michael@0: * reordering codes for a locale. michael@0: * @stable ICU 4.8 michael@0: */ michael@0: UCOL_REORDER_CODE_DEFAULT = -1, michael@0: /** michael@0: * A special reordering code that is used to specify no reordering codes. michael@0: * @stable ICU 4.8 michael@0: */ michael@0: UCOL_REORDER_CODE_NONE = USCRIPT_UNKNOWN, michael@0: /** michael@0: * A special reordering code that is used to specify all other codes used for michael@0: * reordering except for the codes lised as UColReorderCode values and those michael@0: * listed explicitly in a reordering. michael@0: * @stable ICU 4.8 michael@0: */ michael@0: UCOL_REORDER_CODE_OTHERS = USCRIPT_UNKNOWN, michael@0: /** michael@0: * Characters with the space property. michael@0: * This is equivalent to the rule value "space". michael@0: * @stable ICU 4.8 michael@0: */ michael@0: UCOL_REORDER_CODE_SPACE = 0x1000, michael@0: /** michael@0: * The first entry in the enumeration of reordering groups. This is intended for use in michael@0: * range checking and enumeration of the reorder codes. michael@0: * @stable ICU 4.8 michael@0: */ michael@0: UCOL_REORDER_CODE_FIRST = UCOL_REORDER_CODE_SPACE, michael@0: /** michael@0: * Characters with the punctuation property. michael@0: * This is equivalent to the rule value "punct". michael@0: * @stable ICU 4.8 michael@0: */ michael@0: UCOL_REORDER_CODE_PUNCTUATION = 0x1001, michael@0: /** michael@0: * Characters with the symbol property. michael@0: * This is equivalent to the rule value "symbol". michael@0: * @stable ICU 4.8 michael@0: */ michael@0: UCOL_REORDER_CODE_SYMBOL = 0x1002, michael@0: /** michael@0: * Characters with the currency property. michael@0: * This is equivalent to the rule value "currency". michael@0: * @stable ICU 4.8 michael@0: */ michael@0: UCOL_REORDER_CODE_CURRENCY = 0x1003, michael@0: /** michael@0: * Characters with the digit property. michael@0: * This is equivalent to the rule value "digit". michael@0: * @stable ICU 4.8 michael@0: */ michael@0: UCOL_REORDER_CODE_DIGIT = 0x1004, michael@0: /** michael@0: * The limit of the reorder codes. This is intended for use in range checking michael@0: * and enumeration of the reorder codes. michael@0: * @stable ICU 4.8 michael@0: */ michael@0: UCOL_REORDER_CODE_LIMIT = 0x1005 michael@0: } UColReorderCode; michael@0: michael@0: /** michael@0: * Base letter represents a primary difference. Set comparison michael@0: * level to UCOL_PRIMARY to ignore secondary and tertiary differences. michael@0: * Use this to set the strength of a Collator object. michael@0: * Example of primary difference, "abc" < "abd" michael@0: * michael@0: * Diacritical differences on the same base letter represent a secondary michael@0: * difference. Set comparison level to UCOL_SECONDARY to ignore tertiary michael@0: * differences. Use this to set the strength of a Collator object. michael@0: * Example of secondary difference, "ä" >> "a". michael@0: * michael@0: * Uppercase and lowercase versions of the same character represents a michael@0: * tertiary difference. Set comparison level to UCOL_TERTIARY to include michael@0: * all comparison differences. Use this to set the strength of a Collator michael@0: * object. michael@0: * Example of tertiary difference, "abc" <<< "ABC". michael@0: * michael@0: * Two characters are considered "identical" when they have the same michael@0: * unicode spellings. UCOL_IDENTICAL. michael@0: * For example, "ä" == "ä". michael@0: * michael@0: * UCollationStrength is also used to determine the strength of sort keys michael@0: * generated from UCollator objects michael@0: * These values can be now found in the UColAttributeValue enum. michael@0: * @stable ICU 2.0 michael@0: **/ michael@0: typedef UColAttributeValue UCollationStrength; michael@0: michael@0: /** Attributes that collation service understands. All the attributes can take UCOL_DEFAULT michael@0: * value, as well as the values specific to each one. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: typedef enum { michael@0: /** Attribute for direction of secondary weights - used in Canadian French. michael@0: * Acceptable values are UCOL_ON, which results in secondary weights michael@0: * being considered backwards and UCOL_OFF which treats secondary michael@0: * weights in the order they appear. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UCOL_FRENCH_COLLATION, michael@0: /** Attribute for handling variable elements. michael@0: * Acceptable values are UCOL_NON_IGNORABLE (default) michael@0: * which treats all the codepoints with non-ignorable michael@0: * primary weights in the same way, michael@0: * and UCOL_SHIFTED which causes codepoints with primary michael@0: * weights that are equal or below the variable top value michael@0: * to be ignored on primary level and moved to the quaternary michael@0: * level. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UCOL_ALTERNATE_HANDLING, michael@0: /** Controls the ordering of upper and lower case letters. michael@0: * Acceptable values are UCOL_OFF (default), which orders michael@0: * upper and lower case letters in accordance to their tertiary michael@0: * weights, UCOL_UPPER_FIRST which forces upper case letters to michael@0: * sort before lower case letters, and UCOL_LOWER_FIRST which does michael@0: * the opposite. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UCOL_CASE_FIRST, michael@0: /** Controls whether an extra case level (positioned before the third michael@0: * level) is generated or not. Acceptable values are UCOL_OFF (default), michael@0: * when case level is not generated, and UCOL_ON which causes the case michael@0: * level to be generated. Contents of the case level are affected by michael@0: * the value of UCOL_CASE_FIRST attribute. A simple way to ignore michael@0: * accent differences in a string is to set the strength to UCOL_PRIMARY michael@0: * and enable case level. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UCOL_CASE_LEVEL, michael@0: /** Controls whether the normalization check and necessary normalizations michael@0: * are performed. When set to UCOL_OFF (default) no normalization check michael@0: * is performed. The correctness of the result is guaranteed only if the michael@0: * input data is in so-called FCD form (see users manual for more info). michael@0: * When set to UCOL_ON, an incremental check is performed to see whether michael@0: * the input data is in the FCD form. If the data is not in the FCD form, michael@0: * incremental NFD normalization is performed. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UCOL_NORMALIZATION_MODE, michael@0: /** An alias for UCOL_NORMALIZATION_MODE attribute. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UCOL_DECOMPOSITION_MODE = UCOL_NORMALIZATION_MODE, michael@0: /** The strength attribute. Can be either UCOL_PRIMARY, UCOL_SECONDARY, michael@0: * UCOL_TERTIARY, UCOL_QUATERNARY or UCOL_IDENTICAL. The usual strength michael@0: * for most locales (except Japanese) is tertiary. Quaternary strength michael@0: * is useful when combined with shifted setting for alternate handling michael@0: * attribute and for JIS x 4061 collation, when it is used to distinguish michael@0: * between Katakana and Hiragana (this is achieved by setting the michael@0: * UCOL_HIRAGANA_QUATERNARY mode to on. Otherwise, quaternary level michael@0: * is affected only by the number of non ignorable code points in michael@0: * the string. Identical strength is rarely useful, as it amounts michael@0: * to codepoints of the NFD form of the string. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UCOL_STRENGTH, michael@0: #ifndef U_HIDE_DEPRECATED_API michael@0: /** When turned on, this attribute positions Hiragana before all michael@0: * non-ignorables on quaternary level This is a sneaky way to produce JIS michael@0: * sort order. michael@0: * michael@0: * This attribute is an implementation detail of the CLDR Japanese tailoring. michael@0: * The implementation might change to use a different mechanism michael@0: * to achieve the same Japanese sort order. michael@0: * Since ICU 50, this attribute is not settable any more via API functions. michael@0: * @deprecated ICU 50 Implementation detail, cannot be set via API, might be removed from implementation. michael@0: */ michael@0: UCOL_HIRAGANA_QUATERNARY_MODE = UCOL_STRENGTH + 1, michael@0: #endif /* U_HIDE_DEPRECATED_API */ michael@0: /** When turned on, this attribute generates a collation key michael@0: * for the numeric value of substrings of digits. michael@0: * This is a way to get '100' to sort AFTER '2'. Note that the longest michael@0: * digit substring that can be treated as a single collation element is michael@0: * 254 digits (not counting leading zeros). If a digit substring is michael@0: * longer than that, the digits beyond the limit will be treated as a michael@0: * separate digit substring associated with a separate collation element. michael@0: * @stable ICU 2.8 michael@0: */ michael@0: UCOL_NUMERIC_COLLATION = UCOL_STRENGTH + 2, michael@0: /** michael@0: * The number of UColAttribute constants. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UCOL_ATTRIBUTE_COUNT michael@0: } UColAttribute; michael@0: michael@0: /** Options for retrieving the rule string michael@0: * @stable ICU 2.0 michael@0: */ michael@0: typedef enum { michael@0: /** michael@0: * Retrieves the tailoring rules only. michael@0: * Same as calling the version of getRules() without UColRuleOption. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UCOL_TAILORING_ONLY, michael@0: /** michael@0: * Retrieves the "UCA rules" concatenated with the tailoring rules. michael@0: * The "UCA rules" are an approximation of the root collator's sort order. michael@0: * They are almost never used or useful at runtime and can be removed from the data. michael@0: * See http://userguide.icu-project.org/collation/customization#TOC-Building-on-Existing-Locales michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UCOL_FULL_RULES michael@0: } UColRuleOption ; michael@0: michael@0: /** michael@0: * Open a UCollator for comparing strings. michael@0: * The UCollator pointer is used in all the calls to the Collation michael@0: * service. After finished, collator must be disposed of by calling michael@0: * {@link #ucol_close }. michael@0: * @param loc The locale containing the required collation rules. michael@0: * Special values for locales can be passed in - michael@0: * if NULL is passed for the locale, the default locale michael@0: * collation rules will be used. If empty string ("") or michael@0: * "root" are passed, UCA rules will be used. michael@0: * @param status A pointer to an UErrorCode to receive any errors michael@0: * @return A pointer to a UCollator, or 0 if an error occurred. michael@0: * @see ucol_openRules michael@0: * @see ucol_safeClone michael@0: * @see ucol_close michael@0: * @stable ICU 2.0 michael@0: */ michael@0: U_STABLE UCollator* U_EXPORT2 michael@0: ucol_open(const char *loc, UErrorCode *status); michael@0: michael@0: /** michael@0: * Produce an UCollator instance according to the rules supplied. michael@0: * The rules are used to change the default ordering, defined in the michael@0: * UCA in a process called tailoring. The resulting UCollator pointer michael@0: * can be used in the same way as the one obtained by {@link #ucol_strcoll }. michael@0: * @param rules A string describing the collation rules. For the syntax michael@0: * of the rules please see users guide. michael@0: * @param rulesLength The length of rules, or -1 if null-terminated. michael@0: * @param normalizationMode The normalization mode: One of michael@0: * UCOL_OFF (expect the text to not need normalization), michael@0: * UCOL_ON (normalize), or michael@0: * UCOL_DEFAULT (set the mode according to the rules) michael@0: * @param strength The default collation strength; one of UCOL_PRIMARY, UCOL_SECONDARY, michael@0: * UCOL_TERTIARY, UCOL_IDENTICAL,UCOL_DEFAULT_STRENGTH - can be also set in the rules. michael@0: * @param parseError A pointer to UParseError to recieve information about errors michael@0: * occurred during parsing. This argument can currently be set michael@0: * to NULL, but at users own risk. Please provide a real structure. michael@0: * @param status A pointer to an UErrorCode to receive any errors michael@0: * @return A pointer to a UCollator. It is not guaranteed that NULL be returned in case michael@0: * of error - please use status argument to check for errors. michael@0: * @see ucol_open michael@0: * @see ucol_safeClone michael@0: * @see ucol_close michael@0: * @stable ICU 2.0 michael@0: */ michael@0: U_STABLE UCollator* U_EXPORT2 michael@0: ucol_openRules( const UChar *rules, michael@0: int32_t rulesLength, michael@0: UColAttributeValue normalizationMode, michael@0: UCollationStrength strength, michael@0: UParseError *parseError, michael@0: UErrorCode *status); michael@0: michael@0: /** michael@0: * Open a collator defined by a short form string. michael@0: * The structure and the syntax of the string is defined in the "Naming collators" michael@0: * section of the users guide: michael@0: * http://icu-project.org/userguide/Collate_Concepts.html#Naming_Collators michael@0: * Attributes are overriden by the subsequent attributes. So, for "S2_S3", final michael@0: * strength will be 3. 3066bis locale overrides individual locale parts. michael@0: * The call to this function is equivalent to a call to ucol_open, followed by a michael@0: * series of calls to ucol_setAttribute and ucol_setVariableTop. michael@0: * @param definition A short string containing a locale and a set of attributes. michael@0: * Attributes not explicitly mentioned are left at the default michael@0: * state for a locale. michael@0: * @param parseError if not NULL, structure that will get filled with error's pre michael@0: * and post context in case of error. michael@0: * @param forceDefaults if FALSE, the settings that are the same as the collator michael@0: * default settings will not be applied (for example, setting michael@0: * French secondary on a French collator would not be executed). michael@0: * If TRUE, all the settings will be applied regardless of the michael@0: * collator default value. If the definition michael@0: * strings are to be cached, should be set to FALSE. michael@0: * @param status Error code. Apart from regular error conditions connected to michael@0: * instantiating collators (like out of memory or similar), this michael@0: * API will return an error if an invalid attribute or attribute/value michael@0: * combination is specified. michael@0: * @return A pointer to a UCollator or 0 if an error occured (including an michael@0: * invalid attribute). michael@0: * @see ucol_open michael@0: * @see ucol_setAttribute michael@0: * @see ucol_setVariableTop michael@0: * @see ucol_getShortDefinitionString michael@0: * @see ucol_normalizeShortDefinitionString michael@0: * @stable ICU 3.0 michael@0: * michael@0: */ michael@0: U_STABLE UCollator* U_EXPORT2 michael@0: ucol_openFromShortString( const char *definition, michael@0: UBool forceDefaults, michael@0: UParseError *parseError, michael@0: UErrorCode *status); michael@0: michael@0: #ifndef U_HIDE_DEPRECATED_API michael@0: /** michael@0: * Get a set containing the contractions defined by the collator. The set includes michael@0: * both the UCA contractions and the contractions defined by the collator. This set michael@0: * will contain only strings. If a tailoring explicitly suppresses contractions from michael@0: * the UCA (like Russian), removed contractions will not be in the resulting set. michael@0: * @param coll collator michael@0: * @param conts the set to hold the result. It gets emptied before michael@0: * contractions are added. michael@0: * @param status to hold the error code michael@0: * @return the size of the contraction set michael@0: * michael@0: * @deprecated ICU 3.4, use ucol_getContractionsAndExpansions instead michael@0: */ michael@0: U_DEPRECATED int32_t U_EXPORT2 michael@0: ucol_getContractions( const UCollator *coll, michael@0: USet *conts, michael@0: UErrorCode *status); michael@0: #endif /* U_HIDE_DEPRECATED_API */ michael@0: michael@0: /** michael@0: * Get a set containing the expansions defined by the collator. The set includes michael@0: * both the UCA expansions and the expansions defined by the tailoring michael@0: * @param coll collator michael@0: * @param contractions if not NULL, the set to hold the contractions michael@0: * @param expansions if not NULL, the set to hold the expansions michael@0: * @param addPrefixes add the prefix contextual elements to contractions michael@0: * @param status to hold the error code michael@0: * michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE void U_EXPORT2 michael@0: ucol_getContractionsAndExpansions( const UCollator *coll, michael@0: USet *contractions, USet *expansions, michael@0: UBool addPrefixes, UErrorCode *status); michael@0: michael@0: /** michael@0: * Close a UCollator. michael@0: * Once closed, a UCollator should not be used. Every open collator should michael@0: * be closed. Otherwise, a memory leak will result. michael@0: * @param coll The UCollator to close. michael@0: * @see ucol_open michael@0: * @see ucol_openRules michael@0: * @see ucol_safeClone michael@0: * @stable ICU 2.0 michael@0: */ michael@0: U_STABLE void U_EXPORT2 michael@0: ucol_close(UCollator *coll); michael@0: michael@0: #if U_SHOW_CPLUSPLUS_API michael@0: michael@0: U_NAMESPACE_BEGIN michael@0: michael@0: /** michael@0: * \class LocalUCollatorPointer michael@0: * "Smart pointer" class, closes a UCollator via ucol_close(). michael@0: * For most methods see the LocalPointerBase base class. michael@0: * michael@0: * @see LocalPointerBase michael@0: * @see LocalPointer michael@0: * @stable ICU 4.4 michael@0: */ michael@0: U_DEFINE_LOCAL_OPEN_POINTER(LocalUCollatorPointer, UCollator, ucol_close); michael@0: michael@0: U_NAMESPACE_END michael@0: michael@0: #endif michael@0: michael@0: /** michael@0: * Compare two strings. michael@0: * The strings will be compared using the options already specified. michael@0: * @param coll The UCollator containing the comparison rules. michael@0: * @param source The source string. michael@0: * @param sourceLength The length of source, or -1 if null-terminated. michael@0: * @param target The target string. michael@0: * @param targetLength The length of target, or -1 if null-terminated. michael@0: * @return The result of comparing the strings; one of UCOL_EQUAL, michael@0: * UCOL_GREATER, UCOL_LESS michael@0: * @see ucol_greater michael@0: * @see ucol_greaterOrEqual michael@0: * @see ucol_equal michael@0: * @stable ICU 2.0 michael@0: */ michael@0: U_STABLE UCollationResult U_EXPORT2 michael@0: ucol_strcoll( const UCollator *coll, michael@0: const UChar *source, michael@0: int32_t sourceLength, michael@0: const UChar *target, michael@0: int32_t targetLength); michael@0: michael@0: /** michael@0: * Compare two strings in UTF-8. michael@0: * The strings will be compared using the options already specified. michael@0: * Note: When input string contains malformed a UTF-8 byte sequence, michael@0: * this function treats these bytes as REPLACEMENT CHARACTER (U+FFFD). michael@0: * @param coll The UCollator containing the comparison rules. michael@0: * @param source The source UTF-8 string. michael@0: * @param sourceLength The length of source, or -1 if null-terminated. michael@0: * @param target The target UTF-8 string. michael@0: * @param targetLength The length of target, or -1 if null-terminated. michael@0: * @param status A pointer to an UErrorCode to receive any errors michael@0: * @return The result of comparing the strings; one of UCOL_EQUAL, michael@0: * UCOL_GREATER, UCOL_LESS michael@0: * @see ucol_greater michael@0: * @see ucol_greaterOrEqual michael@0: * @see ucol_equal michael@0: * @stable ICU 50 michael@0: */ michael@0: U_STABLE UCollationResult U_EXPORT2 michael@0: ucol_strcollUTF8( michael@0: const UCollator *coll, michael@0: const char *source, michael@0: int32_t sourceLength, michael@0: const char *target, michael@0: int32_t targetLength, michael@0: UErrorCode *status); michael@0: michael@0: /** michael@0: * Determine if one string is greater than another. michael@0: * This function is equivalent to {@link #ucol_strcoll } == UCOL_GREATER michael@0: * @param coll The UCollator containing the comparison rules. michael@0: * @param source The source string. michael@0: * @param sourceLength The length of source, or -1 if null-terminated. michael@0: * @param target The target string. michael@0: * @param targetLength The length of target, or -1 if null-terminated. michael@0: * @return TRUE if source is greater than target, FALSE otherwise. michael@0: * @see ucol_strcoll michael@0: * @see ucol_greaterOrEqual michael@0: * @see ucol_equal michael@0: * @stable ICU 2.0 michael@0: */ michael@0: U_STABLE UBool U_EXPORT2 michael@0: ucol_greater(const UCollator *coll, michael@0: const UChar *source, int32_t sourceLength, michael@0: const UChar *target, int32_t targetLength); michael@0: michael@0: /** michael@0: * Determine if one string is greater than or equal to another. michael@0: * This function is equivalent to {@link #ucol_strcoll } != UCOL_LESS michael@0: * @param coll The UCollator containing the comparison rules. michael@0: * @param source The source string. michael@0: * @param sourceLength The length of source, or -1 if null-terminated. michael@0: * @param target The target string. michael@0: * @param targetLength The length of target, or -1 if null-terminated. michael@0: * @return TRUE if source is greater than or equal to target, FALSE otherwise. michael@0: * @see ucol_strcoll michael@0: * @see ucol_greater michael@0: * @see ucol_equal michael@0: * @stable ICU 2.0 michael@0: */ michael@0: U_STABLE UBool U_EXPORT2 michael@0: ucol_greaterOrEqual(const UCollator *coll, michael@0: const UChar *source, int32_t sourceLength, michael@0: const UChar *target, int32_t targetLength); michael@0: michael@0: /** michael@0: * Compare two strings for equality. michael@0: * This function is equivalent to {@link #ucol_strcoll } == UCOL_EQUAL michael@0: * @param coll The UCollator containing the comparison rules. michael@0: * @param source The source string. michael@0: * @param sourceLength The length of source, or -1 if null-terminated. michael@0: * @param target The target string. michael@0: * @param targetLength The length of target, or -1 if null-terminated. michael@0: * @return TRUE if source is equal to target, FALSE otherwise michael@0: * @see ucol_strcoll michael@0: * @see ucol_greater michael@0: * @see ucol_greaterOrEqual michael@0: * @stable ICU 2.0 michael@0: */ michael@0: U_STABLE UBool U_EXPORT2 michael@0: ucol_equal(const UCollator *coll, michael@0: const UChar *source, int32_t sourceLength, michael@0: const UChar *target, int32_t targetLength); michael@0: michael@0: /** michael@0: * Compare two UTF-8 encoded trings. michael@0: * The strings will be compared using the options already specified. michael@0: * @param coll The UCollator containing the comparison rules. michael@0: * @param sIter The source string iterator. michael@0: * @param tIter The target string iterator. michael@0: * @return The result of comparing the strings; one of UCOL_EQUAL, michael@0: * UCOL_GREATER, UCOL_LESS michael@0: * @param status A pointer to an UErrorCode to receive any errors michael@0: * @see ucol_strcoll michael@0: * @stable ICU 2.6 michael@0: */ michael@0: U_STABLE UCollationResult U_EXPORT2 michael@0: ucol_strcollIter( const UCollator *coll, michael@0: UCharIterator *sIter, michael@0: UCharIterator *tIter, michael@0: UErrorCode *status); michael@0: michael@0: /** michael@0: * Get the collation strength used in a UCollator. michael@0: * The strength influences how strings are compared. michael@0: * @param coll The UCollator to query. michael@0: * @return The collation strength; one of UCOL_PRIMARY, UCOL_SECONDARY, michael@0: * UCOL_TERTIARY, UCOL_QUATERNARY, UCOL_IDENTICAL michael@0: * @see ucol_setStrength michael@0: * @stable ICU 2.0 michael@0: */ michael@0: U_STABLE UCollationStrength U_EXPORT2 michael@0: ucol_getStrength(const UCollator *coll); michael@0: michael@0: /** michael@0: * Set the collation strength used in a UCollator. michael@0: * The strength influences how strings are compared. michael@0: * @param coll The UCollator to set. michael@0: * @param strength The desired collation strength; one of UCOL_PRIMARY, michael@0: * UCOL_SECONDARY, UCOL_TERTIARY, UCOL_QUATERNARY, UCOL_IDENTICAL, UCOL_DEFAULT michael@0: * @see ucol_getStrength michael@0: * @stable ICU 2.0 michael@0: */ michael@0: U_STABLE void U_EXPORT2 michael@0: ucol_setStrength(UCollator *coll, michael@0: UCollationStrength strength); michael@0: michael@0: /** michael@0: * Retrieves the reordering codes for this collator. michael@0: * These reordering codes are a combination of UScript codes and UColReorderCode entries. michael@0: * @param coll The UCollator to query. michael@0: * @param dest The array to fill with the script ordering. michael@0: * @param destCapacity The length of dest. If it is 0, then dest may be NULL and the function michael@0: * will only return the length of the result without writing any of the result string (pre-flighting). michael@0: * @param pErrorCode Must be a valid pointer to an error code value, which must not indicate a michael@0: * failure before the function call. michael@0: * @return The number of reordering codes written to the dest array. michael@0: * @see ucol_setReorderCodes michael@0: * @see ucol_getEquivalentReorderCodes michael@0: * @see UScriptCode michael@0: * @see UColReorderCode michael@0: * @stable ICU 4.8 michael@0: */ michael@0: U_STABLE int32_t U_EXPORT2 michael@0: ucol_getReorderCodes(const UCollator* coll, michael@0: int32_t* dest, michael@0: int32_t destCapacity, michael@0: UErrorCode *pErrorCode); michael@0: /** michael@0: * Sets the reordering codes for this collator. michael@0: * Collation reordering allows scripts and some other defined blocks of characters michael@0: * to be moved relative to each other as a block. This reordering is done on top of michael@0: * the DUCET/CLDR standard collation order. Reordering can specify groups to be placed michael@0: * at the start and/or the end of the collation order. These groups are specified using michael@0: * UScript codes and UColReorderCode entries. michael@0: *
By default, reordering codes specified for the start of the order are placed in the michael@0: * order given after a group of "special" non-script blocks. These special groups of characters michael@0: * are space, punctuation, symbol, currency, and digit. These special groups are represented with michael@0: * UColReorderCode entries. Script groups can be intermingled with michael@0: * these special non-script blocks if those special blocks are explicitly specified in the reordering. michael@0: *
The special code OTHERS stands for any script that is not explicitly michael@0: * mentioned in the list of reordering codes given. Anything that is after OTHERS michael@0: * will go at the very end of the reordering in the order given. michael@0: *
The special reorder code DEFAULT will reset the reordering for this collator michael@0: * to the default for this collator. The default reordering may be the DUCET/CLDR order or may be a reordering that michael@0: * was specified when this collator was created from resource data or from rules. The michael@0: * DEFAULT code must be the sole code supplied when it used. If not michael@0: * that will result in an U_ILLEGAL_ARGUMENT_ERROR being set. michael@0: *
The special reorder code NONE will remove any reordering for this collator.
michael@0: * The result of setting no reordering will be to have the DUCET/CLDR ordering used. The
michael@0: * NONE code must be the sole code supplied when it used.
michael@0: * @param coll The UCollator to set.
michael@0: * @param reorderCodes An array of script codes in the new order. This can be NULL if the
michael@0: * length is also set to 0. An empty array will clear any reordering codes on the collator.
michael@0: * @param reorderCodesLength The length of reorderCodes.
michael@0: * @param pErrorCode Must be a valid pointer to an error code value, which must not indicate a
michael@0: * failure before the function call.
michael@0: * @see ucol_getReorderCodes
michael@0: * @see ucol_getEquivalentReorderCodes
michael@0: * @see UScriptCode
michael@0: * @see UColReorderCode
michael@0: * @stable ICU 4.8
michael@0: */
michael@0: U_STABLE void U_EXPORT2
michael@0: ucol_setReorderCodes(UCollator* coll,
michael@0: const int32_t* reorderCodes,
michael@0: int32_t reorderCodesLength,
michael@0: UErrorCode *pErrorCode);
michael@0:
michael@0: /**
michael@0: * Retrieves the reorder codes that are grouped with the given reorder code. Some reorder
michael@0: * codes will be grouped and must reorder together.
michael@0: * @param reorderCode The reorder code to determine equivalence for.
michael@0: * @param dest The array to fill with the script ordering.
michael@0: * @param destCapacity The length of dest. If it is 0, then dest may be NULL and the function
michael@0: * will only return the length of the result without writing any of the result string (pre-flighting).
michael@0: * @param pErrorCode Must be a valid pointer to an error code value, which must not indicate
michael@0: * a failure before the function call.
michael@0: * @return The number of reordering codes written to the dest array.
michael@0: * @see ucol_setReorderCodes
michael@0: * @see ucol_getReorderCodes
michael@0: * @see UScriptCode
michael@0: * @see UColReorderCode
michael@0: * @stable ICU 4.8
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ucol_getEquivalentReorderCodes(int32_t reorderCode,
michael@0: int32_t* dest,
michael@0: int32_t destCapacity,
michael@0: UErrorCode *pErrorCode);
michael@0:
michael@0: /**
michael@0: * Get the display name for a UCollator.
michael@0: * The display name is suitable for presentation to a user.
michael@0: * @param objLoc The locale of the collator in question.
michael@0: * @param dispLoc The locale for display.
michael@0: * @param result A pointer to a buffer to receive the attribute.
michael@0: * @param resultLength The maximum size of result.
michael@0: * @param status A pointer to an UErrorCode to receive any errors
michael@0: * @return The total buffer size needed; if greater than resultLength,
michael@0: * the output was truncated.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ucol_getDisplayName( const char *objLoc,
michael@0: const char *dispLoc,
michael@0: UChar *result,
michael@0: int32_t resultLength,
michael@0: UErrorCode *status);
michael@0:
michael@0: /**
michael@0: * Get a locale for which collation rules are available.
michael@0: * A UCollator in a locale returned by this function will perform the correct
michael@0: * collation for the locale.
michael@0: * @param localeIndex The index of the desired locale.
michael@0: * @return A locale for which collation rules are available, or 0 if none.
michael@0: * @see ucol_countAvailable
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE const char* U_EXPORT2
michael@0: ucol_getAvailable(int32_t localeIndex);
michael@0:
michael@0: /**
michael@0: * Determine how many locales have collation rules available.
michael@0: * This function is most useful as determining the loop ending condition for
michael@0: * calls to {@link #ucol_getAvailable }.
michael@0: * @return The number of locales for which collation rules are available.
michael@0: * @see ucol_getAvailable
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ucol_countAvailable(void);
michael@0:
michael@0: #if !UCONFIG_NO_SERVICE
michael@0: /**
michael@0: * Create a string enumerator of all locales for which a valid
michael@0: * collator may be opened.
michael@0: * @param status input-output error code
michael@0: * @return a string enumeration over locale strings. The caller is
michael@0: * responsible for closing the result.
michael@0: * @stable ICU 3.0
michael@0: */
michael@0: U_STABLE UEnumeration* U_EXPORT2
michael@0: ucol_openAvailableLocales(UErrorCode *status);
michael@0: #endif
michael@0:
michael@0: /**
michael@0: * Create a string enumerator of all possible keywords that are relevant to
michael@0: * collation. At this point, the only recognized keyword for this
michael@0: * service is "collation".
michael@0: * @param status input-output error code
michael@0: * @return a string enumeration over locale strings. The caller is
michael@0: * responsible for closing the result.
michael@0: * @stable ICU 3.0
michael@0: */
michael@0: U_STABLE UEnumeration* U_EXPORT2
michael@0: ucol_getKeywords(UErrorCode *status);
michael@0:
michael@0: /**
michael@0: * Given a keyword, create a string enumeration of all values
michael@0: * for that keyword that are currently in use.
michael@0: * @param keyword a particular keyword as enumerated by
michael@0: * ucol_getKeywords. If any other keyword is passed in, *status is set
michael@0: * to U_ILLEGAL_ARGUMENT_ERROR.
michael@0: * @param status input-output error code
michael@0: * @return a string enumeration over collation keyword values, or NULL
michael@0: * upon error. The caller is responsible for closing the result.
michael@0: * @stable ICU 3.0
michael@0: */
michael@0: U_STABLE UEnumeration* U_EXPORT2
michael@0: ucol_getKeywordValues(const char *keyword, UErrorCode *status);
michael@0:
michael@0: /**
michael@0: * Given a key and a locale, returns an array of string values in a preferred
michael@0: * order that would make a difference. These are all and only those values where
michael@0: * the open (creation) of the service with the locale formed from the input locale
michael@0: * plus input keyword and that value has different behavior than creation with the
michael@0: * input locale alone.
michael@0: * @param key one of the keys supported by this service. For now, only
michael@0: * "collation" is supported.
michael@0: * @param locale the locale
michael@0: * @param commonlyUsed if set to true it will return only commonly used values
michael@0: * with the given locale in preferred order. Otherwise,
michael@0: * it will return all the available values for the locale.
michael@0: * @param status error status
michael@0: * @return a string enumeration over keyword values for the given key and the locale.
michael@0: * @stable ICU 4.2
michael@0: */
michael@0: U_STABLE UEnumeration* U_EXPORT2
michael@0: ucol_getKeywordValuesForLocale(const char* key,
michael@0: const char* locale,
michael@0: UBool commonlyUsed,
michael@0: UErrorCode* status);
michael@0:
michael@0: /**
michael@0: * Return the functionally equivalent locale for the given
michael@0: * requested locale, with respect to given keyword, for the
michael@0: * collation service. If two locales return the same result, then
michael@0: * collators instantiated for these locales will behave
michael@0: * equivalently. The converse is not always true; two collators
michael@0: * may in fact be equivalent, but return different results, due to
michael@0: * internal details. The return result has no other meaning than
michael@0: * that stated above, and implies nothing as to the relationship
michael@0: * between the two locales. This is intended for use by
michael@0: * applications who wish to cache collators, or otherwise reuse
michael@0: * collators when possible. The functional equivalent may change
michael@0: * over time. For more information, please see the
michael@0: * Locales and Services section of the ICU User Guide.
michael@0: * @param result fillin for the functionally equivalent locale
michael@0: * @param resultCapacity capacity of the fillin buffer
michael@0: * @param keyword a particular keyword as enumerated by
michael@0: * ucol_getKeywords.
michael@0: * @param locale the requested locale
michael@0: * @param isAvailable if non-NULL, pointer to a fillin parameter that
michael@0: * indicates whether the requested locale was 'available' to the
michael@0: * collation service. A locale is defined as 'available' if it
michael@0: * physically exists within the collation locale data.
michael@0: * @param status pointer to input-output error code
michael@0: * @return the actual buffer size needed for the locale. If greater
michael@0: * than resultCapacity, the returned full name will be truncated and
michael@0: * an error code will be returned.
michael@0: * @stable ICU 3.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ucol_getFunctionalEquivalent(char* result, int32_t resultCapacity,
michael@0: const char* keyword, const char* locale,
michael@0: UBool* isAvailable, UErrorCode* status);
michael@0:
michael@0: /**
michael@0: * Get the collation tailoring rules from a UCollator.
michael@0: * The rules will follow the rule syntax.
michael@0: * @param coll The UCollator to query.
michael@0: * @param length
michael@0: * @return The collation tailoring rules.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE const UChar* U_EXPORT2
michael@0: ucol_getRules( const UCollator *coll,
michael@0: int32_t *length);
michael@0:
michael@0: /** Get the short definition string for a collator. This API harvests the collator's
michael@0: * locale and the attribute set and produces a string that can be used for opening
michael@0: * a collator with the same properties using the ucol_openFromShortString API.
michael@0: * This string will be normalized.
michael@0: * The structure and the syntax of the string is defined in the "Naming collators"
michael@0: * section of the users guide:
michael@0: * http://icu-project.org/userguide/Collate_Concepts.html#Naming_Collators
michael@0: * This API supports preflighting.
michael@0: * @param coll a collator
michael@0: * @param locale a locale that will appear as a collators locale in the resulting
michael@0: * short string definition. If NULL, the locale will be harvested
michael@0: * from the collator.
michael@0: * @param buffer space to hold the resulting string
michael@0: * @param capacity capacity of the buffer
michael@0: * @param status for returning errors. All the preflighting errors are featured
michael@0: * @return length of the resulting string
michael@0: * @see ucol_openFromShortString
michael@0: * @see ucol_normalizeShortDefinitionString
michael@0: * @stable ICU 3.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ucol_getShortDefinitionString(const UCollator *coll,
michael@0: const char *locale,
michael@0: char *buffer,
michael@0: int32_t capacity,
michael@0: UErrorCode *status);
michael@0:
michael@0: /** Verifies and normalizes short definition string.
michael@0: * Normalized short definition string has all the option sorted by the argument name,
michael@0: * so that equivalent definition strings are the same.
michael@0: * This API supports preflighting.
michael@0: * @param source definition string
michael@0: * @param destination space to hold the resulting string
michael@0: * @param capacity capacity of the buffer
michael@0: * @param parseError if not NULL, structure that will get filled with error's pre
michael@0: * and post context in case of error.
michael@0: * @param status Error code. This API will return an error if an invalid attribute
michael@0: * or attribute/value combination is specified. All the preflighting
michael@0: * errors are also featured
michael@0: * @return length of the resulting normalized string.
michael@0: *
michael@0: * @see ucol_openFromShortString
michael@0: * @see ucol_getShortDefinitionString
michael@0: *
michael@0: * @stable ICU 3.0
michael@0: */
michael@0:
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ucol_normalizeShortDefinitionString(const char *source,
michael@0: char *destination,
michael@0: int32_t capacity,
michael@0: UParseError *parseError,
michael@0: UErrorCode *status);
michael@0:
michael@0:
michael@0: /**
michael@0: * Get a sort key for a string from a UCollator.
michael@0: * Sort keys may be compared using strcmp.
michael@0: *
michael@0: * Like ICU functions that write to an output buffer, the buffer contents
michael@0: * is undefined if the buffer capacity (resultLength parameter) is too small.
michael@0: * Unlike ICU functions that write a string to an output buffer,
michael@0: * the terminating zero byte is counted in the sort key length.
michael@0: * @param coll The UCollator containing the collation rules.
michael@0: * @param source The string to transform.
michael@0: * @param sourceLength The length of source, or -1 if null-terminated.
michael@0: * @param result A pointer to a buffer to receive the attribute.
michael@0: * @param resultLength The maximum size of result.
michael@0: * @return The size needed to fully store the sort key.
michael@0: * If there was an internal error generating the sort key,
michael@0: * a zero value is returned.
michael@0: * @see ucol_keyHashCode
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ucol_getSortKey(const UCollator *coll,
michael@0: const UChar *source,
michael@0: int32_t sourceLength,
michael@0: uint8_t *result,
michael@0: int32_t resultLength);
michael@0:
michael@0:
michael@0: /** Gets the next count bytes of a sort key. Caller needs
michael@0: * to preserve state array between calls and to provide
michael@0: * the same type of UCharIterator set with the same string.
michael@0: * The destination buffer provided must be big enough to store
michael@0: * the number of requested bytes.
michael@0: *
michael@0: * The generated sort key may or may not be compatible with
michael@0: * sort keys generated using ucol_getSortKey().
michael@0: * @param coll The UCollator containing the collation rules.
michael@0: * @param iter UCharIterator containing the string we need
michael@0: * the sort key to be calculated for.
michael@0: * @param state Opaque state of sortkey iteration.
michael@0: * @param dest Buffer to hold the resulting sortkey part
michael@0: * @param count number of sort key bytes required.
michael@0: * @param status error code indicator.
michael@0: * @return the actual number of bytes of a sortkey. It can be
michael@0: * smaller than count if we have reached the end of
michael@0: * the sort key.
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ucol_nextSortKeyPart(const UCollator *coll,
michael@0: UCharIterator *iter,
michael@0: uint32_t state[2],
michael@0: uint8_t *dest, int32_t count,
michael@0: UErrorCode *status);
michael@0:
michael@0: /** enum that is taken by ucol_getBound API
michael@0: * See below for explanation
michael@0: * do not change the values assigned to the
michael@0: * members of this enum. Underlying code
michael@0: * depends on them having these numbers
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: typedef enum {
michael@0: /** lower bound */
michael@0: UCOL_BOUND_LOWER = 0,
michael@0: /** upper bound that will match strings of exact size */
michael@0: UCOL_BOUND_UPPER = 1,
michael@0: /** upper bound that will match all the strings that have the same initial substring as the given string */
michael@0: UCOL_BOUND_UPPER_LONG = 2,
michael@0: UCOL_BOUND_VALUE_COUNT
michael@0: } UColBoundMode;
michael@0:
michael@0: /**
michael@0: * Produce a bound for a given sortkey and a number of levels.
michael@0: * Return value is always the number of bytes needed, regardless of
michael@0: * whether the result buffer was big enough or even valid.
michael@0: * Resulting bounds can be used to produce a range of strings that are
michael@0: * between upper and lower bounds. For example, if bounds are produced
michael@0: * for a sortkey of string "smith", strings between upper and lower
michael@0: * bounds with one level would include "Smith", "SMITH", "sMiTh".
michael@0: * There are two upper bounds that can be produced. If UCOL_BOUND_UPPER
michael@0: * is produced, strings matched would be as above. However, if bound
michael@0: * produced using UCOL_BOUND_UPPER_LONG is used, the above example will
michael@0: * also match "Smithsonian" and similar.
michael@0: * For more on usage, see example in cintltst/capitst.c in procedure
michael@0: * TestBounds.
michael@0: * Sort keys may be compared using strcmp.
michael@0: * @param source The source sortkey.
michael@0: * @param sourceLength The length of source, or -1 if null-terminated.
michael@0: * (If an unmodified sortkey is passed, it is always null
michael@0: * terminated).
michael@0: * @param boundType Type of bound required. It can be UCOL_BOUND_LOWER, which
michael@0: * produces a lower inclusive bound, UCOL_BOUND_UPPER, that
michael@0: * produces upper bound that matches strings of the same length
michael@0: * or UCOL_BOUND_UPPER_LONG that matches strings that have the
michael@0: * same starting substring as the source string.
michael@0: * @param noOfLevels Number of levels required in the resulting bound (for most
michael@0: * uses, the recommended value is 1). See users guide for
michael@0: * explanation on number of levels a sortkey can have.
michael@0: * @param result A pointer to a buffer to receive the resulting sortkey.
michael@0: * @param resultLength The maximum size of result.
michael@0: * @param status Used for returning error code if something went wrong. If the
michael@0: * number of levels requested is higher than the number of levels
michael@0: * in the source key, a warning (U_SORT_KEY_TOO_SHORT_WARNING) is
michael@0: * issued.
michael@0: * @return The size needed to fully store the bound.
michael@0: * @see ucol_keyHashCode
michael@0: * @stable ICU 2.1
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ucol_getBound(const uint8_t *source,
michael@0: int32_t sourceLength,
michael@0: UColBoundMode boundType,
michael@0: uint32_t noOfLevels,
michael@0: uint8_t *result,
michael@0: int32_t resultLength,
michael@0: UErrorCode *status);
michael@0:
michael@0: /**
michael@0: * Gets the version information for a Collator. Version is currently
michael@0: * an opaque 32-bit number which depends, among other things, on major
michael@0: * versions of the collator tailoring and UCA.
michael@0: * @param coll The UCollator to query.
michael@0: * @param info the version # information, the result will be filled in
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE void U_EXPORT2
michael@0: ucol_getVersion(const UCollator* coll, UVersionInfo info);
michael@0:
michael@0: /**
michael@0: * Gets the UCA version information for a Collator. Version is the
michael@0: * UCA version number (3.1.1, 4.0).
michael@0: * @param coll The UCollator to query.
michael@0: * @param info the version # information, the result will be filled in
michael@0: * @stable ICU 2.8
michael@0: */
michael@0: U_STABLE void U_EXPORT2
michael@0: ucol_getUCAVersion(const UCollator* coll, UVersionInfo info);
michael@0:
michael@0: /**
michael@0: * Merges two sort keys. The levels are merged with their corresponding counterparts
michael@0: * (primaries with primaries, secondaries with secondaries etc.). Between the values
michael@0: * from the same level a separator is inserted.
michael@0: *
michael@0: * This is useful, for example, for combining sort keys from first and last names
michael@0: * to sort such pairs.
michael@0: * It is possible to merge multiple sort keys by consecutively merging
michael@0: * another one with the intermediate result.
michael@0: *
michael@0: * The length of the merge result is the sum of the lengths of the input sort keys.
michael@0: *
michael@0: * Example (uncompressed):
michael@0: *
191B1D 01 050505 01 910505 00 michael@0: * 1F2123 01 050505 01 910505 00michael@0: * will be merged as michael@0: *
191B1D 02 1F2123 01 050505 02 050505 01 910505 02 910505 00michael@0: * michael@0: * If the destination buffer is not big enough, then its contents are undefined. michael@0: * If any of source lengths are zero or any of the source pointers are NULL/undefined, michael@0: * the result is of size zero. michael@0: * michael@0: * @param src1 the first sort key michael@0: * @param src1Length the length of the first sort key, including the zero byte at the end; michael@0: * can be -1 if the function is to find the length michael@0: * @param src2 the second sort key michael@0: * @param src2Length the length of the second sort key, including the zero byte at the end; michael@0: * can be -1 if the function is to find the length michael@0: * @param dest the buffer where the merged sort key is written, michael@0: * can be NULL if destCapacity==0 michael@0: * @param destCapacity the number of bytes in the dest buffer michael@0: * @return the length of the merged sort key, src1Length+src2Length; michael@0: * can be larger than destCapacity, or 0 if an error occurs (only for illegal arguments), michael@0: * in which cases the contents of dest is undefined michael@0: * @stable ICU 2.0 michael@0: */ michael@0: U_STABLE int32_t U_EXPORT2 michael@0: ucol_mergeSortkeys(const uint8_t *src1, int32_t src1Length, michael@0: const uint8_t *src2, int32_t src2Length, michael@0: uint8_t *dest, int32_t destCapacity); michael@0: michael@0: /** michael@0: * Universal attribute setter michael@0: * @param coll collator which attributes are to be changed michael@0: * @param attr attribute type michael@0: * @param value attribute value michael@0: * @param status to indicate whether the operation went on smoothly or there were errors michael@0: * @see UColAttribute michael@0: * @see UColAttributeValue michael@0: * @see ucol_getAttribute michael@0: * @stable ICU 2.0 michael@0: */ michael@0: U_STABLE void U_EXPORT2 michael@0: ucol_setAttribute(UCollator *coll, UColAttribute attr, UColAttributeValue value, UErrorCode *status); michael@0: michael@0: /** michael@0: * Universal attribute getter michael@0: * @param coll collator which attributes are to be changed michael@0: * @param attr attribute type michael@0: * @return attribute value michael@0: * @param status to indicate whether the operation went on smoothly or there were errors michael@0: * @see UColAttribute michael@0: * @see UColAttributeValue michael@0: * @see ucol_setAttribute michael@0: * @stable ICU 2.0 michael@0: */ michael@0: U_STABLE UColAttributeValue U_EXPORT2 michael@0: ucol_getAttribute(const UCollator *coll, UColAttribute attr, UErrorCode *status); michael@0: michael@0: /** Variable top michael@0: * is a two byte primary value which causes all the codepoints with primary values that michael@0: * are less or equal than the variable top to be shifted when alternate handling is set michael@0: * to UCOL_SHIFTED. michael@0: * Sets the variable top to a collation element value of a string supplied. michael@0: * @param coll collator which variable top needs to be changed michael@0: * @param varTop one or more (if contraction) UChars to which the variable top should be set michael@0: * @param len length of variable top string. If -1 it is considered to be zero terminated. michael@0: * @param status error code. If error code is set, the return value is undefined. michael@0: * Errors set by this function are: