* For more information about the collation service see - * the users guide. + * the User Guide. *
* Collation service provides correct sorting orders for most locales supported in ICU. * If specific data for a locale is not available, the orders eventually falls back - * to the UCA sort order. + * to the CLDR root sort order. *
* Sort ordering may be customized by providing your own set of rules. For more on - * this subject see the - * - * Collation customization section of the users guide. + * this subject see the + * Collation Customization section of the User Guide. *
* @see UCollationResult * @see UNormalizationMode @@ -62,12 +60,12 @@ typedef struct UCollator UCollator; /** * UCOL_LESS is returned if source string is compared to be less than target - * string in the u_strcoll() method. + * string in the ucol_strcoll() method. * UCOL_EQUAL is returned if source string is compared to be equal to target - * string in the u_strcoll() method. + * string in the ucol_strcoll() method. * UCOL_GREATER is returned if source string is compared to be greater than - * target string in the u_strcoll() method. - * @see u_strcoll() + * target string in the ucol_strcoll() method. + * @see ucol_strcoll() *
* Possible values for a comparison result * @stable ICU 2.0 @@ -127,10 +125,88 @@ typedef enum { /** upper case sorts before lower case */ UCOL_UPPER_FIRST = 25, +#ifndef U_HIDE_DEPRECATED_API + /** + * One more than the highest normal UColAttributeValue value. + * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. + */ UCOL_ATTRIBUTE_VALUE_COUNT - +#endif /* U_HIDE_DEPRECATED_API */ } UColAttributeValue; +/** + * Enum containing the codes for reordering segments of the collation table that are not script + * codes. These reordering codes are to be used in conjunction with the script codes. + * @see ucol_getReorderCodes + * @see ucol_setReorderCodes + * @see ucol_getEquivalentReorderCodes + * @see UScriptCode + * @stable ICU 4.8 + */ + typedef enum { + /** + * A special reordering code that is used to specify the default + * reordering codes for a locale. + * @stable ICU 4.8 + */ + UCOL_REORDER_CODE_DEFAULT = -1, + /** + * A special reordering code that is used to specify no reordering codes. + * @stable ICU 4.8 + */ + UCOL_REORDER_CODE_NONE = USCRIPT_UNKNOWN, + /** + * A special reordering code that is used to specify all other codes used for + * reordering except for the codes lised as UColReorderCode values and those + * listed explicitly in a reordering. + * @stable ICU 4.8 + */ + UCOL_REORDER_CODE_OTHERS = USCRIPT_UNKNOWN, + /** + * Characters with the space property. + * This is equivalent to the rule value "space". + * @stable ICU 4.8 + */ + UCOL_REORDER_CODE_SPACE = 0x1000, + /** + * The first entry in the enumeration of reordering groups. This is intended for use in + * range checking and enumeration of the reorder codes. + * @stable ICU 4.8 + */ + UCOL_REORDER_CODE_FIRST = UCOL_REORDER_CODE_SPACE, + /** + * Characters with the punctuation property. + * This is equivalent to the rule value "punct". + * @stable ICU 4.8 + */ + UCOL_REORDER_CODE_PUNCTUATION = 0x1001, + /** + * Characters with the symbol property. + * This is equivalent to the rule value "symbol". + * @stable ICU 4.8 + */ + UCOL_REORDER_CODE_SYMBOL = 0x1002, + /** + * Characters with the currency property. + * This is equivalent to the rule value "currency". + * @stable ICU 4.8 + */ + UCOL_REORDER_CODE_CURRENCY = 0x1003, + /** + * Characters with the digit property. + * This is equivalent to the rule value "digit". + * @stable ICU 4.8 + */ + UCOL_REORDER_CODE_DIGIT = 0x1004, +#ifndef U_HIDE_DEPRECATED_API + /** + * One more than the highest normal UColReorderCode value. + * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. + */ + UCOL_REORDER_CODE_LIMIT = 0x1005 +#endif /* U_HIDE_DEPRECATED_API */ +} UColReorderCode; + /** * Base letter represents a primary difference. Set comparison * level to UCOL_PRIMARY to ignore secondary and tertiary differences. @@ -164,10 +240,12 @@ typedef UColAttributeValue UCollationStrength; * @stable ICU 2.0 */ typedef enum { - /** Attribute for direction of secondary weights - used in French. + /** Attribute for direction of secondary weights - used in Canadian French. * Acceptable values are UCOL_ON, which results in secondary weights * being considered backwards and UCOL_OFF which treats secondary - * weights in the order they appear.*/ + * weights in the order they appear. + * @stable ICU 2.0 + */ UCOL_FRENCH_COLLATION, /** Attribute for handling variable elements. * Acceptable values are UCOL_NON_IGNORABLE (default) @@ -176,14 +254,18 @@ typedef enum { * and UCOL_SHIFTED which causes codepoints with primary * weights that are equal or below the variable top value * to be ignored on primary level and moved to the quaternary - * level.*/ + * level. + * @stable ICU 2.0 + */ UCOL_ALTERNATE_HANDLING, /** Controls the ordering of upper and lower case letters. * Acceptable values are UCOL_OFF (default), which orders * upper and lower case letters in accordance to their tertiary * weights, UCOL_UPPER_FIRST which forces upper case letters to * sort before lower case letters, and UCOL_LOWER_FIRST which does - * the opposite. */ + * the opposite. + * @stable ICU 2.0 + */ UCOL_CASE_FIRST, /** Controls whether an extra case level (positioned before the third * level) is generated or not. Acceptable values are UCOL_OFF (default), @@ -191,7 +273,9 @@ typedef enum { * level to be generated. Contents of the case level are affected by * the value of UCOL_CASE_FIRST attribute. A simple way to ignore * accent differences in a string is to set the strength to UCOL_PRIMARY - * and enable case level. */ + * and enable case level. + * @stable ICU 2.0 + */ UCOL_CASE_LEVEL, /** Controls whether the normalization check and necessary normalizations * are performed. When set to UCOL_OFF (default) no normalization check @@ -199,29 +283,71 @@ typedef enum { * input data is in so-called FCD form (see users manual for more info). * When set to UCOL_ON, an incremental check is performed to see whether * the input data is in the FCD form. If the data is not in the FCD form, - * incremental NFD normalization is performed. */ + * incremental NFD normalization is performed. + * @stable ICU 2.0 + */ UCOL_NORMALIZATION_MODE, - /** An alias for UCOL_NORMALIZATION_MODE attribute */ + /** An alias for UCOL_NORMALIZATION_MODE attribute. + * @stable ICU 2.0 + */ UCOL_DECOMPOSITION_MODE = UCOL_NORMALIZATION_MODE, /** The strength attribute. Can be either UCOL_PRIMARY, UCOL_SECONDARY, * UCOL_TERTIARY, UCOL_QUATERNARY or UCOL_IDENTICAL. The usual strength - * for most locales (except Japanese) is tertiary. Quaternary strength + * for most locales (except Japanese) is tertiary. + * + * Quaternary strength * is useful when combined with shifted setting for alternate handling - * attribute and for JIS x 4061 collation, when it is used to distinguish - * between Katakana and Hiragana (this is achieved by setting the - * UCOL_HIRAGANA_QUATERNARY mode to on. Otherwise, quaternary level - * is affected only by the number of non ignorable code points in - * the string. Identical strength is rarely useful, as it amounts - * to codepoints of the NFD form of the string. */ + * attribute and for JIS X 4061 collation, when it is used to distinguish + * between Katakana and Hiragana. + * Otherwise, quaternary level + * is affected only by the number of non-ignorable code points in + * the string. + * + * Identical strength is rarely useful, as it amounts + * to codepoints of the NFD form of the string. + * @stable ICU 2.0 + */ UCOL_STRENGTH, +#ifndef U_HIDE_DEPRECATED_API /** When turned on, this attribute positions Hiragana before all * non-ignorables on quaternary level This is a sneaky way to produce JIS - * sort order */ - UCOL_HIRAGANA_QUATERNARY_MODE, - /** When turned on, this attribute generates a collation key - * for the numeric value of substrings of digits. - * This is a way to get '100' to sort AFTER '2'. */ - UCOL_NUMERIC_COLLATION, + * sort order. + * + * This attribute was an implementation detail of the CLDR Japanese tailoring. + * Since ICU 50, this attribute is not settable any more via API functions. + * Since CLDR 25/ICU 53, explicit quaternary relations are used + * to achieve the same Japanese sort order. + * + * @deprecated ICU 50 Implementation detail, cannot be set via API, was removed from implementation. + */ + UCOL_HIRAGANA_QUATERNARY_MODE = UCOL_STRENGTH + 1, +#endif /* U_HIDE_DEPRECATED_API */ + /** + * When turned on, this attribute makes + * substrings of digits sort according to their numeric values. + * + * This is a way to get '100' to sort AFTER '2'. Note that the longest + * digit substring that can be treated as a single unit is + * 254 digits (not counting leading zeros). If a digit substring is + * longer than that, the digits beyond the limit will be treated as a + * separate digit substring. + * + * A "digit" in this sense is a code point with General_Category=Nd, + * which does not include circled numbers, roman numerals, etc. + * Only a contiguous digit substring is considered, that is, + * non-negative integers without separators. + * There is no support for plus/minus signs, decimals, exponents, etc. + * + * @stable ICU 2.8 + */ + UCOL_NUMERIC_COLLATION = UCOL_STRENGTH + 2, + + /* Do not conditionalize the following with #ifndef U_HIDE_DEPRECATED_API, + * it is needed for layout of RuleBasedCollator object. */ + /** + * One more than the highest normal UColAttribute value. + * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. + */ UCOL_ATTRIBUTE_COUNT } UColAttribute; @@ -229,14 +355,32 @@ typedef enum { * @stable ICU 2.0 */ typedef enum { - /** Retrieve tailoring only */ + /** + * Retrieves the tailoring rules only. + * Same as calling the version of getRules() without UColRuleOption. + * @stable ICU 2.0 + */ UCOL_TAILORING_ONLY, - /** Retrieve UCA rules and tailoring */ + /** + * Retrieves the "UCA rules" concatenated with the tailoring rules. + * The "UCA rules" are an approximation of the root collator's sort order. + * They are almost never used or useful at runtime and can be removed from the data. + * See http://userguide.icu-project.org/collation/customization#TOC-Building-on-Existing-Locales + * @stable ICU 2.0 + */ UCOL_FULL_RULES } UColRuleOption ; /** * Open a UCollator for comparing strings. + * + * For some languages, multiple collation types are available; + * for example, "de@collation=phonebook". + * Starting with ICU 54, collation attributes can be specified via locale keywords as well, + * in the old locale extension syntax ("el@colCaseFirst=upper") + * or in language tag syntax ("el-u-kf-upper"). + * See User Guide: Collation API. + * * The UCollator pointer is used in all the calls to the Collation * service. After finished, collator must be disposed of by calling * {@link #ucol_close }. @@ -244,8 +388,8 @@ typedef enum { * Special values for locales can be passed in - * if NULL is passed for the locale, the default locale * collation rules will be used. If empty string ("") or - * "root" are passed, UCA rules will be used. - * @param status A pointer to an UErrorCode to receive any errors + * "root" are passed, the root collator will be returned. + * @param status A pointer to a UErrorCode to receive any errors * @return A pointer to a UCollator, or 0 if an error occurred. * @see ucol_openRules * @see ucol_safeClone @@ -256,7 +400,7 @@ U_STABLE UCollator* U_EXPORT2 ucol_open(const char *loc, UErrorCode *status); /** - * Produce an UCollator instance according to the rules supplied. + * Produce a UCollator instance according to the rules supplied. * The rules are used to change the default ordering, defined in the * UCA in a process called tailoring. The resulting UCollator pointer * can be used in the same way as the one obtained by {@link #ucol_strcoll }. @@ -272,7 +416,7 @@ ucol_open(const char *loc, UErrorCode *status); * @param parseError A pointer to UParseError to recieve information about errors * occurred during parsing. This argument can currently be set * to NULL, but at users own risk. Please provide a real structure. - * @param status A pointer to an UErrorCode to receive any errors + * @param status A pointer to a UErrorCode to receive any errors * @return A pointer to a UCollator. It is not guaranteed that NULL be returned in case * of error - please use status argument to check for errors. * @see ucol_open @@ -288,11 +432,12 @@ ucol_openRules( const UChar *rules, UParseError *parseError, UErrorCode *status); +#ifndef U_HIDE_DEPRECATED_API /** * Open a collator defined by a short form string. * The structure and the syntax of the string is defined in the "Naming collators" * section of the users guide: - * http://icu.sourceforge.net/userguide/Collate_Concepts.html#Naming_Collators + * http://userguide.icu-project.org/collation/concepts#TOC-Collator-naming-scheme * Attributes are overriden by the subsequent attributes. So, for "S2_S3", final * strength will be 3. 3066bis locale overrides individual locale parts. * The call to this function is equivalent to a call to ucol_open, followed by a @@ -319,20 +464,21 @@ ucol_openRules( const UChar *rules, * @see ucol_setVariableTop * @see ucol_getShortDefinitionString * @see ucol_normalizeShortDefinitionString - * @stable ICU 3.0 - * + * @deprecated ICU 54 Use ucol_open() with language tag collation keywords instead. */ -U_STABLE UCollator* U_EXPORT2 +U_DEPRECATED UCollator* U_EXPORT2 ucol_openFromShortString( const char *definition, UBool forceDefaults, UParseError *parseError, UErrorCode *status); +#endif /* U_HIDE_DEPRECATED_API */ +#ifndef U_HIDE_DEPRECATED_API /** * Get a set containing the contractions defined by the collator. The set includes - * both the UCA contractions and the contractions defined by the collator. This set + * both the root collator's contractions and the contractions defined by the collator. This set * will contain only strings. If a tailoring explicitly suppresses contractions from - * the UCA (like Russian), removed contractions will not be in the resulting set. + * the root collator (like Russian), removed contractions will not be in the resulting set. * @param coll collator * @param conts the set to hold the result. It gets emptied before * contractions are added. @@ -345,19 +491,20 @@ U_DEPRECATED int32_t U_EXPORT2 ucol_getContractions( const UCollator *coll, USet *conts, UErrorCode *status); +#endif /* U_HIDE_DEPRECATED_API */ /** * Get a set containing the expansions defined by the collator. The set includes - * both the UCA expansions and the expansions defined by the tailoring + * both the root collator's expansions and the expansions defined by the tailoring * @param coll collator * @param contractions if not NULL, the set to hold the contractions * @param expansions if not NULL, the set to hold the expansions * @param addPrefixes add the prefix contextual elements to contractions * @param status to hold the error code * - * @draft ICU 3.4 + * @stable ICU 3.4 */ -U_DRAFT void U_EXPORT2 +U_STABLE void U_EXPORT2 ucol_getContractionsAndExpansions( const UCollator *coll, USet *contractions, USet *expansions, UBool addPrefixes, UErrorCode *status); @@ -375,6 +522,25 @@ ucol_getContractionsAndExpansions( const UCollator *coll, U_STABLE void U_EXPORT2 ucol_close(UCollator *coll); +#if U_SHOW_CPLUSPLUS_API + +U_NAMESPACE_BEGIN + +/** + * \class LocalUCollatorPointer + * "Smart pointer" class, closes a UCollator via ucol_close(). + * For most methods see the LocalPointerBase base class. + * + * @see LocalPointerBase + * @see LocalPointer + * @stable ICU 4.4 + */ +U_DEFINE_LOCAL_OPEN_POINTER(LocalUCollatorPointer, UCollator, ucol_close); + +U_NAMESPACE_END + +#endif // U_SHOW_CPLUSPLUS_API + /** * Compare two strings. * The strings will be compared using the options already specified. @@ -397,6 +563,33 @@ ucol_strcoll( const UCollator *coll, const UChar *target, int32_t targetLength); +/** +* Compare two strings in UTF-8. +* The strings will be compared using the options already specified. +* Note: When input string contains malformed a UTF-8 byte sequence, +* this function treats these bytes as REPLACEMENT CHARACTER (U+FFFD). +* @param coll The UCollator containing the comparison rules. +* @param source The source UTF-8 string. +* @param sourceLength The length of source, or -1 if null-terminated. +* @param target The target UTF-8 string. +* @param targetLength The length of target, or -1 if null-terminated. +* @param status A pointer to a UErrorCode to receive any errors +* @return The result of comparing the strings; one of UCOL_EQUAL, +* UCOL_GREATER, UCOL_LESS +* @see ucol_greater +* @see ucol_greaterOrEqual +* @see ucol_equal +* @stable ICU 50 +*/ +U_STABLE UCollationResult U_EXPORT2 +ucol_strcollUTF8( + const UCollator *coll, + const char *source, + int32_t sourceLength, + const char *target, + int32_t targetLength, + UErrorCode *status); + /** * Determine if one string is greater than another. * This function is equivalent to {@link #ucol_strcoll } == UCOL_GREATER @@ -462,7 +655,7 @@ ucol_equal(const UCollator *coll, * @param tIter The target string iterator. * @return The result of comparing the strings; one of UCOL_EQUAL, * UCOL_GREATER, UCOL_LESS - * @param status A pointer to an UErrorCode to receive any errors + * @param status A pointer to a UErrorCode to receive any errors * @see ucol_strcoll * @stable ICU 2.6 */ @@ -497,6 +690,98 @@ U_STABLE void U_EXPORT2 ucol_setStrength(UCollator *coll, UCollationStrength strength); +/** + * Retrieves the reordering codes for this collator. + * These reordering codes are a combination of UScript codes and UColReorderCode entries. + * @param coll The UCollator to query. + * @param dest The array to fill with the script ordering. + * @param destCapacity The length of dest. If it is 0, then dest may be NULL and the function + * will only return the length of the result without writing any codes (pre-flighting). + * @param pErrorCode Must be a valid pointer to an error code value, which must not indicate a + * failure before the function call. + * @return The number of reordering codes written to the dest array. + * @see ucol_setReorderCodes + * @see ucol_getEquivalentReorderCodes + * @see UScriptCode + * @see UColReorderCode + * @stable ICU 4.8 + */ +U_STABLE int32_t U_EXPORT2 +ucol_getReorderCodes(const UCollator* coll, + int32_t* dest, + int32_t destCapacity, + UErrorCode *pErrorCode); +/** + * Sets the reordering codes for this collator. + * Collation reordering allows scripts and some other groups of characters + * to be moved relative to each other. This reordering is done on top of + * the DUCET/CLDR standard collation order. Reordering can specify groups to be placed + * at the start and/or the end of the collation order. These groups are specified using + * UScript codes and UColReorderCode entries. + * + *
By default, reordering codes specified for the start of the order are placed in the + * order given after several special non-script blocks. These special groups of characters + * are space, punctuation, symbol, currency, and digit. These special groups are represented with + * UColReorderCode entries. Script groups can be intermingled with + * these special non-script groups if those special groups are explicitly specified in the reordering. + * + *
The special code OTHERS stands for any script that is not explicitly + * mentioned in the list of reordering codes given. Anything that is after OTHERS + * will go at the very end of the reordering in the order given. + * + *
The special reorder code DEFAULT will reset the reordering for this collator + * to the default for this collator. The default reordering may be the DUCET/CLDR order or may be a reordering that + * was specified when this collator was created from resource data or from rules. The + * DEFAULT code must be the sole code supplied when it is used. + * If not, then U_ILLEGAL_ARGUMENT_ERROR will be set. + * + *
The special reorder code NONE will remove any reordering for this collator. + * The result of setting no reordering will be to have the DUCET/CLDR ordering used. The + * NONE code must be the sole code supplied when it is used. + * + * @param coll The UCollator to set. + * @param reorderCodes An array of script codes in the new order. This can be NULL if the + * length is also set to 0. An empty array will clear any reordering codes on the collator. + * @param reorderCodesLength The length of reorderCodes. + * @param pErrorCode Must be a valid pointer to an error code value, which must not indicate a + * failure before the function call. + * @see ucol_getReorderCodes + * @see ucol_getEquivalentReorderCodes + * @see UScriptCode + * @see UColReorderCode + * @stable ICU 4.8 + */ +U_STABLE void U_EXPORT2 +ucol_setReorderCodes(UCollator* coll, + const int32_t* reorderCodes, + int32_t reorderCodesLength, + UErrorCode *pErrorCode); + +/** + * Retrieves the reorder codes that are grouped with the given reorder code. Some reorder + * codes will be grouped and must reorder together. + * Beginning with ICU 55, scripts only reorder together if they are primary-equal, + * for example Hiragana and Katakana. + * + * @param reorderCode The reorder code to determine equivalence for. + * @param dest The array to fill with the script ordering. + * @param destCapacity The length of dest. If it is 0, then dest may be NULL and the function + * will only return the length of the result without writing any codes (pre-flighting). + * @param pErrorCode Must be a valid pointer to an error code value, which must not indicate + * a failure before the function call. + * @return The number of reordering codes written to the dest array. + * @see ucol_setReorderCodes + * @see ucol_getReorderCodes + * @see UScriptCode + * @see UColReorderCode + * @stable ICU 4.8 + */ +U_STABLE int32_t U_EXPORT2 +ucol_getEquivalentReorderCodes(int32_t reorderCode, + int32_t* dest, + int32_t destCapacity, + UErrorCode *pErrorCode); + /** * Get the display name for a UCollator. * The display name is suitable for presentation to a user. @@ -504,7 +789,7 @@ ucol_setStrength(UCollator *coll, * @param dispLoc The locale for display. * @param result A pointer to a buffer to receive the attribute. * @param resultLength The maximum size of result. - * @param status A pointer to an UErrorCode to receive any errors + * @param status A pointer to a UErrorCode to receive any errors * @return The total buffer size needed; if greater than resultLength, * the output was truncated. * @stable ICU 2.0 @@ -520,13 +805,13 @@ ucol_getDisplayName( const char *objLoc, * Get a locale for which collation rules are available. * A UCollator in a locale returned by this function will perform the correct * collation for the locale. - * @param index The index of the desired locale. + * @param localeIndex The index of the desired locale. * @return A locale for which collation rules are available, or 0 if none. * @see ucol_countAvailable * @stable ICU 2.0 */ U_STABLE const char* U_EXPORT2 -ucol_getAvailable(int32_t index); +ucol_getAvailable(int32_t localeIndex); /** * Determine how many locales have collation rules available. @@ -579,31 +864,54 @@ U_STABLE UEnumeration* U_EXPORT2 ucol_getKeywordValues(const char *keyword, UErrorCode *status); /** - * Return the functionally equivalent locale for the given - * requested locale, with respect to given keyword, for the - * collation service. If two locales return the same result, then - * collators instantiated for these locales will behave - * equivalently. The converse is not always true; two collators + * Given a key and a locale, returns an array of string values in a preferred + * order that would make a difference. These are all and only those values where + * the open (creation) of the service with the locale formed from the input locale + * plus input keyword and that value has different behavior than creation with the + * input locale alone. + * @param key one of the keys supported by this service. For now, only + * "collation" is supported. + * @param locale the locale + * @param commonlyUsed if set to true it will return only commonly used values + * with the given locale in preferred order. Otherwise, + * it will return all the available values for the locale. + * @param status error status + * @return a string enumeration over keyword values for the given key and the locale. + * @stable ICU 4.2 + */ +U_STABLE UEnumeration* U_EXPORT2 +ucol_getKeywordValuesForLocale(const char* key, + const char* locale, + UBool commonlyUsed, + UErrorCode* status); + +/** + * Return the functionally equivalent locale for the specified + * input locale, with respect to given keyword, for the + * collation service. If two different input locale + keyword + * combinations produce the same result locale, then collators + * instantiated for these two different input locales will behave + * equivalently. The converse is not always true; two collators * may in fact be equivalent, but return different results, due to - * internal details. The return result has no other meaning than + * internal details. The return result has no other meaning than * that stated above, and implies nothing as to the relationship - * between the two locales. This is intended for use by + * between the two locales. This is intended for use by * applications who wish to cache collators, or otherwise reuse - * collators when possible. The functional equivalent may change - * over time. For more information, please see the + * collators when possible. The functional equivalent may change + * over time. For more information, please see the * Locales and Services section of the ICU User Guide. - * @param result fillin for the functionally equivalent locale + * @param result fillin for the functionally equivalent result locale * @param resultCapacity capacity of the fillin buffer * @param keyword a particular keyword as enumerated by * ucol_getKeywords. - * @param locale the requested locale + * @param locale the specified input locale * @param isAvailable if non-NULL, pointer to a fillin parameter that - * indicates whether the requested locale was 'available' to the - * collation service. A locale is defined as 'available' if it + * on return indicates whether the specified input locale was 'available' + * to the collation service. A locale is defined as 'available' if it * physically exists within the collation locale data. * @param status pointer to input-output error code - * @return the actual buffer size needed for the locale. If greater + * @return the actual buffer size needed for the locale. If greater * than resultCapacity, the returned full name will be truncated and * an error code will be returned. * @stable ICU 3.0 @@ -614,24 +922,25 @@ ucol_getFunctionalEquivalent(char* result, int32_t resultCapacity, UBool* isAvailable, UErrorCode* status); /** - * Get the collation rules from a UCollator. + * Get the collation tailoring rules from a UCollator. * The rules will follow the rule syntax. * @param coll The UCollator to query. * @param length - * @return The collation rules. + * @return The collation tailoring rules. * @stable ICU 2.0 */ U_STABLE const UChar* U_EXPORT2 ucol_getRules( const UCollator *coll, int32_t *length); +#ifndef U_HIDE_DEPRECATED_API /** Get the short definition string for a collator. This API harvests the collator's * locale and the attribute set and produces a string that can be used for opening - * a collator with the same properties using the ucol_openFromShortString API. + * a collator with the same attributes using the ucol_openFromShortString API. * This string will be normalized. * The structure and the syntax of the string is defined in the "Naming collators" * section of the users guide: - * http://icu.sourceforge.net/userguide/Collate_Concepts.html#Naming_Collators + * http://userguide.icu-project.org/collation/concepts#TOC-Collator-naming-scheme * This API supports preflighting. * @param coll a collator * @param locale a locale that will appear as a collators locale in the resulting @@ -643,9 +952,9 @@ ucol_getRules( const UCollator *coll, * @return length of the resulting string * @see ucol_openFromShortString * @see ucol_normalizeShortDefinitionString - * @stable ICU 3.0 + * @deprecated ICU 54 */ -U_STABLE int32_t U_EXPORT2 +U_DEPRECATED int32_t U_EXPORT2 ucol_getShortDefinitionString(const UCollator *coll, const char *locale, char *buffer, @@ -669,26 +978,37 @@ ucol_getShortDefinitionString(const UCollator *coll, * @see ucol_openFromShortString * @see ucol_getShortDefinitionString * - * @stable ICU 3.0 + * @deprecated ICU 54 */ -U_STABLE int32_t U_EXPORT2 +U_DEPRECATED int32_t U_EXPORT2 ucol_normalizeShortDefinitionString(const char *source, char *destination, int32_t capacity, UParseError *parseError, UErrorCode *status); - +#endif /* U_HIDE_DEPRECATED_API */ + /** * Get a sort key for a string from a UCollator. * Sort keys may be compared using strcmp. + * + * Note that sort keys are often less efficient than simply doing comparison. + * For more details, see the ICU User Guide. + * + * Like ICU functions that write to an output buffer, the buffer contents + * is undefined if the buffer capacity (resultLength parameter) is too small. + * Unlike ICU functions that write a string to an output buffer, + * the terminating zero byte is counted in the sort key length. * @param coll The UCollator containing the collation rules. * @param source The string to transform. * @param sourceLength The length of source, or -1 if null-terminated. * @param result A pointer to a buffer to receive the attribute. * @param resultLength The maximum size of result. - * @return The size needed to fully store the sort key.. + * @return The size needed to fully store the sort key. + * If there was an internal error generating the sort key, + * a zero value is returned. * @see ucol_keyHashCode * @stable ICU 2.0 */ @@ -704,10 +1024,10 @@ ucol_getSortKey(const UCollator *coll, * to preserve state array between calls and to provide * the same type of UCharIterator set with the same string. * The destination buffer provided must be big enough to store - * the number of requested bytes. Generated sortkey is not - * compatible with sortkeys generated using ucol_getSortKey - * API, since we don't do any compression. If uncompressed - * sortkeys are required, this API can be used. + * the number of requested bytes. + * + * The generated sort key may or may not be compatible with + * sort keys generated using ucol_getSortKey(). * @param coll The UCollator containing the collation rules. * @param iter UCharIterator containing the string we need * the sort key to be calculated for. @@ -741,7 +1061,13 @@ typedef enum { UCOL_BOUND_UPPER = 1, /** upper bound that will match all the strings that have the same initial substring as the given string */ UCOL_BOUND_UPPER_LONG = 2, - UCOL_BOUND_VALUE_COUNT +#ifndef U_HIDE_DEPRECATED_API + /** + * One more than the highest normal UColBoundMode value. + * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. + */ + UCOL_BOUND_VALUE_COUNT +#endif /* U_HIDE_DEPRECATED_API */ } UColBoundMode; /** @@ -811,26 +1137,51 @@ ucol_getVersion(const UCollator* coll, UVersionInfo info); U_STABLE void U_EXPORT2 ucol_getUCAVersion(const UCollator* coll, UVersionInfo info); -/** - * Merge two sort keys. The levels are merged with their corresponding counterparts +/** + * Merges two sort keys. The levels are merged with their corresponding counterparts * (primaries with primaries, secondaries with secondaries etc.). Between the values * from the same level a separator is inserted. - * example (uncompressed): - * 191B1D 01 050505 01 910505 00 and 1F2123 01 050505 01 910505 00 + * + * This is useful, for example, for combining sort keys from first and last names + * to sort such pairs. + * See http://www.unicode.org/reports/tr10/#Merging_Sort_Keys + * + * The recommended way to achieve "merged" sorting is by + * concatenating strings with U+FFFE between them. + * The concatenation has the same sort order as the merged sort keys, + * but merge(getSortKey(str1), getSortKey(str2)) may differ from getSortKey(str1 + '\uFFFE' + str2). + * Using strings with U+FFFE may yield shorter sort keys. + * + * For details about Sort Key Features see + * http://userguide.icu-project.org/collation/api#TOC-Sort-Key-Features + * + * It is possible to merge multiple sort keys by consecutively merging + * another one with the intermediate result. + * + * The length of the merge result is the sum of the lengths of the input sort keys. + * + * Example (uncompressed): + *
191B1D 01 050505 01 910505 00 + * 1F2123 01 050505 01 910505 00* will be merged as - * 191B1D 02 1F212301 050505 02 050505 01 910505 02 910505 00 - * This allows for concatenating of first and last names for sorting, among other things. - * If the destination buffer is not big enough, the results are undefined. - * If any of source lengths are zero or any of source pointers are NULL/undefined, - * result is of size zero. - * @param src1 pointer to the first sortkey - * @param src1Length length of the first sortkey - * @param src2 pointer to the second sortkey - * @param src2Length length of the second sortkey - * @param dest buffer to hold the result - * @param destCapacity size of the buffer for the result - * @return size of the result. If the buffer is big enough size is always - * src1Length+src2Length-1 + *
191B1D 02 1F2123 01 050505 02 050505 01 910505 02 910505 00+ * + * If the destination buffer is not big enough, then its contents are undefined. + * If any of source lengths are zero or any of the source pointers are NULL/undefined, + * the result is of size zero. + * + * @param src1 the first sort key + * @param src1Length the length of the first sort key, including the zero byte at the end; + * can be -1 if the function is to find the length + * @param src2 the second sort key + * @param src2Length the length of the second sort key, including the zero byte at the end; + * can be -1 if the function is to find the length + * @param dest the buffer where the merged sort key is written, + * can be NULL if destCapacity==0 + * @param destCapacity the number of bytes in the dest buffer + * @return the length of the merged sort key, src1Length+src2Length; + * can be larger than destCapacity, or 0 if an error occurs (only for illegal arguments), + * in which cases the contents of dest is undefined * @stable ICU 2.0 */ U_STABLE int32_t U_EXPORT2 @@ -866,66 +1217,103 @@ ucol_setAttribute(UCollator *coll, UColAttribute attr, UColAttributeValue value, U_STABLE UColAttributeValue U_EXPORT2 ucol_getAttribute(const UCollator *coll, UColAttribute attr, UErrorCode *status); -/** Variable top - * is a two byte primary value which causes all the codepoints with primary values that - * are less or equal than the variable top to be shifted when alternate handling is set - * to UCOL_SHIFTED. - * Sets the variable top to a collation element value of a string supplied. - * @param coll collator which variable top needs to be changed +/** + * Sets the variable top to the top of the specified reordering group. + * The variable top determines the highest-sorting character + * which is affected by UCOL_ALTERNATE_HANDLING. + * If that attribute is set to UCOL_NON_IGNORABLE, then the variable top has no effect. + * @param coll the collator + * @param group one of UCOL_REORDER_CODE_SPACE, UCOL_REORDER_CODE_PUNCTUATION, + * UCOL_REORDER_CODE_SYMBOL, UCOL_REORDER_CODE_CURRENCY; + * or UCOL_REORDER_CODE_DEFAULT to restore the default max variable group + * @param pErrorCode Standard ICU error code. Its input value must + * pass the U_SUCCESS() test, or else the function returns + * immediately. Check for U_FAILURE() on output or use with + * function chaining. (See User Guide for details.) + * @see ucol_getMaxVariable + * @stable ICU 53 + */ +U_STABLE void U_EXPORT2 +ucol_setMaxVariable(UCollator *coll, UColReorderCode group, UErrorCode *pErrorCode); + +/** + * Returns the maximum reordering group whose characters are affected by UCOL_ALTERNATE_HANDLING. + * @param coll the collator + * @return the maximum variable reordering group. + * @see ucol_setMaxVariable + * @stable ICU 53 + */ +U_STABLE UColReorderCode U_EXPORT2 +ucol_getMaxVariable(const UCollator *coll); + +#ifndef U_HIDE_DEPRECATED_API +/** + * Sets the variable top to the primary weight of the specified string. + * + * Beginning with ICU 53, the variable top is pinned to + * the top of one of the supported reordering groups, + * and it must not be beyond the last of those groups. + * See ucol_setMaxVariable(). + * @param coll the collator * @param varTop one or more (if contraction) UChars to which the variable top should be set * @param len length of variable top string. If -1 it is considered to be zero terminated. - * @param status error code. If error code is set, the return value is undefined. - * Errors set by this function are: