Collator class performs locale-sensitive string
michael@0: * comparison.
michael@0: * Collator is an abstract base class. Subclasses implement
michael@0: * specific collation strategies. One subclass,
michael@0: * RuleBasedCollator, is currently provided and is applicable
michael@0: * to a wide set of languages. Other subclasses may be created to handle more
michael@0: * specialized needs.
michael@0: *
michael@0: * Like other locale-sensitive classes, you can use the static factory method,
michael@0: * createInstance, to obtain the appropriate
michael@0: * Collator object for a given locale. You will only need to
michael@0: * look at the subclasses of Collator if you need to
michael@0: * understand the details of a particular collation strategy or if you need to
michael@0: * modify that strategy.
michael@0: *
michael@0: * The following example shows how to compare two strings using the
michael@0: * Collator for the default locale.
michael@0: * \htmlonly
\endhtmlonly
michael@0: *
michael@0: * \code
michael@0: * // Compare two strings in the default locale
michael@0: * UErrorCode success = U_ZERO_ERROR;
michael@0: * Collator* myCollator = Collator::createInstance(success);
michael@0: * if (myCollator->compare("abc", "ABC") < 0)
michael@0: * cout << "abc is less than ABC" << endl;
michael@0: * else
michael@0: * cout << "abc is greater than or equal to ABC" << endl;
michael@0: * \endcode
michael@0: *
michael@0: * \htmlonly\endhtmlonly
michael@0: *
michael@0: * You can set a Collator's strength property to
michael@0: * determine the level of difference considered significant in comparisons.
michael@0: * Five strengths are provided: PRIMARY, SECONDARY,
michael@0: * TERTIARY, QUATERNARY and IDENTICAL.
michael@0: * The exact assignment of strengths to language features is locale dependant.
michael@0: * For example, in Czech, "e" and "f" are considered primary differences,
michael@0: * while "e" and "\u00EA" are secondary differences, "e" and "E" are tertiary
michael@0: * differences and "e" and "e" are identical. The following shows how both case
michael@0: * and accents could be ignored for US English.
michael@0: * \htmlonly
\endhtmlonly
michael@0: *
michael@0: * \code
michael@0: * //Get the Collator for US English and set its strength to PRIMARY
michael@0: * UErrorCode success = U_ZERO_ERROR;
michael@0: * Collator* usCollator = Collator::createInstance(Locale::US, success);
michael@0: * usCollator->setStrength(Collator::PRIMARY);
michael@0: * if (usCollator->compare("abc", "ABC") == 0)
michael@0: * cout << "'abc' and 'ABC' strings are equivalent with strength PRIMARY" << endl;
michael@0: * \endcode
michael@0: *
michael@0: * \htmlonly\endhtmlonly
michael@0: *
michael@0: * For comparing strings exactly once, the compare method
michael@0: * provides the best performance. When sorting a list of strings however, it
michael@0: * is generally necessary to compare each string multiple times. In this case,
michael@0: * sort keys provide better performance. The getSortKey methods
michael@0: * convert a string to a series of bytes that can be compared bitwise against
michael@0: * other sort keys using strcmp(). Sort keys are written as
michael@0: * zero-terminated byte strings. They consist of several substrings, one for
michael@0: * each collation strength level, that are delimited by 0x01 bytes.
michael@0: * If the string code points are appended for UCOL_IDENTICAL, then they are
michael@0: * processed for correct code point order comparison and may contain 0x01
michael@0: * bytes but not zero bytes.
michael@0: *
michael@0: * An older set of APIs returns a CollationKey object that wraps
michael@0: * the sort key bytes instead of returning the bytes themselves.
michael@0: * Its use is deprecated, but it is still available for compatibility with
michael@0: * Java.
michael@0: *
michael@0: * Note: Collators with different Locale,
michael@0: * and CollationStrength settings will return different sort
michael@0: * orders for the same set of strings. Locales have specific collation rules,
michael@0: * and the way in which secondary and tertiary differences are taken into
michael@0: * account, for example, will result in a different sorting order for same
michael@0: * strings.
michael@0: *
typeid(*this) == typeid(other).
michael@0: *
michael@0: * Subclass implementations should do something like the following:
michael@0: *
michael@0: * if (this == &other) { return TRUE; }
michael@0: * if (!Collator::operator==(other)) { return FALSE; } // not the same class
michael@0: *
michael@0: * const MyCollator &o = (const MyCollator&)other;
michael@0: * (compare this vs. o's subclass fields)
michael@0: *
michael@0: * @param other Collator object to be compared
michael@0: * @return TRUE if other is the same as this.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: virtual UBool operator==(const Collator& other) const;
michael@0:
michael@0: /**
michael@0: * Returns true if "other" is not the same as "this".
michael@0: * Calls ! operator==(const Collator&) const which works for all subclasses.
michael@0: * @param other Collator object to be compared
michael@0: * @return TRUE if other is not the same as this.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: virtual UBool operator!=(const Collator& other) const;
michael@0:
michael@0: /**
michael@0: * Makes a copy of this object.
michael@0: * @return a copy of this object, owned by the caller
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: virtual Collator* clone(void) const = 0;
michael@0:
michael@0: /**
michael@0: * Creates the Collator object for the current default locale.
michael@0: * The default locale is determined by Locale::getDefault.
michael@0: * The UErrorCode& err parameter is used to return status information to the user.
michael@0: * To check whether the construction succeeded or not, you should check the
michael@0: * value of U_SUCCESS(err). If you wish more detailed information, you can
michael@0: * check for informational error results which still indicate success.
michael@0: * U_USING_FALLBACK_ERROR indicates that a fall back locale was used. For
michael@0: * example, 'de_CH' was requested, but nothing was found there, so 'de' was
michael@0: * used. U_USING_DEFAULT_ERROR indicates that the default locale data was
michael@0: * used; neither the requested locale nor any of its fall back locales
michael@0: * could be found.
michael@0: * The caller owns the returned object and is responsible for deleting it.
michael@0: *
michael@0: * @param err the error code status.
michael@0: * @return the collation object of the default locale.(for example, en_US)
michael@0: * @see Locale#getDefault
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: static Collator* U_EXPORT2 createInstance(UErrorCode& err);
michael@0:
michael@0: /**
michael@0: * Gets the table-based collation object for the desired locale. The
michael@0: * resource of the desired locale will be loaded by ResourceLoader.
michael@0: * Locale::ENGLISH is the base collation table and all other languages are
michael@0: * built on top of it with additional language-specific modifications.
michael@0: * The UErrorCode& err parameter is used to return status information to the user.
michael@0: * To check whether the construction succeeded or not, you should check
michael@0: * the value of U_SUCCESS(err). If you wish more detailed information, you
michael@0: * can check for informational error results which still indicate success.
michael@0: * U_USING_FALLBACK_ERROR indicates that a fall back locale was used. For
michael@0: * example, 'de_CH' was requested, but nothing was found there, so 'de' was
michael@0: * used. U_USING_DEFAULT_ERROR indicates that the default locale data was
michael@0: * used; neither the requested locale nor any of its fall back locales
michael@0: * could be found.
michael@0: * The caller owns the returned object and is responsible for deleting it.
michael@0: * @param loc The locale ID for which to open a collator.
michael@0: * @param err the error code status.
michael@0: * @return the created table-based collation object based on the desired
michael@0: * locale.
michael@0: * @see Locale
michael@0: * @see ResourceLoader
michael@0: * @stable ICU 2.2
michael@0: */
michael@0: static Collator* U_EXPORT2 createInstance(const Locale& loc, UErrorCode& err);
michael@0:
michael@0: #ifdef U_USE_COLLATION_OBSOLETE_2_6
michael@0: /**
michael@0: * Create a Collator with a specific version.
michael@0: * This is the same as createInstance(loc, err) except that getVersion() of
michael@0: * the returned object is guaranteed to be the same as the version
michael@0: * parameter.
michael@0: * This is designed to be used to open the same collator for a given
michael@0: * locale even when ICU is updated.
michael@0: * The same locale and version guarantees the same sort keys and
michael@0: * comparison results.
michael@0: * michael@0: * Note: this API will be removed in a future release. Use michael@0: * createInstance(const Locale&, UErrorCode&) instead.
michael@0: * michael@0: * @param loc The locale ID for which to open a collator. michael@0: * @param version The requested collator version. michael@0: * @param err A reference to a UErrorCode, michael@0: * must not indicate a failure before calling this function. michael@0: * @return A pointer to a Collator, or 0 if an error occurred michael@0: * or a collator with the requested version is not available. michael@0: * michael@0: * @see getVersion michael@0: * @obsolete ICU 2.6 michael@0: */ michael@0: static Collator *createInstance(const Locale &loc, UVersionInfo version, UErrorCode &err); michael@0: #endif michael@0: michael@0: /** michael@0: * The comparison function compares the character data stored in two michael@0: * different strings. Returns information about whether a string is less michael@0: * than, greater than or equal to another string. michael@0: * @param source the source string to be compared with. michael@0: * @param target the string that is to be compared with the source string. michael@0: * @return Returns a byte value. GREATER if source is greater michael@0: * than target; EQUAL if source is equal to target; LESS if source is less michael@0: * than target michael@0: * @deprecated ICU 2.6 use the overload with UErrorCode & michael@0: */ michael@0: virtual EComparisonResult compare(const UnicodeString& source, michael@0: const UnicodeString& target) const; michael@0: michael@0: /** michael@0: * The comparison function compares the character data stored in two michael@0: * different strings. Returns information about whether a string is less michael@0: * than, greater than or equal to another string. michael@0: * @param source the source string to be compared with. michael@0: * @param target the string that is to be compared with the source string. michael@0: * @param status possible error code michael@0: * @return Returns an enum value. UCOL_GREATER if source is greater michael@0: * than target; UCOL_EQUAL if source is equal to target; UCOL_LESS if source is less michael@0: * than target michael@0: * @stable ICU 2.6 michael@0: */ michael@0: virtual UCollationResult compare(const UnicodeString& source, michael@0: const UnicodeString& target, michael@0: UErrorCode &status) const = 0; michael@0: michael@0: /** michael@0: * Does the same thing as compare but limits the comparison to a specified michael@0: * length michael@0: * @param source the source string to be compared with. michael@0: * @param target the string that is to be compared with the source string. michael@0: * @param length the length the comparison is limited to michael@0: * @return Returns a byte value. GREATER if source (up to the specified michael@0: * length) is greater than target; EQUAL if source (up to specified michael@0: * length) is equal to target; LESS if source (up to the specified michael@0: * length) is less than target. michael@0: * @deprecated ICU 2.6 use the overload with UErrorCode & michael@0: */ michael@0: virtual EComparisonResult compare(const UnicodeString& source, michael@0: const UnicodeString& target, michael@0: int32_t length) const; michael@0: michael@0: /** michael@0: * Does the same thing as compare but limits the comparison to a specified michael@0: * length michael@0: * @param source the source string to be compared with. michael@0: * @param target the string that is to be compared with the source string. michael@0: * @param length the length the comparison is limited to michael@0: * @param status possible error code michael@0: * @return Returns an enum value. UCOL_GREATER if source (up to the specified michael@0: * length) is greater than target; UCOL_EQUAL if source (up to specified michael@0: * length) is equal to target; UCOL_LESS if source (up to the specified michael@0: * length) is less than target. michael@0: * @stable ICU 2.6 michael@0: */ michael@0: virtual UCollationResult compare(const UnicodeString& source, michael@0: const UnicodeString& target, michael@0: int32_t length, michael@0: UErrorCode &status) const = 0; michael@0: michael@0: /** michael@0: * The comparison function compares the character data stored in two michael@0: * different string arrays. Returns information about whether a string array michael@0: * is less than, greater than or equal to another string array. michael@0: *Example of use: michael@0: *
michael@0: * . UChar ABC[] = {0x41, 0x42, 0x43, 0}; // = "ABC"
michael@0: * . UChar abc[] = {0x61, 0x62, 0x63, 0}; // = "abc"
michael@0: * . UErrorCode status = U_ZERO_ERROR;
michael@0: * . Collator *myCollation =
michael@0: * . Collator::createInstance(Locale::US, status);
michael@0: * . if (U_FAILURE(status)) return;
michael@0: * . myCollation->setStrength(Collator::PRIMARY);
michael@0: * . // result would be Collator::EQUAL ("abc" == "ABC")
michael@0: * . // (no primary difference between "abc" and "ABC")
michael@0: * . Collator::EComparisonResult result =
michael@0: * . myCollation->compare(abc, 3, ABC, 3);
michael@0: * . myCollation->setStrength(Collator::TERTIARY);
michael@0: * . // result would be Collator::LESS ("abc" <<< "ABC")
michael@0: * . // (with tertiary difference between "abc" and "ABC")
michael@0: * . result = myCollation->compare(abc, 3, ABC, 3);
michael@0: *
michael@0: * @param source the source string array to be compared with.
michael@0: * @param sourceLength the length of the source string array. If this value
michael@0: * is equal to -1, the string array is null-terminated.
michael@0: * @param target the string that is to be compared with the source string.
michael@0: * @param targetLength the length of the target string array. If this value
michael@0: * is equal to -1, the string array is null-terminated.
michael@0: * @return Returns a byte value. GREATER if source is greater than target;
michael@0: * EQUAL if source is equal to target; LESS if source is less than
michael@0: * target
michael@0: * @deprecated ICU 2.6 use the overload with UErrorCode &
michael@0: */
michael@0: virtual EComparisonResult compare(const UChar* source, int32_t sourceLength,
michael@0: const UChar* target, int32_t targetLength)
michael@0: const;
michael@0:
michael@0: /**
michael@0: * The comparison function compares the character data stored in two
michael@0: * different string arrays. Returns information about whether a string array
michael@0: * is less than, greater than or equal to another string array.
michael@0: * @param source the source string array to be compared with.
michael@0: * @param sourceLength the length of the source string array. If this value
michael@0: * is equal to -1, the string array is null-terminated.
michael@0: * @param target the string that is to be compared with the source string.
michael@0: * @param targetLength the length of the target string array. If this value
michael@0: * is equal to -1, the string array is null-terminated.
michael@0: * @param status possible error code
michael@0: * @return Returns an enum value. UCOL_GREATER if source is greater
michael@0: * than target; UCOL_EQUAL if source is equal to target; UCOL_LESS if source is less
michael@0: * than target
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: virtual UCollationResult compare(const UChar* source, int32_t sourceLength,
michael@0: const UChar* target, int32_t targetLength,
michael@0: UErrorCode &status) const = 0;
michael@0:
michael@0: /**
michael@0: * Compares two strings using the Collator.
michael@0: * Returns whether the first one compares less than/equal to/greater than
michael@0: * the second one.
michael@0: * This version takes UCharIterator input.
michael@0: * @param sIter the first ("source") string iterator
michael@0: * @param tIter the second ("target") string iterator
michael@0: * @param status ICU status
michael@0: * @return UCOL_LESS, UCOL_EQUAL or UCOL_GREATER
michael@0: * @stable ICU 4.2
michael@0: */
michael@0: virtual UCollationResult compare(UCharIterator &sIter,
michael@0: UCharIterator &tIter,
michael@0: UErrorCode &status) const;
michael@0:
michael@0: /**
michael@0: * Compares two UTF-8 strings using the Collator.
michael@0: * Returns whether the first one compares less than/equal to/greater than
michael@0: * the second one.
michael@0: * This version takes UTF-8 input.
michael@0: * Note that a StringPiece can be implicitly constructed
michael@0: * from a std::string or a NUL-terminated const char * string.
michael@0: * @param source the first UTF-8 string
michael@0: * @param target the second UTF-8 string
michael@0: * @param status ICU status
michael@0: * @return UCOL_LESS, UCOL_EQUAL or UCOL_GREATER
michael@0: * @stable ICU 4.2
michael@0: */
michael@0: virtual UCollationResult compareUTF8(const StringPiece &source,
michael@0: const StringPiece &target,
michael@0: UErrorCode &status) const;
michael@0:
michael@0: /**
michael@0: * Transforms the string into a series of characters that can be compared
michael@0: * with CollationKey::compareTo. It is not possible to restore the original
michael@0: * string from the chars in the sort key. The generated sort key handles
michael@0: * only a limited number of ignorable characters.
michael@0: * Use CollationKey::equals or CollationKey::compare to compare the michael@0: * generated sort keys. michael@0: * If the source string is null, a null collation key will be returned. michael@0: * @param source the source string to be transformed into a sort key. michael@0: * @param key the collation key to be filled in michael@0: * @param status the error code status. michael@0: * @return the collation key of the string based on the collation rules. michael@0: * @see CollationKey#compare michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual CollationKey& getCollationKey(const UnicodeString& source, michael@0: CollationKey& key, michael@0: UErrorCode& status) const = 0; michael@0: michael@0: /** michael@0: * Transforms the string into a series of characters that can be compared michael@0: * with CollationKey::compareTo. It is not possible to restore the original michael@0: * string from the chars in the sort key. The generated sort key handles michael@0: * only a limited number of ignorable characters. michael@0: *
Use CollationKey::equals or CollationKey::compare to compare the michael@0: * generated sort keys. michael@0: *
If the source string is null, a null collation key will be returned. michael@0: * @param source the source string to be transformed into a sort key. michael@0: * @param sourceLength length of the collation key michael@0: * @param key the collation key to be filled in michael@0: * @param status the error code status. michael@0: * @return the collation key of the string based on the collation rules. michael@0: * @see CollationKey#compare michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual CollationKey& getCollationKey(const UChar*source, michael@0: int32_t sourceLength, michael@0: CollationKey& key, michael@0: UErrorCode& status) const = 0; michael@0: /** michael@0: * Generates the hash code for the collation object michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual int32_t hashCode(void) const = 0; michael@0: michael@0: /** michael@0: * Gets the locale of the Collator michael@0: * michael@0: * @param type can be either requested, valid or actual locale. For more michael@0: * information see the definition of ULocDataLocaleType in michael@0: * uloc.h michael@0: * @param status the error code status. michael@0: * @return locale where the collation data lives. If the collator michael@0: * was instantiated from rules, locale is empty. michael@0: * @deprecated ICU 2.8 This API is under consideration for revision michael@0: * in ICU 3.0. michael@0: */ michael@0: virtual Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const = 0; michael@0: michael@0: /** michael@0: * Convenience method for comparing two strings based on the collation rules. michael@0: * @param source the source string to be compared with. michael@0: * @param target the target string to be compared with. michael@0: * @return true if the first string is greater than the second one, michael@0: * according to the collation rules. false, otherwise. michael@0: * @see Collator#compare michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UBool greater(const UnicodeString& source, const UnicodeString& target) michael@0: const; michael@0: michael@0: /** michael@0: * Convenience method for comparing two strings based on the collation rules. michael@0: * @param source the source string to be compared with. michael@0: * @param target the target string to be compared with. michael@0: * @return true if the first string is greater than or equal to the second michael@0: * one, according to the collation rules. false, otherwise. michael@0: * @see Collator#compare michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UBool greaterOrEqual(const UnicodeString& source, michael@0: const UnicodeString& target) const; michael@0: michael@0: /** michael@0: * Convenience method for comparing two strings based on the collation rules. michael@0: * @param source the source string to be compared with. michael@0: * @param target the target string to be compared with. michael@0: * @return true if the strings are equal according to the collation rules. michael@0: * false, otherwise. michael@0: * @see Collator#compare michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UBool equals(const UnicodeString& source, const UnicodeString& target) const; michael@0: michael@0: /** michael@0: * Determines the minimum strength that will be used in comparison or michael@0: * transformation. michael@0: *
E.g. with strength == SECONDARY, the tertiary difference is ignored michael@0: *
E.g. with strength == PRIMARY, the secondary and tertiary difference michael@0: * are ignored. michael@0: * @return the current comparison level. michael@0: * @see Collator#setStrength michael@0: * @deprecated ICU 2.6 Use getAttribute(UCOL_STRENGTH...) instead michael@0: */ michael@0: virtual ECollationStrength getStrength(void) const; michael@0: michael@0: /** michael@0: * Sets the minimum strength to be used in comparison or transformation. michael@0: *
Example of use: michael@0: *
michael@0: * \code
michael@0: * UErrorCode status = U_ZERO_ERROR;
michael@0: * Collator*myCollation = Collator::createInstance(Locale::US, status);
michael@0: * if (U_FAILURE(status)) return;
michael@0: * myCollation->setStrength(Collator::PRIMARY);
michael@0: * // result will be "abc" == "ABC"
michael@0: * // tertiary differences will be ignored
michael@0: * Collator::ComparisonResult result = myCollation->compare("abc", "ABC");
michael@0: * \endcode
michael@0: *
michael@0: * @see Collator#getStrength
michael@0: * @param newStrength the new comparison level.
michael@0: * @deprecated ICU 2.6 Use setAttribute(UCOL_STRENGTH...) instead
michael@0: */
michael@0: virtual void setStrength(ECollationStrength newStrength);
michael@0:
michael@0: /**
michael@0: * Retrieves the reordering codes for this collator.
michael@0: * @param dest The array to fill with the script ordering.
michael@0: * @param destCapacity The length of dest. If it is 0, then dest may be NULL and the function
michael@0: * will only return the length of the result without writing any of the result string (pre-flighting).
michael@0: * @param status A reference to an error code value, which must not indicate
michael@0: * a failure before the function call.
michael@0: * @return The length of the script ordering array.
michael@0: * @see ucol_setReorderCodes
michael@0: * @see Collator#getEquivalentReorderCodes
michael@0: * @see Collator#setReorderCodes
michael@0: * @see UScriptCode
michael@0: * @see UColReorderCode
michael@0: * @stable ICU 4.8
michael@0: */
michael@0: virtual int32_t getReorderCodes(int32_t *dest,
michael@0: int32_t destCapacity,
michael@0: UErrorCode& status) const;
michael@0:
michael@0: /**
michael@0: * Sets the ordering of scripts for this collator.
michael@0: *
michael@0: * The reordering codes are a combination of script codes and reorder codes. michael@0: * @param reorderCodes An array of script codes in the new order. This can be NULL if the michael@0: * length is also set to 0. An empty array will clear any reordering codes on the collator. michael@0: * @param reorderCodesLength The length of reorderCodes. michael@0: * @param status error code michael@0: * @see Collator#getReorderCodes michael@0: * @see Collator#getEquivalentReorderCodes michael@0: * @see UScriptCode michael@0: * @see UColReorderCode michael@0: * @stable ICU 4.8 michael@0: */ michael@0: virtual void setReorderCodes(const int32_t* reorderCodes, michael@0: int32_t reorderCodesLength, michael@0: UErrorCode& status) ; michael@0: michael@0: /** michael@0: * Retrieves the reorder codes that are grouped with the given reorder code. Some reorder michael@0: * codes will be grouped and must reorder together. michael@0: * @param reorderCode The reorder code to determine equivalence for. michael@0: * @param dest The array to fill with the script equivalene reordering codes. michael@0: * @param destCapacity The length of dest. If it is 0, then dest may be NULL and the michael@0: * function will only return the length of the result without writing any of the result michael@0: * string (pre-flighting). michael@0: * @param status A reference to an error code value, which must not indicate michael@0: * a failure before the function call. michael@0: * @return The length of the of the reordering code equivalence array. michael@0: * @see ucol_setReorderCodes michael@0: * @see Collator#getReorderCodes michael@0: * @see Collator#setReorderCodes michael@0: * @see UScriptCode michael@0: * @see UColReorderCode michael@0: * @stable ICU 4.8 michael@0: */ michael@0: static int32_t U_EXPORT2 getEquivalentReorderCodes(int32_t reorderCode, michael@0: int32_t* dest, michael@0: int32_t destCapacity, michael@0: UErrorCode& status); michael@0: michael@0: /** michael@0: * Get name of the object for the desired Locale, in the desired langauge michael@0: * @param objectLocale must be from getAvailableLocales michael@0: * @param displayLocale specifies the desired locale for output michael@0: * @param name the fill-in parameter of the return value michael@0: * @return display-able name of the object for the object locale in the michael@0: * desired language michael@0: * @stable ICU 2.0 michael@0: */ michael@0: static UnicodeString& U_EXPORT2 getDisplayName(const Locale& objectLocale, michael@0: const Locale& displayLocale, michael@0: UnicodeString& name); michael@0: michael@0: /** michael@0: * Get name of the object for the desired Locale, in the langauge of the michael@0: * default locale. michael@0: * @param objectLocale must be from getAvailableLocales michael@0: * @param name the fill-in parameter of the return value michael@0: * @return name of the object for the desired locale in the default language michael@0: * @stable ICU 2.0 michael@0: */ michael@0: static UnicodeString& U_EXPORT2 getDisplayName(const Locale& objectLocale, michael@0: UnicodeString& name); michael@0: michael@0: /** michael@0: * Get the set of Locales for which Collations are installed. michael@0: * michael@0: *
Note this does not include locales supported by registered collators. michael@0: * If collators might have been registered, use the overload of getAvailableLocales michael@0: * that returns a StringEnumeration.
michael@0: * michael@0: * @param count the output parameter of number of elements in the locale list michael@0: * @return the list of available locales for which collations are installed michael@0: * @stable ICU 2.0 michael@0: */ michael@0: static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count); michael@0: michael@0: /** michael@0: * Return a StringEnumeration over the locales available at the time of the call, michael@0: * including registered locales. If a severe error occurs (such as out of memory michael@0: * condition) this will return null. If there is no locale data, an empty enumeration michael@0: * will be returned. michael@0: * @return a StringEnumeration over the locales available at the time of the call michael@0: * @stable ICU 2.6 michael@0: */ michael@0: static StringEnumeration* U_EXPORT2 getAvailableLocales(void); michael@0: michael@0: /** michael@0: * Create a string enumerator of all possible keywords that are relevant to michael@0: * collation. At this point, the only recognized keyword for this michael@0: * service is "collation". michael@0: * @param status input-output error code michael@0: * @return a string enumeration over locale strings. The caller is michael@0: * responsible for closing the result. michael@0: * @stable ICU 3.0 michael@0: */ michael@0: static StringEnumeration* U_EXPORT2 getKeywords(UErrorCode& status); michael@0: michael@0: /** michael@0: * Given a keyword, create a string enumeration of all values michael@0: * for that keyword that are currently in use. michael@0: * @param keyword a particular keyword as enumerated by michael@0: * ucol_getKeywords. If any other keyword is passed in, status is set michael@0: * to U_ILLEGAL_ARGUMENT_ERROR. michael@0: * @param status input-output error code michael@0: * @return a string enumeration over collation keyword values, or NULL michael@0: * upon error. The caller is responsible for deleting the result. michael@0: * @stable ICU 3.0 michael@0: */ michael@0: static StringEnumeration* U_EXPORT2 getKeywordValues(const char *keyword, UErrorCode& status); michael@0: michael@0: /** michael@0: * Given a key and a locale, returns an array of string values in a preferred michael@0: * order that would make a difference. These are all and only those values where michael@0: * the open (creation) of the service with the locale formed from the input locale michael@0: * plus input keyword and that value has different behavior than creation with the michael@0: * input locale alone. michael@0: * @param keyword one of the keys supported by this service. For now, only michael@0: * "collation" is supported. michael@0: * @param locale the locale michael@0: * @param commonlyUsed if set to true it will return only commonly used values michael@0: * with the given locale in preferred order. Otherwise, michael@0: * it will return all the available values for the locale. michael@0: * @param status ICU status michael@0: * @return a string enumeration over keyword values for the given key and the locale. michael@0: * @stable ICU 4.2 michael@0: */ michael@0: static StringEnumeration* U_EXPORT2 getKeywordValuesForLocale(const char* keyword, const Locale& locale, michael@0: UBool commonlyUsed, UErrorCode& status); michael@0: michael@0: /** michael@0: * Return the functionally equivalent locale for the given michael@0: * requested locale, with respect to given keyword, for the michael@0: * collation service. If two locales return the same result, then michael@0: * collators instantiated for these locales will behave michael@0: * equivalently. The converse is not always true; two collators michael@0: * may in fact be equivalent, but return different results, due to michael@0: * internal details. The return result has no other meaning than michael@0: * that stated above, and implies nothing as to the relationship michael@0: * between the two locales. This is intended for use by michael@0: * applications who wish to cache collators, or otherwise reuse michael@0: * collators when possible. The functional equivalent may change michael@0: * over time. For more information, please see the michael@0: * Locales and Services section of the ICU User Guide. michael@0: * @param keyword a particular keyword as enumerated by michael@0: * ucol_getKeywords. michael@0: * @param locale the requested locale michael@0: * @param isAvailable reference to a fillin parameter that michael@0: * indicates whether the requested locale was 'available' to the michael@0: * collation service. A locale is defined as 'available' if it michael@0: * physically exists within the collation locale data. michael@0: * @param status reference to input-output error code michael@0: * @return the functionally equivalent collation locale, or the root michael@0: * locale upon error. michael@0: * @stable ICU 3.0 michael@0: */ michael@0: static Locale U_EXPORT2 getFunctionalEquivalent(const char* keyword, const Locale& locale, michael@0: UBool& isAvailable, UErrorCode& status); michael@0: michael@0: #if !UCONFIG_NO_SERVICE michael@0: /** michael@0: * Register a new Collator. The collator will be adopted. michael@0: * @param toAdopt the Collator instance to be adopted michael@0: * @param locale the locale with which the collator will be associated michael@0: * @param status the in/out status code, no special meanings are assigned michael@0: * @return a registry key that can be used to unregister this collator michael@0: * @stable ICU 2.6 michael@0: */ michael@0: static URegistryKey U_EXPORT2 registerInstance(Collator* toAdopt, const Locale& locale, UErrorCode& status); michael@0: michael@0: /** michael@0: * Register a new CollatorFactory. The factory will be adopted. michael@0: * @param toAdopt the CollatorFactory instance to be adopted michael@0: * @param status the in/out status code, no special meanings are assigned michael@0: * @return a registry key that can be used to unregister this collator michael@0: * @stable ICU 2.6 michael@0: */ michael@0: static URegistryKey U_EXPORT2 registerFactory(CollatorFactory* toAdopt, UErrorCode& status); michael@0: michael@0: /** michael@0: * Unregister a previously-registered Collator or CollatorFactory michael@0: * using the key returned from the register call. Key becomes michael@0: * invalid after a successful call and should not be used again. michael@0: * The object corresponding to the key will be deleted. michael@0: * @param key the registry key returned by a previous call to registerInstance michael@0: * @param status the in/out status code, no special meanings are assigned michael@0: * @return TRUE if the collator for the key was successfully unregistered michael@0: * @stable ICU 2.6 michael@0: */ michael@0: static UBool U_EXPORT2 unregister(URegistryKey key, UErrorCode& status); michael@0: #endif /* UCONFIG_NO_SERVICE */ michael@0: michael@0: /** michael@0: * Gets the version information for a Collator. michael@0: * @param info the version # information, the result will be filled in michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void getVersion(UVersionInfo info) const = 0; michael@0: michael@0: /** michael@0: * Returns a unique class ID POLYMORPHICALLY. Pure virtual method. michael@0: * This method is to implement a simple version of RTTI, since not all C++ michael@0: * compilers support genuine RTTI. Polymorphic operator==() and clone() michael@0: * methods call this method. michael@0: * @return The class ID for this object. All objects of a given class have michael@0: * the same class ID. Objects of other classes have different class michael@0: * IDs. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual UClassID getDynamicClassID(void) const = 0; michael@0: michael@0: /** michael@0: * Universal attribute setter michael@0: * @param attr attribute type michael@0: * @param value attribute value michael@0: * @param status to indicate whether the operation went on smoothly or michael@0: * there were errors michael@0: * @stable ICU 2.2 michael@0: */ michael@0: virtual void setAttribute(UColAttribute attr, UColAttributeValue value, michael@0: UErrorCode &status) = 0; michael@0: michael@0: /** michael@0: * Universal attribute getter michael@0: * @param attr attribute type michael@0: * @param status to indicate whether the operation went on smoothly or michael@0: * there were errors michael@0: * @return attribute value michael@0: * @stable ICU 2.2 michael@0: */ michael@0: virtual UColAttributeValue getAttribute(UColAttribute attr, michael@0: UErrorCode &status) const = 0; michael@0: michael@0: /** michael@0: * Sets the variable top to a collation element value of a string supplied. michael@0: * @param varTop one or more (if contraction) UChars to which the variable top should be set michael@0: * @param len length of variable top string. If -1 it is considered to be zero terminated. michael@0: * @param status error code. If error code is set, the return value is undefined. Errors set by this function are:michael@0: * If standard locale display names are sufficient, Collator instances can michael@0: * be registered using registerInstance instead.
michael@0: *michael@0: * Note: if the collators are to be used from C APIs, they must be instances michael@0: * of RuleBasedCollator.
michael@0: * michael@0: * @stable ICU 2.6 michael@0: */ michael@0: class U_I18N_API CollatorFactory : public UObject { michael@0: public: michael@0: michael@0: /** michael@0: * Destructor michael@0: * @stable ICU 3.0 michael@0: */ michael@0: virtual ~CollatorFactory(); michael@0: michael@0: /** michael@0: * Return true if this factory is visible. Default is true. michael@0: * If not visible, the locales supported by this factory will not michael@0: * be listed by getAvailableLocales. michael@0: * @return true if the factory is visible. michael@0: * @stable ICU 2.6 michael@0: */ michael@0: virtual UBool visible(void) const; michael@0: michael@0: /** michael@0: * Return a collator for the provided locale. If the locale michael@0: * is not supported, return NULL. michael@0: * @param loc the locale identifying the collator to be created. michael@0: * @return a new collator if the locale is supported, otherwise NULL. michael@0: * @stable ICU 2.6 michael@0: */ michael@0: virtual Collator* createCollator(const Locale& loc) = 0; michael@0: michael@0: /** michael@0: * Return the name of the collator for the objectLocale, localized for the displayLocale. michael@0: * If objectLocale is not supported, or the factory is not visible, set the result string michael@0: * to bogus. michael@0: * @param objectLocale the locale identifying the collator michael@0: * @param displayLocale the locale for which the display name of the collator should be localized michael@0: * @param result an output parameter for the display name, set to bogus if not supported. michael@0: * @return the display name michael@0: * @stable ICU 2.6 michael@0: */ michael@0: virtual UnicodeString& getDisplayName(const Locale& objectLocale, michael@0: const Locale& displayLocale, michael@0: UnicodeString& result); michael@0: michael@0: /** michael@0: * Return an array of all the locale names directly supported by this factory. michael@0: * The number of names is returned in count. This array is owned by the factory. michael@0: * Its contents must never change. michael@0: * @param count output parameter for the number of locales supported by the factory michael@0: * @param status the in/out error code michael@0: * @return a pointer to an array of count UnicodeStrings. michael@0: * @stable ICU 2.6 michael@0: */ michael@0: virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) = 0; michael@0: }; michael@0: #endif /* UCONFIG_NO_SERVICE */ michael@0: michael@0: // Collator inline methods ----------------------------------------------- michael@0: michael@0: U_NAMESPACE_END michael@0: michael@0: #endif /* #if !UCONFIG_NO_COLLATION */ michael@0: michael@0: #endif