By default, reordering codes specified for the start of the order are placed in the - * order given after a group of "special" non-script blocks. These special groups of characters + * 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 blocks if those special blocks are explicitly specified in the reordering. + * 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 used. If not - * that will result in a U_ILLEGAL_ARGUMENT_ERROR being set. + * 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 used. + * 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. @@ -735,10 +760,13 @@ ucol_setReorderCodes(UCollator* coll, /** * 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 of the result string (pre-flighting). + * 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. @@ -858,31 +886,32 @@ ucol_getKeywordValuesForLocale(const char* key, 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 + * 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 * 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 @@ -904,6 +933,7 @@ 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 attributes using the ucol_openFromShortString API. @@ -922,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, @@ -948,21 +978,25 @@ 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, @@ -1027,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; /** @@ -1104,6 +1144,17 @@ ucol_getUCAVersion(const UCollator* coll, UVersionInfo info); * * 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. * @@ -1166,8 +1217,6 @@ ucol_setAttribute(UCollator *coll, UColAttribute attr, UColAttributeValue value, U_STABLE UColAttributeValue U_EXPORT2 ucol_getAttribute(const UCollator *coll, UColAttribute attr, UErrorCode *status); -#ifndef U_HIDE_DRAFT_API - /** * Sets the variable top to the top of the specified reordering group. * The variable top determines the highest-sorting character @@ -1182,9 +1231,9 @@ ucol_getAttribute(const UCollator *coll, UColAttribute attr, UErrorCode *status) * immediately. Check for U_FAILURE() on output or use with * function chaining. (See User Guide for details.) * @see ucol_getMaxVariable - * @draft ICU 53 + * @stable ICU 53 */ -U_DRAFT void U_EXPORT2 +U_STABLE void U_EXPORT2 ucol_setMaxVariable(UCollator *coll, UColReorderCode group, UErrorCode *pErrorCode); /** @@ -1192,13 +1241,12 @@ ucol_setMaxVariable(UCollator *coll, UColReorderCode group, UErrorCode *pErrorCo * @param coll the collator * @return the maximum variable reordering group. * @see ucol_setMaxVariable - * @draft ICU 53 + * @stable ICU 53 */ -U_DRAFT UColReorderCode U_EXPORT2 +U_STABLE UColReorderCode U_EXPORT2 ucol_getMaxVariable(const UCollator *coll); -#endif /* U_HIDE_DRAFT_API */ - +#ifndef U_HIDE_DEPRECATED_API /** * Sets the variable top to the primary weight of the specified string. * @@ -1223,6 +1271,7 @@ U_DEPRECATED uint32_t U_EXPORT2 ucol_setVariableTop(UCollator *coll, const UChar *varTop, int32_t len, UErrorCode *status); +#endif /* U_HIDE_DEPRECATED_API */ /** * Gets the variable top value of a Collator. @@ -1237,6 +1286,7 @@ ucol_setVariableTop(UCollator *coll, */ U_STABLE uint32_t U_EXPORT2 ucol_getVariableTop(const UCollator *coll, UErrorCode *status); +#ifndef U_HIDE_DEPRECATED_API /** * Sets the variable top to the specified primary weight. * @@ -1252,6 +1302,7 @@ U_STABLE uint32_t U_EXPORT2 ucol_getVariableTop(const UCollator *coll, UErrorCod */ U_DEPRECATED void U_EXPORT2 ucol_restoreVariableTop(UCollator *coll, const uint32_t varTop, UErrorCode *status); +#endif /* U_HIDE_DEPRECATED_API */ /** * Thread safe cloning operation. The result is a clone of a given collator. @@ -1422,14 +1473,14 @@ ucol_cloneBinary(const UCollator *coll, * ucol_cloneBinary. Binary image used in instantiation of the * collator remains owned by the user and should stay around for * the lifetime of the collator. The API also takes a base collator - * which usually should be the root collator. + * which must be the root collator. * @param bin binary image owned by the user and required through the * lifetime of the collator * @param length size of the image. If negative, the API will try to * figure out the length of the image - * @param base fallback collator, usually the root collator. Base is required to be - * present through the lifetime of the collator. Currently - * it cannot be NULL. + * @param base Base collator, for lookup of untailored characters. + * Must be the root collator, must not be NULL. + * The base is required to be present through the lifetime of the collator. * @param status for catching errors * @return newly created collator * @see ucol_cloneBinary