* \endcode
* </pre>
* \htmlonly</blockquote>\endhtmlonly
-* <p>
-* For comparing strings exactly once, the <code>compare</code> method
-* provides the best performance. When sorting a list of strings however, it
-* is generally necessary to compare each string multiple times. In this case,
-* sort keys provide better performance. The <code>getSortKey</code> methods
+*
+* The <code>getSortKey</code> methods
* convert a string to a series of bytes that can be compared bitwise against
* other sort keys using <code>strcmp()</code>. Sort keys are written as
-* zero-terminated byte strings. They consist of several substrings, one for
-* each collation strength level, that are delimited by 0x01 bytes.
-* If the string code points are appended for UCOL_IDENTICAL, then they are
-* processed for correct code point order comparison and may contain 0x01
-* bytes but not zero bytes.
-* </p>
-* <p>
+* zero-terminated byte strings.
+*
* Another set of APIs returns a <code>CollationKey</code> object that wraps
* the sort key bytes instead of returning the bytes themselves.
* </p>
/**
* Transforms the string into a series of characters that can be compared
* with CollationKey::compareTo. It is not possible to restore the original
- * string from the chars in the sort key. The generated sort key handles
- * only a limited number of ignorable characters.
+ * string from the chars in the sort key.
* <p>Use CollationKey::equals or CollationKey::compare to compare the
* generated sort keys.
* If the source string is null, a null collation key will be returned.
+ *
+ * Note that sort keys are often less efficient than simply doing comparison.
+ * For more details, see the ICU User Guide.
+ *
* @param source the source string to be transformed into a sort key.
* @param key the collation key to be filled in
* @param status the error code status.
/**
* Transforms the string into a series of characters that can be compared
* with CollationKey::compareTo. It is not possible to restore the original
- * string from the chars in the sort key. The generated sort key handles
- * only a limited number of ignorable characters.
+ * string from the chars in the sort key.
* <p>Use CollationKey::equals or CollationKey::compare to compare the
* generated sort keys.
* <p>If the source string is null, a null collation key will be returned.
+ *
+ * Note that sort keys are often less efficient than simply doing comparison.
+ * For more details, see the ICU User Guide.
+ *
* @param source the source string to be transformed into a sort key.
* @param sourceLength length of the collation key
* @param key the collation key to be filled in
* Get the sort key as an array of bytes from a UnicodeString.
* Sort key byte arrays are zero-terminated and can be compared using
* strcmp().
+ *
+ * Note that sort keys are often less efficient than simply doing comparison.
+ * For more details, see the ICU User Guide.
+ *
* @param source string to be processed.
* @param result buffer to store result in. If NULL, number of bytes needed
* will be returned.
* Get the sort key as an array of bytes from a UChar buffer.
* Sort key byte arrays are zero-terminated and can be compared using
* strcmp().
+ *
+ * Note that sort keys are often less efficient than simply doing comparison.
+ * For more details, see the ICU User Guide.
+ *
* @param source string to be processed.
* @param sourceLength length of string to be processed.
* If -1, the string is 0 terminated and length will be decided by the
*/
/**
- * \file
+ * \file
* \brief C++ API: The RuleBasedCollator class implements the Collator abstract base class.
*/
UErrorCode &status) const;
/**
- * Transforms a specified region of the string into a series of characters
- * that can be compared with CollationKey.compare. Use a CollationKey when
- * you need to do repeated comparisions on the same string. For a single
- * comparison the compare method will be faster.
- * @param source the source string.
- * @param key the transformed key of the source string.
- * @param status the error code status.
- * @return the transformed key.
- * @see CollationKey
- * @stable ICU 2.0
- */
+ * Transforms the string into a series of characters
+ * that can be compared with CollationKey.compare().
+ *
+ * Note that sort keys are often less efficient than simply doing comparison.
+ * For more details, see the ICU User Guide.
+ *
+ * @param source the source string.
+ * @param key the transformed key of the source string.
+ * @param status the error code status.
+ * @return the transformed key.
+ * @see CollationKey
+ * @stable ICU 2.0
+ */
virtual CollationKey& getCollationKey(const UnicodeString& source,
CollationKey& key,
UErrorCode& status) const;
/**
- * Transforms a specified region of the string into a series of characters
- * that can be compared with CollationKey.compare. Use a CollationKey when
- * you need to do repeated comparisions on the same string. For a single
- * comparison the compare method will be faster.
- * @param source the source string.
- * @param sourceLength the length of the source string.
- * @param key the transformed key of the source string.
- * @param status the error code status.
- * @return the transformed key.
- * @see CollationKey
- * @stable ICU 2.0
- */
+ * Transforms a specified region of the string into a series of characters
+ * that can be compared with CollationKey.compare.
+ *
+ * Note that sort keys are often less efficient than simply doing comparison.
+ * For more details, see the ICU User Guide.
+ *
+ * @param source the source string.
+ * @param sourceLength the length of the source string.
+ * @param key the transformed key of the source string.
+ * @param status the error code status.
+ * @return the transformed key.
+ * @see CollationKey
+ * @stable ICU 2.0
+ */
virtual CollationKey& getCollationKey(const UChar *source,
int32_t sourceLength,
CollationKey& key,
/**
* Get the sort key as an array of bytes from a UnicodeString.
+ *
+ * Note that sort keys are often less efficient than simply doing comparison.
+ * For more details, see the ICU User Guide.
+ *
* @param source string to be processed.
* @param result buffer to store result in. If NULL, number of bytes needed
* will be returned.
/**
* Get the sort key as an array of bytes from a UChar buffer.
+ *
+ * Note that sort keys are often less efficient than simply doing comparison.
+ * For more details, see the ICU User Guide.
+ *
* @param source string to be processed.
* @param sourceLength length of string to be processed. If -1, the string
* is 0 terminated and length will be decided by the function.
* Get a sort key for a string from a UCollator.
* Sort keys may be compared using <TT>strcmp</TT>.
*
+ * 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,
projects / icu / commitdiff