/*
******************************************************************************
-* Copyright (C) 1996-2004, International Business Machines *
+* Copyright (C) 1996-2012, International Business Machines *
* Corporation and others. All Rights Reserved. *
******************************************************************************
*/
+/**
+ * \file
+ * \brief C++ API: Collation Service.
+ */
+
/**
* File coll.h
*
#include "unicode/normlzr.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
- */
-typedef const void* URegistryKey;
-
/**
* @stable ICU 2.6
*/
* <em>Important: </em>The ICU collation service has been reimplemented
* in order to achieve better performance and UCA compliance.
* For details, see the
-* <a href="http://oss.software.ibm.com/cvs/icu/~checkout~/icuhtml/design/collation/ICU_collation_design.htm">
+* <a href="http://source.icu-project.org/repos/icu/icuhtml/trunk/design/collation/ICU_collation_design.htm">
* collation design document</a>.
* <p>
* <code>Collator</code> is an abstract base class. Subclasses implement
* 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".
+ * 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
*
* Two characters are considered "identical" when they have the same unicode
* spellings.<br>
- * For example, "ä" == "ä".
+ * For example, "ä" == "ä".
*
* UCollationStrength is also used to determine the strength of sort keys
* generated from Collator objects.
*/
enum ECollationStrength
{
- PRIMARY = 0,
- SECONDARY = 1,
- TERTIARY = 2,
- QUATERNARY = 3,
- IDENTICAL = 15
+ PRIMARY = UCOL_PRIMARY, // 0
+ SECONDARY = UCOL_SECONDARY, // 1
+ TERTIARY = UCOL_TERTIARY, // 2
+ QUATERNARY = UCOL_QUATERNARY, // 3
+ IDENTICAL = UCOL_IDENTICAL // 15
};
/**
*/
enum EComparisonResult
{
- LESS = -1,
- EQUAL = 0,
- GREATER = 1
+ LESS = UCOL_LESS, // -1
+ EQUAL = UCOL_EQUAL, // 0
+ GREATER = UCOL_GREATER // 1
};
// Collator public destructor -----------------------------------------
// Collator public methods --------------------------------------------
/**
- * Returns true if "other" is the same as "this"
+ * Returns TRUE if "other" is the same as "this".
+ *
+ * The base class implementation returns TRUE if "other" has the same type/class as "this":
+ * <code>typeid(*this) == typeid(other)</code>.
+ *
+ * Subclass implementations should do something like the following:
+ * <pre>
+ * 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)
+ * </pre>
* @param other Collator object to be compared
- * @return true if other is the same as this.
+ * @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.
+ * @return TRUE if other is not the same as this.
* @stable ICU 2.0
*/
virtual UBool operator!=(const Collator& other) const;
/**
- * Makes a shallow copy of the current object.
- * @return a copy of this object
+ * 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;
* 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>
+ * . UChar ABC[] = {0x41, 0x42, 0x43, 0}; // = "ABC"
+ * . UChar abc[] = {0x61, 0x62, 0x63, 0}; // = "abc"
+ * . 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")
+ * . 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.
const UChar* 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
* @param status the error code status.
* @return the collation key of the string based on the collation rules.
* @see CollationKey#compare
- * @deprecated ICU 2.8 Use getSortKey(...) instead
+ * @stable ICU 2.0
*/
virtual CollationKey& getCollationKey(const UnicodeString& source,
CollationKey& key,
* @param status the error code status.
* @return the collation key of the string based on the collation rules.
* @see CollationKey#compare
- * @deprecated ICU 2.8 Use getSortKey(...) instead
+ * @stable ICU 2.0
*/
virtual CollationKey& getCollationKey(const UChar*source,
int32_t sourceLength,
* @deprecated ICU 2.8 This API is under consideration for revision
* in ICU 3.0.
*/
- virtual const Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const = 0;
+ virtual Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const = 0;
/**
* Convenience method for comparing two strings based on the collation rules.
UBool equals(const UnicodeString& source, const UnicodeString& target) const;
/**
- * Determines the minimum strength that will be use in comparison or
+ * 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
* @see Collator#setStrength
* @deprecated ICU 2.6 Use getAttribute(UCOL_STRENGTH...) instead
*/
- virtual ECollationStrength getStrength(void) const = 0;
+ virtual ECollationStrength getStrength(void) const;
/**
* Sets the minimum strength to be used in comparison or transformation.
* @param newStrength the new comparison level.
* @deprecated ICU 2.6 Use setAttribute(UCOL_STRENGTH...) instead
*/
- virtual void setStrength(ECollationStrength newStrength) = 0;
+ 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 of the result string (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 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.
+ * @param reorderCode The reorder code to determine equivalence for.
+ * @param dest The array to fill with the script equivalene 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 of the result
+ * string (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 langauge
*/
static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
-#if !UCONFIG_NO_SERVICE
/**
* 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
* @stable ICU 2.6
*/
static StringEnumeration* U_EXPORT2 getAvailableLocales(void);
-#endif
/**
* Create a string enumerator of all possible keywords that are relevant to
* @param status input-output error code
* @return a string enumeration over locale strings. The caller is
* responsible for closing the result.
- * @draft ICU 3.0
+ * @stable ICU 3.0
*/
static StringEnumeration* U_EXPORT2 getKeywords(UErrorCode& status);
* @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.
- * @draft ICU 3.0
+ * @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
* 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://oss.software.ibm.com/icu/userguide/locale.html#services">
+ * href="http://icu-project.org/userguide/locale.html#services">
* Locales and Services</a> section of the ICU User Guide.
* @param keyword a particular keyword as enumerated by
* ucol_getKeywords.
* @param status reference to input-output error code
* @return the functionally equivalent collation locale, or the root
* locale upon error.
- * @draft ICU 3.0
+ * @stable ICU 3.0
*/
static Locale U_EXPORT2 getFunctionalEquivalent(const char* keyword, const Locale& locale,
UBool& isAvailable, UErrorCode& status);
* @stable ICU 2.2
*/
virtual UColAttributeValue getAttribute(UColAttribute attr,
- UErrorCode &status) = 0;
+ UErrorCode &status) const = 0;
/**
* Sets the variable top to a collation element value of a string supplied.
* @return a 32 bit value containing the value of the variable top in upper 16 bits. Lower 16 bits are undefined
* @stable ICU 2.0
*/
- virtual uint32_t setVariableTop(const UnicodeString varTop, UErrorCode &status) = 0;
+ virtual uint32_t setVariableTop(const UnicodeString &varTop, UErrorCode &status) = 0;
/**
* Sets the variable top to a collation element value supplied. Variable top is set to the upper 16 bits.
* @param status error code (not changed by function)
* @stable ICU 2.0
*/
- virtual void setVariableTop(const uint32_t varTop, UErrorCode &status) = 0;
+ virtual void setVariableTop(uint32_t varTop, UErrorCode &status) = 0;
/**
* Gets the variable top value of a Collator.
*/
virtual UnicodeSet *getTailoredSet(UErrorCode &status) const;
-
/**
- * Thread safe cloning operation
- * @return pointer to the new clone, user should remove it.
- * @stable ICU 2.2
+ * 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) = 0;
+ virtual Collator* safeClone(void) const;
/**
* Get the sort key as an array of bytes from an UnicodeString.
*/
Collator();
+#ifndef U_HIDE_DEPRECATED_API
/**
* Constructor.
* Empty constructor, does not handle the arguments.
*/
Collator(UCollationStrength collationStrength,
UNormalizationMode decompositionMode);
+#endif /* U_HIDE_DEPRECATED_API */
/**
* Copy constructor.
/**
* Used internally by registraton to define the requested and valid locales.
- * @param requestedLocale the requsted locale
+ * @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);
+ virtual void setLocales(const Locale& requestedLocale, const Locale& validLocale, const Locale& actualLocale);
public:
#if !UCONFIG_NO_SERVICE
+#ifndef U_HIDE_INTERNAL_API
/**
* used only by ucol_open, not for public use
* @internal
*/
static UCollator* createUCollator(const char* loc, UErrorCode* status);
+#endif /* U_HIDE_INTERNAL_API */
#endif
+
+ /** 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 properties 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://icu-project.org/userguide/Collate_Concepts.html#Naming_Collators
+ * 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;
private:
/**
* Assignment operator. Private for now.
/**
* Destructor
- * @draft ICU 3.0
+ * @stable ICU 3.0
*/
virtual ~CollatorFactory();
projects / apple / icu.git / blobdiff