// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
******************************************************************************
* Copyright (C) 1996-2016, International Business Machines
* Corporation and others. All Rights Reserved.
******************************************************************************
*/
/**
* \file
* \brief C++ API: Collation Service.
*/
/**
* File coll.h
*
* Created by: Helena Shih
*
* Modification History:
*
* Date Name Description
* 02/5/97 aliu Modified createDefault to load collation data from
* binary files when possible. Added related methods
* createCollationFromFile, chopLocale, createPathName.
* 02/11/97 aliu Added members addToCache, findInCache, and fgCache.
* 02/12/97 aliu Modified to create objects from RuleBasedCollator cache.
* Moved cache out of Collation class.
* 02/13/97 aliu Moved several methods out of this class and into
* RuleBasedCollator, with modifications. Modified
* createDefault() to call new RuleBasedCollator(Locale&)
* constructor. General clean up and documentation.
* 02/20/97 helena Added clone, operator==, operator!=, operator=, copy
* constructor and getDynamicClassID.
* 03/25/97 helena Updated with platform independent data types.
* 05/06/97 helena Added memory allocation error detection.
* 06/20/97 helena Java class name change.
* 09/03/97 helena Added createCollationKeyValues().
* 02/10/98 damiba Added compare() with length as parameter.
* 04/23/99 stephen Removed EDecompositionMode, merged with
* Normalizer::EMode.
* 11/02/99 helena Collator performance enhancements. Eliminates the
* UnicodeString construction and special case for NO_OP.
* 11/23/99 srl More performance enhancements. Inlining of
* critical accessors.
* 05/15/00 helena Added version information API.
* 01/29/01 synwee Modified into a C++ wrapper which calls C apis
* (ucol.h).
* 2012-2014 markus Rewritten in C++ again.
*/
#ifndef COLL_H
#define COLL_H
#include "unicode/utypes.h"
#if !UCONFIG_NO_COLLATION
#include "unicode/uobject.h"
#include "unicode/ucol.h"
#include "unicode/unorm.h"
#include "unicode/locid.h"
#include "unicode/uniset.h"
#include "unicode/umisc.h"
#include "unicode/uiter.h"
#include "unicode/stringpiece.h"
U_NAMESPACE_BEGIN
class StringEnumeration;
#if !UCONFIG_NO_SERVICE
/**
* @stable ICU 2.6
*/
class CollatorFactory;
#endif
/**
* @stable ICU 2.0
*/
class CollationKey;
/**
* The <code>Collator</code> class performs locale-sensitive string
* comparison.<br>
* You use this class to build searching and sorting routines for natural
* language text.
* <p>
* <code>Collator</code> is an abstract base class. Subclasses implement
* specific collation strategies. One subclass,
* <code>RuleBasedCollator</code>, is currently provided and is applicable
* to a wide set of languages. Other subclasses may be created to handle more
* specialized needs.
* <p>
* Like other locale-sensitive classes, you can use the static factory method,
* <code>createInstance</code>, to obtain the appropriate
* <code>Collator</code> object for a given locale. You will only need to
* look at the subclasses of <code>Collator</code> if you need to
* understand the details of a particular collation strategy or if you need to
* modify that strategy.
* <p>
* The following example shows how to compare two strings using the
* <code>Collator</code> for the default locale.
* \htmlonly<blockquote>\endhtmlonly
* <pre>
* \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
* </pre>
* \htmlonly</blockquote>\endhtmlonly
* <p>
* You can set a <code>Collator</code>'s <em>strength</em> attribute to
* determine the level of difference considered significant in comparisons.
* Five strengths are provided: <code>PRIMARY</code>, <code>SECONDARY</code>,
* <code>TERTIARY</code>, <code>QUATERNARY</code> and <code>IDENTICAL</code>.
* The exact assignment of strengths to language features is locale dependent.
* 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.
* \htmlonly<blockquote>\endhtmlonly
* <pre>
* \code
* //Get the Collator for US English and set its strength to PRIMARY
* UErrorCode success = U_ZERO_ERROR;
* Collator* usCollator = Collator::createInstance(Locale::getUS(), success);
* usCollator->setStrength(Collator::PRIMARY);
* if (usCollator->compare("abc", "ABC") == 0)
* cout << "'abc' and 'ABC' strings are equivalent with strength PRIMARY" << endl;
* \endcode
* </pre>
* \htmlonly</blockquote>\endhtmlonly
*
* 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.
*
* Another set of APIs returns a <code>CollationKey</code> object that wraps
* the sort key bytes instead of returning the bytes themselves.
* </p>
* <p>
* <strong>Note:</strong> <code>Collator</code>s with different Locale,
* and CollationStrength 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.
* </p>
* @see RuleBasedCollator
* @see CollationKey
* @see CollationElementIterator
* @see Locale
* @see Normalizer2
* @version 2.0 11/15/01
*/
class U_I18N_API Collator : public UObject {
public:
// Collator public enums -----------------------------------------------
/**
* Base letter represents a primary difference. Set comparison level to
* PRIMARY to ignore secondary and tertiary differences.<br>
* Use this to set the strength of a Collator object.<br>
* Example of primary difference, "abc" < "abd"
*
* Diacritical differences on the same base letter represent a secondary
* difference. Set comparison level to SECONDARY to ignore tertiary
* differences. Use this to set the strength of a Collator object.<br>
* Example of secondary difference, "ä" >> "a".
*
* Uppercase and lowercase versions of the same character represents a
* tertiary difference. Set comparison level to TERTIARY to include all
* comparison differences. Use this to set the strength of a Collator
* object.<br>
* Example of tertiary difference, "abc" <<< "ABC".
*
* Two characters are considered "identical" when they have the same unicode
* spellings.<br>
* For example, "ä" == "ä".
*
* UCollationStrength is also used to determine the strength of sort keys
* generated from Collator objects.
* @stable ICU 2.0
*/
enum ECollationStrength
{
PRIMARY = UCOL_PRIMARY, // 0
SECONDARY = UCOL_SECONDARY, // 1
TERTIARY = UCOL_TERTIARY, // 2
QUATERNARY = UCOL_QUATERNARY, // 3
IDENTICAL = UCOL_IDENTICAL // 15
};
// Cannot use #ifndef U_HIDE_DEPRECATED_API for the following, it is
// used by virtual methods that cannot have that conditional.
/**
* LESS is returned if source string is compared to be less than target
* string in the compare() method.
* EQUAL is returned if source string is compared to be equal to target
* string in the compare() method.
* GREATER is returned if source string is compared to be greater than
* target string in the compare() method.
* @see Collator#compare
* @deprecated ICU 2.6. Use C enum UCollationResult defined in ucol.h
*/
enum EComparisonResult
{
LESS = UCOL_LESS, // -1
EQUAL = UCOL_EQUAL, // 0
GREATER = UCOL_GREATER // 1
};
// Collator public destructor -----------------------------------------
/**
* Destructor
* @stable ICU 2.0
*/
virtual ~Collator();
// Collator public methods --------------------------------------------
/**
* Returns TRUE if "other" is the same as "this".
*
* The base class implementation returns TRUE if "other" has the same type/class as "this":
* `typeid(*this) == typeid(other)`.
*
* Subclass implementations should do something like the following:
*
* if (this == &other) { return TRUE; }
* if (!Collator::operator==(other)) { return FALSE; } // not the same class
*
* const MyCollator &o = (const MyCollator&)other;
* (compare this vs. o's subclass fields)
*
* @param other Collator object to be compared
* @return TRUE if other is the same as this.
* @stable ICU 2.0
*/
virtual UBool operator==(const Collator& other) const;
/**
* Returns true if "other" is not the same as "this".
* Calls ! operator==(const Collator&) const which works for all subclasses.
* @param other Collator object to be compared
* @return TRUE if other is not the same as this.
* @stable ICU 2.0
*/
virtual UBool operator!=(const Collator& other) const;
/**
* Makes a copy of this object.
* @return a copy of this object, owned by the caller
* @stable ICU 2.0
*/
virtual Collator* clone(void) const = 0;
/**
* Creates the Collator object for the current default locale.
* The default locale is determined by Locale::getDefault.
* The UErrorCode& err parameter is used to return status information to the user.
* To check whether the construction succeeded or not, you should check the
* value of U_SUCCESS(err). If you wish more detailed information, you can
* check for informational error results which still indicate success.
* U_USING_FALLBACK_ERROR indicates that a fall back locale was used. For
* example, 'de_CH' was requested, but nothing was found there, so 'de' was
* used. U_USING_DEFAULT_ERROR indicates that the default locale data was
* used; neither the requested locale nor any of its fall back locales
* could be found.
* The caller owns the returned object and is responsible for deleting it.
*
* @param err the error code status.
* @return the collation object of the default locale.(for example, en_US)
* @see Locale#getDefault
* @stable ICU 2.0
*/
static Collator* U_EXPORT2 createInstance(UErrorCode& err);
/**
* Gets the collation object for the desired locale. The
* resource of the desired locale will be loaded.
*
* Locale::getRoot() is the base collation table and all other languages are
* built on top of it with additional language-specific modifications.
*
* 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 <a href="http://userguide.icu-project.org/collation/api">User Guide: Collation API</a>.
*
* The UErrorCode& err parameter is used to return status information to the user.
* To check whether the construction succeeded or not, you should check
* the value of U_SUCCESS(err). If you wish more detailed information, you
* can check for informational error results which still indicate success.
* U_USING_FALLBACK_ERROR indicates that a fall back locale was used. For
* example, 'de_CH' was requested, but nothing was found there, so 'de' was
* used. U_USING_DEFAULT_ERROR indicates that the default locale data was
* used; neither the requested locale nor any of its fall back locales
* could be found.
*
* The caller owns the returned object and is responsible for deleting it.
* @param loc The locale ID for which to open a collator.
* @param err the error code status.
* @return the created table-based collation object based on the desired
* locale.
* @see Locale
* @see ResourceLoader
* @stable ICU 2.2
*/
static Collator* U_EXPORT2 createInstance(const Locale& loc, UErrorCode& err);
/**
* The comparison function compares the character data stored in two
* different strings. Returns information about whether a string is less
* than, greater than or equal to another string.
* @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
* @deprecated ICU 2.6 use the overload with UErrorCode &
*/
virtual EComparisonResult compare(const UnicodeString& source,
const UnicodeString& target) const;
/**
* The comparison function compares the character data stored in two
* different strings. Returns information about whether a string is less
* than, greater than or equal to another string.
* @param source the source string to be compared with.
* @param target the string that is to be compared with the source string.
* @param status possible error code
* @return Returns an enum value. UCOL_GREATER if source is greater
* than target; UCOL_EQUAL if source is equal to target; UCOL_LESS if source is less
* than target
* @stable ICU 2.6
*/
virtual UCollationResult compare(const UnicodeString& source,
const UnicodeString& target,
UErrorCode &status) const = 0;
/**
* Does the same thing as compare but limits the comparison to a specified
* length
* @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 limited 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.
* @deprecated ICU 2.6 use the overload with UErrorCode &
*/
virtual EComparisonResult compare(const UnicodeString& source,
const UnicodeString& target,
int32_t length) const;
/**
* Does the same thing as compare but limits the comparison to a specified
* length
* @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 limited to
* @param status possible error code
* @return Returns an enum value. UCOL_GREATER if source (up to the specified
* length) is greater than target; UCOL_EQUAL if source (up to specified
* length) is equal to target; UCOL_LESS if source (up to the specified
* length) is less than target.
* @stable ICU 2.6
*/
virtual UCollationResult compare(const UnicodeString& source,
const UnicodeString& target,
int32_t length,
UErrorCode &status) 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.
* <p>Example of use:
* <pre>
* . char16_t ABC[] = {0x41, 0x42, 0x43, 0}; // = "ABC"
* . char16_t abc[] = {0x61, 0x62, 0x63, 0}; // = "abc"
* . UErrorCode status = U_ZERO_ERROR;
* . Collator *myCollation =
* . Collator::createInstance(Locale::getUS(), status);
* . if (U_FAILURE(status)) return;
* . myCollation->setStrength(Collator::PRIMARY);
* . // result would be Collator::EQUAL ("abc" == "ABC")
* . // (no primary difference between "abc" and "ABC")
* . Collator::EComparisonResult result =
* . myCollation->compare(abc, 3, ABC, 3);
* . myCollation->setStrength(Collator::TERTIARY);
* . // result would be Collator::LESS ("abc" <<< "ABC")
* . // (with tertiary difference between "abc" and "ABC")
* . result = myCollation->compare(abc, 3, ABC, 3);
* </pre>
* @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
* @deprecated ICU 2.6 use the overload with UErrorCode &
*/
virtual EComparisonResult compare(const char16_t* source, int32_t sourceLength,
const char16_t* target, int32_t targetLength)
const;
/**
* 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.
* @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.
* @param status possible error code
* @return Returns an enum value. UCOL_GREATER if source is greater
* than target; UCOL_EQUAL if source is equal to target; UCOL_LESS if source is less
* than target
* @stable ICU 2.6
*/
virtual UCollationResult compare(const char16_t* source, int32_t sourceLength,
const char16_t* target, int32_t targetLength,
UErrorCode &status) const = 0;
/**
* Compares two strings using the Collator.
* Returns whether the first one compares less than/equal to/greater than
* the second one.
* This version takes UCharIterator input.
* @param sIter the first ("source") string iterator
* @param tIter the second ("target") string iterator
* @param status ICU status
* @return UCOL_LESS, UCOL_EQUAL or UCOL_GREATER
* @stable ICU 4.2
*/
virtual UCollationResult compare(UCharIterator &sIter,
UCharIterator &tIter,
UErrorCode &status) const;
/**
* Compares two UTF-8 strings using the Collator.
* Returns whether the first one compares less than/equal to/greater than
* the second one.
* This version takes UTF-8 input.
* Note that a StringPiece can be implicitly constructed
* from a std::string or a NUL-terminated const char * string.
* @param source the first UTF-8 string
* @param target the second UTF-8 string
* @param status ICU status
* @return UCOL_LESS, UCOL_EQUAL or UCOL_GREATER
* @stable ICU 4.2
*/
virtual UCollationResult compareUTF8(const StringPiece &source,
const StringPiece &target,
UErrorCode &status) const;
/**
* 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.
* <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.
* @return the collation key of the string based on the collation rules.
* @see CollationKey#compare
* @stable ICU 2.0
*/
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.
* <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
* @param status the error code status.
* @return the collation key of the string based on the collation rules.
* @see CollationKey#compare
* @stable ICU 2.0
*/
virtual CollationKey& getCollationKey(const char16_t*source,
int32_t sourceLength,
CollationKey& key,
UErrorCode& status) const = 0;
/**
* Generates the hash code for the collation object
* @stable ICU 2.0
*/
virtual int32_t hashCode(void) const = 0;
/**
* Gets the locale of the Collator
*
* @param type can be either requested, valid or actual locale. For more
* information see the definition of ULocDataLocaleType in
* uloc.h
* @param status the error code status.
* @return locale where the collation data lives. If the collator
* was instantiated from rules, locale is empty.
* @deprecated ICU 2.8 This API is under consideration for revision
* in ICU 3.0.
*/
virtual Locale getLocale(ULocDataLocaleType type, UErrorCode& status) 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
* @stable ICU 2.0
*/
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
* @stable ICU 2.0
*/
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
* @stable ICU 2.0
*/
UBool equals(const UnicodeString& source, const UnicodeString& target) const;
/**
* Determines the minimum strength that will be used in comparison or
* transformation.
* <p>E.g. with strength == SECONDARY, the tertiary difference is ignored
* <p>E.g. with strength == PRIMARY, the secondary and tertiary difference
* are ignored.
* @return the current comparison level.
* @see Collator#setStrength
* @deprecated ICU 2.6 Use getAttribute(UCOL_STRENGTH...) instead
*/
virtual ECollationStrength getStrength(void) const;
/**
* Sets the minimum strength to be used in comparison or transformation.
* <p>Example of use:
* <pre>
* \code
* UErrorCode status = U_ZERO_ERROR;
* Collator*myCollation = Collator::createInstance(Locale::getUS(), 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
* </pre>
* @see Collator#getStrength
* @param newStrength the new comparison level.
* @deprecated ICU 2.6 Use setAttribute(UCOL_STRENGTH...) instead
*/
virtual void setStrength(ECollationStrength newStrength);
/**
* Retrieves the reordering codes for this collator.
* @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 status A reference to an error code value, which must not indicate
* a failure before the function call.
* @return The length of the script ordering array.
* @see ucol_setReorderCodes
* @see Collator#getEquivalentReorderCodes
* @see Collator#setReorderCodes
* @see UScriptCode
* @see UColReorderCode
* @stable ICU 4.8
*/
virtual int32_t getReorderCodes(int32_t *dest,
int32_t destCapacity,
UErrorCode& status) const;
/**
* Sets the ordering of scripts for this collator.
*
* <p>The reordering codes are a combination of script codes and reorder codes.
* @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 status error code
* @see ucol_setReorderCodes
* @see Collator#getReorderCodes
* @see Collator#getEquivalentReorderCodes
* @see UScriptCode
* @see UColReorderCode
* @stable ICU 4.8
*/
virtual void setReorderCodes(const int32_t* reorderCodes,
int32_t reorderCodesLength,
UErrorCode& status) ;
/**
* 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 equivalence reordering codes.
* @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 status A reference to an error code value, which must not indicate
* a failure before the function call.
* @return The length of the of the reordering code equivalence array.
* @see ucol_setReorderCodes
* @see Collator#getReorderCodes
* @see Collator#setReorderCodes
* @see UScriptCode
* @see UColReorderCode
* @stable ICU 4.8
*/
static int32_t U_EXPORT2 getEquivalentReorderCodes(int32_t reorderCode,
int32_t* dest,
int32_t destCapacity,
UErrorCode& status);
/**
* Get name of the object for the desired Locale, in the desired language
* @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
* @stable ICU 2.0
*/
static UnicodeString& U_EXPORT2 getDisplayName(const Locale& objectLocale,
const Locale& displayLocale,
UnicodeString& name);
/**
* Get name of the object for the desired Locale, in the language 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
* @stable ICU 2.0
*/
static UnicodeString& U_EXPORT2 getDisplayName(const Locale& objectLocale,
UnicodeString& name);
/**
* Get the set of Locales for which Collations are installed.
*
* <p>Note this does not include locales supported by registered collators.
* If collators might have been registered, use the overload of getAvailableLocales
* that returns a StringEnumeration.</p>
*
* @param count the output parameter of number of elements in the locale list
* @return the list of available locales for which collations are installed
* @stable ICU 2.0
*/
static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
/**
* Return a StringEnumeration over the locales available at the time of the call,
* including registered locales. If a severe error occurs (such as out of memory
* condition) this will return null. If there is no locale data, an empty enumeration
* will be returned.
* @return a StringEnumeration over the locales available at the time of the call
* @stable ICU 2.6
*/
static StringEnumeration* U_EXPORT2 getAvailableLocales(void);
/**
* Create a string enumerator of all possible keywords that are relevant to
* collation. At this point, the only recognized keyword for this
* service is "collation".
* @param status input-output error code
* @return a string enumeration over locale strings. The caller is
* responsible for closing the result.
* @stable ICU 3.0
*/
static StringEnumeration* U_EXPORT2 getKeywords(UErrorCode& status);
/**
* Given a keyword, create a string enumeration of all values
* for that keyword that are currently in use.
* @param keyword a particular keyword as enumerated by
* ucol_getKeywords. If any other keyword is passed in, status is set
* to U_ILLEGAL_ARGUMENT_ERROR.
* @param status input-output error code
* @return a string enumeration over collation keyword values, or NULL
* upon error. The caller is responsible for deleting the result.
* @stable ICU 3.0
*/
static StringEnumeration* U_EXPORT2 getKeywordValues(const char *keyword, UErrorCode& status);
/**
* 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 keyword 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 ICU status
* @return a string enumeration over keyword values for the given key and the locale.
* @stable ICU 4.2
*/
static StringEnumeration* U_EXPORT2 getKeywordValuesForLocale(const char* keyword, const Locale& locale,
UBool commonlyUsed, 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
* may in fact be equivalent, but return different results, due to
* 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
* 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 <a
* href="http://userguide.icu-project.org/locale#TOC-Locales-and-Services">
* Locales and Services</a> section of the ICU User Guide.
* @param keyword a particular keyword as enumerated by
* ucol_getKeywords.
* @param locale the requested locale
* @param isAvailable reference to a fillin parameter that
* indicates whether the requested locale was 'available' to the
* collation service. A locale is defined as 'available' if it
* physically exists within the collation locale data.
* @param status reference to input-output error code
* @return the functionally equivalent collation locale, or the root
* locale upon error.
* @stable ICU 3.0
*/
static Locale U_EXPORT2 getFunctionalEquivalent(const char* keyword, const Locale& locale,
UBool& isAvailable, UErrorCode& status);
#if !UCONFIG_NO_SERVICE
/**
* Register a new Collator. The collator will be adopted.
* Because ICU may choose to cache collators internally, this must be
* called at application startup, prior to any calls to
* Collator::createInstance to avoid undefined behavior.
* @param toAdopt the Collator instance to be adopted
* @param locale the locale with which the collator will be associated
* @param status the in/out status code, no special meanings are assigned
* @return a registry key that can be used to unregister this collator
* @stable ICU 2.6
*/
static URegistryKey U_EXPORT2 registerInstance(Collator* toAdopt, const Locale& locale, UErrorCode& status);
/**
* Register a new CollatorFactory. The factory will be adopted.
* Because ICU may choose to cache collators internally, this must be
* called at application startup, prior to any calls to
* Collator::createInstance to avoid undefined behavior.
* @param toAdopt the CollatorFactory instance to be adopted
* @param status the in/out status code, no special meanings are assigned
* @return a registry key that can be used to unregister this collator
* @stable ICU 2.6
*/
static URegistryKey U_EXPORT2 registerFactory(CollatorFactory* toAdopt, UErrorCode& status);
/**
* Unregister a previously-registered Collator or CollatorFactory
* using the key returned from the register call. Key becomes
* invalid after a successful call and should not be used again.
* The object corresponding to the key will be deleted.
* Because ICU may choose to cache collators internally, this should
* be called during application shutdown, after all calls to
* Collator::createInstance to avoid undefined behavior.
* @param key the registry key returned by a previous call to registerInstance
* @param status the in/out status code, no special meanings are assigned
* @return TRUE if the collator for the key was successfully unregistered
* @stable ICU 2.6
*/
static UBool U_EXPORT2 unregister(URegistryKey key, UErrorCode& status);
#endif /* UCONFIG_NO_SERVICE */
/**
* Gets the version information for a Collator.
* @param info the version # information, the result will be filled in
* @stable ICU 2.0
*/
virtual void getVersion(UVersionInfo info) const = 0;
/**
* 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.
* @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.
* @stable ICU 2.0
*/
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
* @stable ICU 2.2
*/
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
* @stable ICU 2.2
*/
virtual UColAttributeValue getAttribute(UColAttribute attr,
UErrorCode &status) const = 0;
/**
* 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.
*
* The base class implementation sets U_UNSUPPORTED_ERROR.
* @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 errorCode 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.)
* @return *this
* @see getMaxVariable
* @stable ICU 53
*/
virtual Collator &setMaxVariable(UColReorderCode group, UErrorCode &errorCode);
/**
* Returns the maximum reordering group whose characters are affected by UCOL_ALTERNATE_HANDLING.
*
* The base class implementation returns UCOL_REORDER_CODE_PUNCTUATION.
* @return the maximum variable reordering group.
* @see setMaxVariable
* @stable ICU 53
*/
virtual UColReorderCode getMaxVariable() const;
/**
* 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 setMaxVariable().
* @param varTop one or more (if contraction) char16_ts 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: <br>
* U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no such contraction<br>
* U_ILLEGAL_ARGUMENT_ERROR if the variable top is beyond
* the last reordering group supported by setMaxVariable()
* @return variable top primary weight
* @deprecated ICU 53 Call setMaxVariable() instead.
*/
virtual uint32_t setVariableTop(const char16_t *varTop, int32_t len, UErrorCode &status) = 0;
/**
* 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 setMaxVariable().
* @param varTop a UnicodeString size 1 or more (if contraction) of char16_ts to which the variable top should be set
* @param status error code. If error code is set, the return value is undefined. Errors set by this function are: <br>
* U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no such contraction<br>
* U_ILLEGAL_ARGUMENT_ERROR if the variable top is beyond
* the last reordering group supported by setMaxVariable()
* @return variable top primary weight
* @deprecated ICU 53 Call setMaxVariable() instead.
*/
virtual uint32_t setVariableTop(const UnicodeString &varTop, UErrorCode &status) = 0;
/**
* Sets the variable top to the specified primary weight.
*
* 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 setMaxVariable().
* @param varTop primary weight, as returned by setVariableTop or ucol_getVariableTop
* @param status error code
* @deprecated ICU 53 Call setMaxVariable() instead.
*/
virtual void setVariableTop(uint32_t varTop, UErrorCode &status) = 0;
/**
* Gets the variable top value of a Collator.
* @param status error code (not changed by function). If error code is set, the return value is undefined.
* @return the variable top primary weight
* @see getMaxVariable
* @stable ICU 2.0
*/
virtual uint32_t getVariableTop(UErrorCode &status) const = 0;
/**
* Get a UnicodeSet that contains all the characters and sequences
* tailored in this collator.
* @param status error code of the operation
* @return a pointer to a UnicodeSet object containing all the
* code points and sequences that may sort differently than
* in the root collator. The object must be disposed of by using delete
* @stable ICU 2.4
*/
virtual UnicodeSet *getTailoredSet(UErrorCode &status) const;
/**
* Same as clone().
* The base class implementation simply calls clone().
* @return a copy of this object, owned by the caller
* @see clone()
* @deprecated ICU 50 no need to have two methods for cloning
*/
virtual Collator* safeClone(void) const;
/**
* 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.
* @param resultLength length of the result buffer. If if not enough the
* buffer will be filled to capacity.
* @return Number of bytes needed for storing the sort key
* @stable ICU 2.2
*/
virtual int32_t getSortKey(const UnicodeString& source,
uint8_t* result,
int32_t resultLength) const = 0;
/**
* Get the sort key as an array of bytes from a char16_t 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
* function.
* @param result buffer to store result in. If NULL, number of bytes needed
* will be returned.
* @param resultLength length of the result buffer. If if not enough the
* buffer will be filled to capacity.
* @return Number of bytes needed for storing the sort key
* @stable ICU 2.2
*/
virtual int32_t getSortKey(const char16_t*source, int32_t sourceLength,
uint8_t*result, int32_t resultLength) const = 0;
/**
* Produce a bound for a given sortkey and a number of levels.
* Return value is always the number of bytes needed, regardless of
* whether the result buffer was big enough or even valid.<br>
* Resulting bounds can be used to produce a range of strings that are
* between upper and lower bounds. For example, if bounds are produced
* for a sortkey of string "smith", strings between upper and lower
* bounds with one level would include "Smith", "SMITH", "sMiTh".<br>
* There are two upper bounds that can be produced. If UCOL_BOUND_UPPER
* is produced, strings matched would be as above. However, if bound
* produced using UCOL_BOUND_UPPER_LONG is used, the above example will
* also match "Smithsonian" and similar.<br>
* For more on usage, see example in cintltst/capitst.c in procedure
* TestBounds.
* Sort keys may be compared using <TT>strcmp</TT>.
* @param source The source sortkey.
* @param sourceLength The length of source, or -1 if null-terminated.
* (If an unmodified sortkey is passed, it is always null
* terminated).
* @param boundType Type of bound required. It can be UCOL_BOUND_LOWER, which
* produces a lower inclusive bound, UCOL_BOUND_UPPER, that
* produces upper bound that matches strings of the same length
* or UCOL_BOUND_UPPER_LONG that matches strings that have the
* same starting substring as the source string.
* @param noOfLevels Number of levels required in the resulting bound (for most
* uses, the recommended value is 1). See users guide for
* explanation on number of levels a sortkey can have.
* @param result A pointer to a buffer to receive the resulting sortkey.
* @param resultLength The maximum size of result.
* @param status Used for returning error code if something went wrong. If the
* number of levels requested is higher than the number of levels
* in the source key, a warning (U_SORT_KEY_TOO_SHORT_WARNING) is
* issued.
* @return The size needed to fully store the bound.
* @see ucol_keyHashCode
* @stable ICU 2.1
*/
static int32_t U_EXPORT2 getBound(const uint8_t *source,
int32_t sourceLength,
UColBoundMode boundType,
uint32_t noOfLevels,
uint8_t *result,
int32_t resultLength,
UErrorCode &status);
protected:
// Collator protected constructors -------------------------------------
/**
* Default constructor.
* Constructor is different from the old default Collator constructor.
* The task for determing the default collation strength and normalization
* mode is left to the child class.
* @stable ICU 2.0
*/
Collator();
#ifndef U_HIDE_DEPRECATED_API
/**
* Constructor.
* Empty constructor, does not handle the arguments.
* This constructor is done for backward compatibility with 1.7 and 1.8.
* The task for handling the argument collation strength and normalization
* mode is left to the child class.
* @param collationStrength collation strength
* @param decompositionMode
* @deprecated ICU 2.4. Subclasses should use the default constructor
* instead and handle the strength and normalization mode themselves.
*/
Collator(UCollationStrength collationStrength,
UNormalizationMode decompositionMode);
#endif /* U_HIDE_DEPRECATED_API */
/**
* Copy constructor.
* @param other Collator object to be copied from
* @stable ICU 2.0
*/
Collator(const Collator& other);
public:
/**
* Used internally by registration to define the requested and valid locales.
* @param requestedLocale the requested locale
* @param validLocale the valid locale
* @param actualLocale the actual locale
* @internal
*/
virtual void setLocales(const Locale& requestedLocale, const Locale& validLocale, const Locale& actualLocale);
/** Get the short definition string for a collator. This internal 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.
* 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://userguide.icu-project.org/collation/concepts#TOC-Collator-naming-scheme
* This function supports preflighting.
*
* This is internal, and intended to be used with delegate converters.
*
* @param locale a locale that will appear as a collators locale in the resulting
* short string definition. If NULL, the locale will be harvested
* from the collator.
* @param buffer space to hold the resulting string
* @param capacity capacity of the buffer
* @param status for returning errors. All the preflighting errors are featured
* @return length of the resulting string
* @see ucol_openFromShortString
* @see ucol_normalizeShortDefinitionString
* @see ucol_getShortDefinitionString
* @internal
*/
virtual int32_t internalGetShortDefinitionString(const char *locale,
char *buffer,
int32_t capacity,
UErrorCode &status) const;
/**
* Implements ucol_strcollUTF8().
* @internal
*/
virtual UCollationResult internalCompareUTF8(
const char *left, int32_t leftLength,
const char *right, int32_t rightLength,
UErrorCode &errorCode) const;
/**
* Implements ucol_nextSortKeyPart().
* @internal
*/
virtual int32_t
internalNextSortKeyPart(
UCharIterator *iter, uint32_t state[2],
uint8_t *dest, int32_t count, UErrorCode &errorCode) const;
#ifndef U_HIDE_INTERNAL_API
/** @internal */
static inline Collator *fromUCollator(UCollator *uc) {
return reinterpret_cast<Collator *>(uc);
}
/** @internal */
static inline const Collator *fromUCollator(const UCollator *uc) {
return reinterpret_cast<const Collator *>(uc);
}
/** @internal */
inline UCollator *toUCollator() {
return reinterpret_cast<UCollator *>(this);
}
/** @internal */
inline const UCollator *toUCollator() const {
return reinterpret_cast<const UCollator *>(this);
}
#endif // U_HIDE_INTERNAL_API
private:
/**
* Assignment operator. Private for now.
*/
Collator& operator=(const Collator& other);
friend class CFactory;
friend class SimpleCFactory;
friend class ICUCollatorFactory;
friend class ICUCollatorService;
static Collator* makeInstance(const Locale& desiredLocale,
UErrorCode& status);
};
#if !UCONFIG_NO_SERVICE
/**
* A factory, used with registerFactory, the creates multiple collators and provides
* display names for them. A factory supports some number of locales-- these are the
* locales for which it can create collators. The factory can be visible, in which
* case the supported locales will be enumerated by getAvailableLocales, or invisible,
* in which they are not. Invisible locales are still supported, they are just not
* listed by getAvailableLocales.
* <p>
* If standard locale display names are sufficient, Collator instances can
* be registered using registerInstance instead.</p>
* <p>
* Note: if the collators are to be used from C APIs, they must be instances
* of RuleBasedCollator.</p>
*
* @stable ICU 2.6
*/
class U_I18N_API CollatorFactory : public UObject {
public:
/**
* Destructor
* @stable ICU 3.0
*/
virtual ~CollatorFactory();
/**
* Return true if this factory is visible. Default is true.
* If not visible, the locales supported by this factory will not
* be listed by getAvailableLocales.
* @return true if the factory is visible.
* @stable ICU 2.6
*/
virtual UBool visible(void) const;
/**
* Return a collator for the provided locale. If the locale
* is not supported, return NULL.
* @param loc the locale identifying the collator to be created.
* @return a new collator if the locale is supported, otherwise NULL.
* @stable ICU 2.6
*/
virtual Collator* createCollator(const Locale& loc) = 0;
/**
* Return the name of the collator for the objectLocale, localized for the displayLocale.
* If objectLocale is not supported, or the factory is not visible, set the result string
* to bogus.
* @param objectLocale the locale identifying the collator
* @param displayLocale the locale for which the display name of the collator should be localized
* @param result an output parameter for the display name, set to bogus if not supported.
* @return the display name
* @stable ICU 2.6
*/
virtual UnicodeString& getDisplayName(const Locale& objectLocale,
const Locale& displayLocale,
UnicodeString& result);
/**
* Return an array of all the locale names directly supported by this factory.
* The number of names is returned in count. This array is owned by the factory.
* Its contents must never change.
* @param count output parameter for the number of locales supported by the factory
* @param status the in/out error code
* @return a pointer to an array of count UnicodeStrings.
* @stable ICU 2.6
*/
virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) = 0;
};
#endif /* UCONFIG_NO_SERVICE */
// Collator inline methods -----------------------------------------------
U_NAMESPACE_END
#endif /* #if !UCONFIG_NO_COLLATION */
#endif