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