michael@0: * Important: The ICU collation service has been reimplemented michael@0: * in order to achieve better performance and UCA compliance. michael@0: * For details, see the michael@0: * michael@0: * collation design document. michael@0: *
michael@0: * RuleBasedCollator is a thin C++ wrapper over the C implementation. michael@0: *
michael@0: * For more information about the collation service see michael@0: * the users guide. michael@0: *
michael@0: * Collation service provides correct sorting orders for most locales supported in ICU. michael@0: * If specific data for a locale is not available, the orders eventually falls back michael@0: * to the UCA sort order. michael@0: *
michael@0: * Sort ordering may be customized by providing your own set of rules. For more on michael@0: * this subject see the michael@0: * Collation customization section of the users guide. michael@0: *
michael@0: * Note, RuleBasedCollator is not to be subclassed. michael@0: * @see Collator michael@0: * @version 2.0 11/15/2001 michael@0: */ michael@0: class U_I18N_API RuleBasedCollator : public Collator michael@0: { michael@0: public: michael@0: michael@0: // constructor ------------------------------------------------------------- michael@0: michael@0: /** michael@0: * RuleBasedCollator constructor. This takes the table rules and builds a michael@0: * collation table out of them. Please see RuleBasedCollator class michael@0: * description for more details on the collation rule syntax. michael@0: * @param rules the collation rules to build the collation table from. michael@0: * @param status reporting a success or an error. michael@0: * @see Locale michael@0: * @stable ICU 2.0 michael@0: */ michael@0: RuleBasedCollator(const UnicodeString& rules, UErrorCode& status); michael@0: michael@0: /** michael@0: * RuleBasedCollator constructor. This takes the table rules and builds a michael@0: * collation table out of them. Please see RuleBasedCollator class michael@0: * description for more details on the collation rule syntax. michael@0: * @param rules the collation rules to build the collation table from. michael@0: * @param collationStrength default strength for comparison michael@0: * @param status reporting a success or an error. michael@0: * @see Locale michael@0: * @stable ICU 2.0 michael@0: */ michael@0: RuleBasedCollator(const UnicodeString& rules, michael@0: ECollationStrength collationStrength, michael@0: UErrorCode& status); michael@0: michael@0: /** michael@0: * RuleBasedCollator constructor. This takes the table rules and builds a michael@0: * collation table out of them. Please see RuleBasedCollator class michael@0: * description for more details on the collation rule syntax. michael@0: * @param rules the collation rules to build the collation table from. michael@0: * @param decompositionMode the normalisation mode michael@0: * @param status reporting a success or an error. michael@0: * @see Locale michael@0: * @stable ICU 2.0 michael@0: */ michael@0: RuleBasedCollator(const UnicodeString& rules, michael@0: UColAttributeValue decompositionMode, michael@0: UErrorCode& status); michael@0: michael@0: /** michael@0: * RuleBasedCollator constructor. This takes the table rules and builds a michael@0: * collation table out of them. Please see RuleBasedCollator class michael@0: * description for more details on the collation rule syntax. michael@0: * @param rules the collation rules to build the collation table from. michael@0: * @param collationStrength default strength for comparison michael@0: * @param decompositionMode the normalisation mode michael@0: * @param status reporting a success or an error. michael@0: * @see Locale michael@0: * @stable ICU 2.0 michael@0: */ michael@0: RuleBasedCollator(const UnicodeString& rules, michael@0: ECollationStrength collationStrength, michael@0: UColAttributeValue decompositionMode, michael@0: UErrorCode& status); michael@0: michael@0: /** michael@0: * Copy constructor. michael@0: * @param other the RuleBasedCollator object to be copied michael@0: * @see Locale michael@0: * @stable ICU 2.0 michael@0: */ michael@0: RuleBasedCollator(const RuleBasedCollator& other); michael@0: michael@0: michael@0: /** Opens a collator from a collator binary image created using michael@0: * cloneBinary. Binary image used in instantiation of the michael@0: * collator remains owned by the user and should stay around for michael@0: * the lifetime of the collator. The API also takes a base collator michael@0: * which usualy should be UCA. michael@0: * @param bin binary image owned by the user and required through the michael@0: * lifetime of the collator michael@0: * @param length size of the image. If negative, the API will try to michael@0: * figure out the length of the image michael@0: * @param base fallback collator, usually UCA. Base is required to be michael@0: * present through the lifetime of the collator. Currently michael@0: * it cannot be NULL. michael@0: * @param status for catching errors michael@0: * @return newly created collator michael@0: * @see cloneBinary michael@0: * @stable ICU 3.4 michael@0: */ michael@0: RuleBasedCollator(const uint8_t *bin, int32_t length, michael@0: const RuleBasedCollator *base, michael@0: UErrorCode &status); michael@0: // destructor -------------------------------------------------------------- michael@0: michael@0: /** michael@0: * Destructor. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual ~RuleBasedCollator(); michael@0: michael@0: // public methods ---------------------------------------------------------- michael@0: michael@0: /** michael@0: * Assignment operator. michael@0: * @param other other RuleBasedCollator object to compare with. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: RuleBasedCollator& operator=(const RuleBasedCollator& other); michael@0: michael@0: /** michael@0: * Returns true if argument is the same as this object. michael@0: * @param other Collator object to be compared. michael@0: * @return true if arguments is the same as this object. 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; michael@0: michael@0: /** michael@0: * Creates a collation element iterator for the source string. The caller of michael@0: * this method is responsible for the memory management of the return michael@0: * pointer. michael@0: * @param source the string over which the CollationElementIterator will michael@0: * iterate. michael@0: * @return the collation element iterator of the source string using this as michael@0: * the based Collator. michael@0: * @stable ICU 2.2 michael@0: */ michael@0: virtual CollationElementIterator* createCollationElementIterator( michael@0: const UnicodeString& source) const; michael@0: michael@0: /** michael@0: * Creates a collation element iterator for the source. The caller of this michael@0: * method is responsible for the memory management of the returned pointer. michael@0: * @param source the CharacterIterator which produces the characters over michael@0: * which the CollationElementItgerator will iterate. michael@0: * @return the collation element iterator of the source using this as the michael@0: * based Collator. michael@0: * @stable ICU 2.2 michael@0: */ michael@0: virtual CollationElementIterator* createCollationElementIterator( michael@0: const CharacterIterator& source) const; michael@0: michael@0: // Make deprecated versions of Collator::compare() visible. michael@0: using Collator::compare; 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; 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; 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; 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: * Transforms a specified region of the string into a series of characters michael@0: * that can be compared with CollationKey.compare. Use a CollationKey when michael@0: * you need to do repeated comparisions on the same string. For a single michael@0: * comparison the compare method will be faster. michael@0: * @param source the source string. michael@0: * @param key the transformed key of the source string. michael@0: * @param status the error code status. michael@0: * @return the transformed key. michael@0: * @see CollationKey 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; michael@0: michael@0: /** michael@0: * Transforms a specified region of the string into a series of characters michael@0: * that can be compared with CollationKey.compare. Use a CollationKey when michael@0: * you need to do repeated comparisions on the same string. For a single michael@0: * comparison the compare method will be faster. michael@0: * @param source the source string. michael@0: * @param sourceLength the length of the source string. michael@0: * @param key the transformed key of the source string. michael@0: * @param status the error code status. michael@0: * @return the transformed key. michael@0: * @see CollationKey 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; michael@0: michael@0: /** michael@0: * Generates the hash code for the rule-based collation object. michael@0: * @return the hash code. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual int32_t hashCode(void) const; michael@0: michael@0: /** michael@0: * Gets the locale of the Collator 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 likely to change in ICU 3.0, based on feedback michael@0: */ michael@0: virtual Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const; michael@0: michael@0: /** michael@0: * Gets the tailoring rules for this collator. michael@0: * @return the collation tailoring from which this collator was created michael@0: * @stable ICU 2.0 michael@0: */ michael@0: const UnicodeString& getRules(void) const; 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; michael@0: michael@0: #ifndef U_HIDE_DEPRECATED_API michael@0: /** michael@0: * Returns the maximum length of any expansion sequences that end with the michael@0: * specified comparison order. michael@0: * michael@0: * This is specific to the kind of collation element values and sequences michael@0: * returned by the CollationElementIterator. michael@0: * Call CollationElementIterator::getMaxExpansion() instead. michael@0: * michael@0: * @param order a collation order returned by CollationElementIterator::previous michael@0: * or CollationElementIterator::next. michael@0: * @return maximum size of the expansion sequences ending with the collation michael@0: * element, or 1 if the collation element does not occur at the end of michael@0: * any expansion sequence michael@0: * @see CollationElementIterator#getMaxExpansion michael@0: * @deprecated ICU 51 Use CollationElementIterator::getMaxExpansion() instead. michael@0: */ michael@0: int32_t getMaxExpansion(int32_t order) const; michael@0: #endif /* U_HIDE_DEPRECATED_API */ michael@0: michael@0: /** michael@0: * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This michael@0: * 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; michael@0: michael@0: /** michael@0: * Returns the class ID for this class. This is useful only for comparing to michael@0: * a return value from getDynamicClassID(). For example: michael@0: *
michael@0: * Base* polymorphic_pointer = createPolymorphicObject(); michael@0: * if (polymorphic_pointer->getDynamicClassID() == michael@0: * Derived::getStaticClassID()) ... michael@0: *michael@0: * @return The class ID for all objects of this class. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: static UClassID U_EXPORT2 getStaticClassID(void); michael@0: michael@0: #ifndef U_HIDE_DEPRECATED_API michael@0: /** michael@0: * Do not use this method: The caller and the ICU library might use different heaps. michael@0: * Use cloneBinary() instead which writes to caller-provided memory. michael@0: * michael@0: * Returns a binary format of this collator. michael@0: * @param length Returns the length of the data, in bytes michael@0: * @param status the error code status. michael@0: * @return memory, owned by the caller, of size 'length' bytes. michael@0: * @deprecated ICU 52. Use cloneBinary() instead. michael@0: */ michael@0: uint8_t *cloneRuleData(int32_t &length, UErrorCode &status); michael@0: #endif /* U_HIDE_DEPRECATED_API */ michael@0: michael@0: /** Creates a binary image of a collator. This binary image can be stored and michael@0: * later used to instantiate a collator using ucol_openBinary. michael@0: * This API supports preflighting. michael@0: * @param buffer a fill-in buffer to receive the binary image michael@0: * @param capacity capacity of the destination buffer michael@0: * @param status for catching errors michael@0: * @return size of the image michael@0: * @see ucol_openBinary michael@0: * @stable ICU 3.4 michael@0: */ michael@0: int32_t cloneBinary(uint8_t *buffer, int32_t capacity, UErrorCode &status); michael@0: michael@0: /** michael@0: * Returns current rules. Delta defines whether full rules are returned or michael@0: * just the tailoring. michael@0: * michael@0: * getRules(void) should normally be used instead. michael@0: * See http://userguide.icu-project.org/collation/customization#TOC-Building-on-Existing-Locales michael@0: * @param delta one of UCOL_TAILORING_ONLY, UCOL_FULL_RULES. michael@0: * @param buffer UnicodeString to store the result rules michael@0: * @stable ICU 2.2 michael@0: * @see UCOL_FULL_RULES michael@0: */ michael@0: void getRules(UColRuleOption delta, UnicodeString &buffer); 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 there were errors michael@0: * @stable ICU 2.2 michael@0: */ michael@0: virtual void setAttribute(UColAttribute attr, UColAttributeValue value, michael@0: UErrorCode &status); 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 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; 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: