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.
+ * @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;
@@ -404,6 +417,24 @@ public:
* The comparison function compares the character data stored in two
* different string arrays. Returns information about whether a string array
* is less than, greater than or equal to another string array.
+ * Example of use: + *
+ * . 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);
+ *
* @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.
@@ -484,7 +515,7 @@ public:
* @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,
@@ -504,7 +535,7 @@ public:
* @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,
@@ -528,7 +559,7 @@ public:
* @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.
@@ -566,7 +597,7 @@ public:
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.
* E.g. with strength == SECONDARY, the tertiary difference is ignored *
E.g. with strength == PRIMARY, the secondary and tertiary difference @@ -575,7 +606,7 @@ public: * @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. @@ -595,31 +626,67 @@ public: * @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); /** - * Get the current reordering of scripts (if one has been set). + * 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 pErrorCode Must be a valid pointer to an error code value, which must not indicate a failure before the function call. - * @return The length of the array of the script ordering. - * @see ucol_getReorderCodes - * @internal + * @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; + virtual int32_t getReorderCodes(int32_t *dest, + int32_t destCapacity, + UErrorCode& status) const; /** - * Set the ordering of scripts for this collator. - * @param reorderCodes An array of reorder codes in the new order. + * Sets the ordering of scripts for this collator. + * + *
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 - * @internal + * @see Collator#getReorderCodes + * @see Collator#setReorderCodes + * @see UScriptCode + * @see UColReorderCode + * @stable ICU 4.8 */ - virtual void setReorderCodes(const int32_t* reorderCodes, - int32_t reorderCodesLength, - UErrorCode& status) ; + 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 @@ -813,7 +880,7 @@ public: * @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. @@ -836,7 +903,7 @@ public: * @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. @@ -845,7 +912,7 @@ public: * @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. @@ -866,13 +933,14 @@ public: */ 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. @@ -967,6 +1035,7 @@ protected: */ Collator(); +#ifndef U_HIDE_DEPRECATED_API /** * Constructor. * Empty constructor, does not handle the arguments. @@ -980,6 +1049,7 @@ protected: */ Collator(UCollationStrength collationStrength, UNormalizationMode decompositionMode); +#endif /* U_HIDE_DEPRECATED_API */ /** * Copy constructor. @@ -1002,12 +1072,42 @@ protected: 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.