Collator class performs locale-sensitive string
* comparison.
* Collator is an abstract base class. Subclasses implement
* specific collation strategies. One subclass,
* RuleBasedCollator, is currently provided and is applicable
* to a wide set of languages. Other subclasses may be created to handle more
* specialized needs.
*
* Like other locale-sensitive classes, you can use the static factory method,
* createInstance, to obtain the appropriate
* Collator object for a given locale. You will only need to
* look at the subclasses of Collator if you need to
* understand the details of a particular collation strategy or if you need to
* modify that strategy.
*
* The following example shows how to compare two strings using the
* Collator for the default locale.
*
*
* \code
* // Compare two strings in the default locale
* UErrorCode success = U_ZERO_ERROR;
* Collator* myCollator = Collator::createInstance(success);
* if (myCollator->compare("abc", "ABC") < 0)
* cout << "abc is less than ABC" << endl;
* else
* cout << "abc is greater than or equal to ABC" << endl;
* \endcode
*
*
*
* You can set a Collator's strength property to
* determine the level of difference considered significant in comparisons.
* Four strengths are provided: PRIMARY, SECONDARY,
* TERTIARY, and IDENTICAL. The exact assignment of
* strengths to language features is locale dependant. For example, in Czech,
* "e" and "f" are considered primary differences, while "e" and "\u00EA" are
* secondary differences, "e" and "E" are tertiary differences and "e" and "e"
* are identical. The following shows how both case and accents could be
* ignored for US English.
*
*
* \code
* //Get the Collator for US English and set its strength to PRIMARY
* UErrorCode success = U_ZERO_ERROR;
* Collator* usCollator =
* Collator::createInstance(Locale::US, success);
* usCollator->setStrength(Collator::PRIMARY);
* if (usCollator->compare("abc", "ABC") == 0)
* cout <<
* "'abc' and 'ABC' strings are equivalent with strength PRIMARY" <<
* endl;
* \endcode
*
*
*
* For comparing strings exactly once, the compare 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 getSortKey methods
* convert a string to a series of bytes that can be compared bitwise against
* other sort keys using strcmp(). 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.
*
* An older set of APIs returns a CollationKey object that wraps
* the sort key bytes instead of returning the bytes themselves.
* Its use is deprecated, but it is still available for compatibility with
* Java.
*
* Note: Collators with different Locale,
* CollationStrength and DecompositionMode settings will return different sort
* orders for the same set of strings. Locales have specific collation rules,
* and the way in which secondary and tertiary differences are taken into
* account, for example, will result in a different sorting order for same
* strings.
*
Example of use: *
* \code
* UErrorCode status = U_ZERO_ERROR;
* Collator*myCollation = Collator::createInstance(Locale::US,
* status);
* if (U_FAILURE(status)) return;
* myCollation->setStrength(Collator::PRIMARY);
* // result would be Collator::EQUAL ("abc" == "ABC")
* // (no primary difference between "abc" and "ABC")
* UCollationResult result = myCollation->compare("abc", "ABC");
* myCollation->setStrength(Collator::TERTIARY);
* // result would be Collator::LESS ("abc" <<< "ABC")
* // (with tertiary difference between "abc" and "ABC")
* UCollationResult result = myCollation->compare("abc", "ABC");
* \endcode
*
* @param source the source string to be compared with.
* @param target the string that is to be compared with the source string.
* @return Returns a byte value. GREATER if source is greater
* than target; EQUAL if source is equal to target; LESS if source is less
* than target
* @stable
**/
virtual EComparisonResult compare(const UnicodeString& source,
const UnicodeString& target) const = 0;
/**
* Does the same thing as compare but limits the comparison to a specified
* length
*
*
*
* Example of use: *
* \code
* UErrorCode status = U_ZERO_ERROR;
* Collator*myCollation = Collator::createInstance(Locale::US,
* status);
* if (U_FAILURE(status)) return;
* myCollation->setStrength(Collator::PRIMARY);
* // result would be Collator::EQUAL ("abc" == "ABC")
* // (no primary difference between "abc" and "ABC")
* UCollationResult result = myCollation->compare("abc", "ABC",3);
* myCollation->setStrength(Collator::TERTIARY);
* // result would be Collator::LESS (abc" <<< "ABC")
* // (with tertiary difference between "abc" and "ABC")
* UCollationResult result = myCollation->compare("abc", "ABC",3);
* \endcode
*
* @param source the source string to be compared with.
* @param target the string that is to be compared with the source string.
* @param length the length the comparison is limitted to
* @return Returns a byte value. GREATER if source (up to the specified
* length) is greater than target; EQUAL if source (up to specified
* length) is equal to target; LESS if source (up to the specified
* length) is less than target.
*/
virtual EComparisonResult compare(const UnicodeString& source,
const UnicodeString& target,
int32_t length) const = 0;
/**
* The comparison function compares the character data stored in two
* different string arrays. Returns information about whether a string array
* is less than, greater than or equal to another string array.
* Example of use: *
* \code
* UErrorCode status = U_ZERO_ERROR;
* Collator*myCollation = Collator::createInstance(Locale::US,
* status);
* if (U_FAILURE(status)) return;
* myCollation->setStrength(Collator::PRIMARY);
* // result would be Collator::EQUAL ("abc" == "ABC")
* // (no primary difference between "abc" and "ABC")
* UCollationResult result = myCollation->compare(L"abc", 3, L"ABC", 3);
* myCollation->setStrength(Collator::TERTIARY);
* // result would be Collator::LESS (abc" <<< "ABC")
* // (with tertiary difference between "abc" and "ABC")
* UCollationResult result = myCollation->compare(L"abc", 3, L"ABC", 3);
* \endcode
*
* @param source the source string array to be compared with.
* @param sourceLength the length of the source string array. If this value
* is equal to -1, the string array is null-terminated.
* @param target the string that is to be compared with the source string.
* @param targetLength the length of the target string array. If this value
* is equal to -1, the string array is null-terminated.
* @return Returns a byte value. GREATER if source is greater than target;
* EQUAL if source is equal to target; LESS if source is less than
* target
*/
virtual EComparisonResult compare(const UChar* source, int32_t sourceLength,
const UChar* target, int32_t targetLength)
const = 0;
/**
* 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.
* Use CollationKey::equals or CollationKey::compare to compare the * generated sort keys. *
Example of use: *
* \code
* UErrorCode status = U_ZERO_ERROR;
* Collator*myCollation = Collator::createInstance(Locale::US,
* status);
* if (U_FAILURE(status)) return;
* myCollation->setStrength(Collator::PRIMARY);
* UErrorCode key1Status, key2Status;
* CollationKey CollationKey1
* CollationKey1 = myCollation->getCollationKey("abc", CollationKey1,
* key1Status);
* CollationKey CollationKey2
* CollationKey2 = myCollation->getCollationKey("ABC", CollationKey2,
* key2Status);
* if (U_FAILURE(key1Status) || U_FAILURE(key2Status))
* {
* delete myCollation;
* return;
* }
* // Use CollationKey::compare() to compare the sort keys
* // result would be 0 (CollationKey1 == CollationKey2)
* int result = CollationKey1.compare(CollationKey2);
* myCollation->setStrength(Collator::TERTIARY);
* CollationKey1 = myCollation->getCollationKey("abc", CollationKey1,
* key1Status);
* CollationKey2 = myCollation->getCollationKey("ABC", CollationKey2,
* key2Status);
* if (U_FAILURE(key1Status) || U_FAILURE(key2Status))
* {
* delete myCollation;
* return;
* }
* // Use CollationKey::compareTo to compare the collation keys
* // result would be -1 (CollationKey1 < CollationKey2)
* result = CollationKey1.compareTo(CollationKey2);
* delete myCollation;
* \endcode
*
* * If the source string is null, a null collation key will be returned. * @param source the source string to be transformed into a sort key. * @param key the collation key to be filled in * @return the collation key of the string based on the collation rules. * @see CollationKey#compare */ virtual CollationKey& getCollationKey(const UnicodeString& source, CollationKey& key, UErrorCode& status) const = 0; /** * 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. *
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. * @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 * @return the collation key of the string based on the collation rules. * @see CollationKey#compare */ virtual CollationKey& getCollationKey(const UChar*source, int32_t sourceLength, CollationKey& key, UErrorCode& status) const = 0; /** * Generates the hash code for the collation object */ virtual int32_t hashCode(void) const = 0; /** * Convenience method for comparing two strings based on the collation rules. * @param source the source string to be compared with. * @param target the target string to be compared with. * @return true if the first string is greater than the second one, * according to the collation rules. false, otherwise. * @see Collator#compare */ UBool greater(const UnicodeString& source, const UnicodeString& target) const; /** * Convenience method for comparing two strings based on the collation rules. * @param source the source string to be compared with. * @param target the target string to be compared with. * @return true if the first string is greater than or equal to the second * one, according to the collation rules. false, otherwise. * @see Collator#compare */ UBool greaterOrEqual(const UnicodeString& source, const UnicodeString& target) const; /** * Convenience method for comparing two strings based on the collation rules. * @param source the source string to be compared with. * @param target the target string to be compared with. * @return true if the strings are equal according to the collation rules. * false, otherwise. * @see Collator#compare */ UBool equals(const UnicodeString& source, const UnicodeString& target) const; /** * Get the decomposition mode of the Collator object. * @return the decomposition mode * @see Collator#setDecomposition */ virtual Normalizer::EMode getDecomposition(void) const = 0; /** * Set the decomposition mode of the Collator object. success is equal to * U_ILLEGAL_ARGUMENT_ERROR if error occurs. * @param the new decomposition mode * @see Collator#getDecomposition */ virtual void setDecomposition(Normalizer::EMode mode) = 0; /** * Determines the minimum strength that will be use in comparison or * transformation. *
E.g. with strength == SECONDARY, the tertiary difference is ignored *
E.g. with strength == PRIMARY, the secondary and tertiary difference * are ignored. * @return the current comparison level. * @see Collator#setStrength */ virtual ECollationStrength getStrength(void) const = 0; /** * Sets the minimum strength to be used in comparison or transformation. *
Example of use: *
* \code
* UErrorCode status = U_ZERO_ERROR;
* Collator*myCollation = Collator::createInstance(Locale::US,
* status);
* if (U_FAILURE(status)) return;
* myCollation->setStrength(Collator::PRIMARY);
* // result will be "abc" == "ABC"
* // tertiary differences will be ignored
* Collator::ComparisonResult result = myCollation->compare("abc",
* "ABC");
* \endcode
*
* @see Collator#getStrength
* @param newStrength the new comparison level.
* @stable
*/
virtual void setStrength(ECollationStrength newStrength) = 0;
/**
* Get name of the object for the desired Locale, in the desired langauge
* @param objectLocale must be from getAvailableLocales
* @param displayLocale specifies the desired locale for output
* @param name the fill-in parameter of the return value
* @return display-able name of the object for the object locale in the
* desired language
*/
static UnicodeString& getDisplayName(const Locale& objectLocale,
const Locale& displayLocale,
UnicodeString& name);
/**
* Get name of the object for the desired Locale, in the langauge of the
* default locale.
* @param objectLocale must be from getAvailableLocales
* @param name the fill-in parameter of the return value
* @return name of the object for the desired locale in the default language
*/
static UnicodeString& getDisplayName(const Locale& objectLocale,
UnicodeString& name);
/**
* Get the set of Locales for which Collations are installed
* @param count the output parameter of number of elements in the locale list
* @return the list of available locales which collations are installed
*/
static const Locale* getAvailableLocales(int32_t& count);
/**
* Gets the version information for a Collator.
* @param info the version # information, the result will be filled in
*/
void getVersion(UVersionInfo info) const;
/**
* Returns a unique class ID POLYMORPHICALLY. Pure virtual method.
* This method is to implement a simple version of RTTI, since not all C++
* compilers support genuine RTTI. Polymorphic operator==() and clone()
* methods call this method.
* Concrete subclasses of Format must implement getDynamicClassID() and also
* a static method and data member:
* static UClassID getStaticClassID()
* {
* return (UClassID)&fgClassID;
* }
* static char fgClassID;
* @return The class ID for this object. All objects of a given class have
* the same class ID. Objects of other classes have different class
* IDs.
*/
virtual UClassID getDynamicClassID(void) const = 0;
/**
* Universal attribute setter
* @param attr attribute type
* @param value attribute value
* @param status to indicate whether the operation went on smoothly or
* there were errors
*/
virtual void setAttribute(UColAttribute attr, UColAttributeValue value,
UErrorCode &status) = 0;
/**
* Universal attribute getter
* @param attr attribute type
* @param status to indicate whether the operation went on smoothly or
* there were errors
* @return attribute value
*/
virtual UColAttributeValue getAttribute(UColAttribute attr,
UErrorCode &status) = 0;
/**
* Sets the variable top to a collation element value of a string supplied.
* @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: