jpayne@69: * For more information about the collation service see jpayne@69: * the User Guide. jpayne@69: *
jpayne@69: * Collation service provides correct sorting orders for most locales supported in ICU. jpayne@69: * If specific data for a locale is not available, the orders eventually falls back jpayne@69: * to the CLDR root sort order. jpayne@69: *
jpayne@69: * Sort ordering may be customized by providing your own set of rules. For more on jpayne@69: * this subject see the jpayne@69: * Collation Customization section of the User Guide. jpayne@69: *
jpayne@69: * Note, RuleBasedCollator is not to be subclassed. jpayne@69: * @see Collator jpayne@69: */ jpayne@69: class U_I18N_API RuleBasedCollator : public Collator { jpayne@69: public: jpayne@69: /** jpayne@69: * RuleBasedCollator constructor. This takes the table rules and builds a jpayne@69: * collation table out of them. Please see RuleBasedCollator class jpayne@69: * description for more details on the collation rule syntax. jpayne@69: * @param rules the collation rules to build the collation table from. jpayne@69: * @param status reporting a success or an error. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: RuleBasedCollator(const UnicodeString& rules, UErrorCode& status); jpayne@69: jpayne@69: /** jpayne@69: * RuleBasedCollator constructor. This takes the table rules and builds a jpayne@69: * collation table out of them. Please see RuleBasedCollator class jpayne@69: * description for more details on the collation rule syntax. jpayne@69: * @param rules the collation rules to build the collation table from. jpayne@69: * @param collationStrength strength for comparison jpayne@69: * @param status reporting a success or an error. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: RuleBasedCollator(const UnicodeString& rules, jpayne@69: ECollationStrength collationStrength, jpayne@69: UErrorCode& status); jpayne@69: jpayne@69: /** jpayne@69: * RuleBasedCollator constructor. This takes the table rules and builds a jpayne@69: * collation table out of them. Please see RuleBasedCollator class jpayne@69: * description for more details on the collation rule syntax. jpayne@69: * @param rules the collation rules to build the collation table from. jpayne@69: * @param decompositionMode the normalisation mode jpayne@69: * @param status reporting a success or an error. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: RuleBasedCollator(const UnicodeString& rules, jpayne@69: UColAttributeValue decompositionMode, jpayne@69: UErrorCode& status); jpayne@69: jpayne@69: /** jpayne@69: * RuleBasedCollator constructor. This takes the table rules and builds a jpayne@69: * collation table out of them. Please see RuleBasedCollator class jpayne@69: * description for more details on the collation rule syntax. jpayne@69: * @param rules the collation rules to build the collation table from. jpayne@69: * @param collationStrength strength for comparison jpayne@69: * @param decompositionMode the normalisation mode jpayne@69: * @param status reporting a success or an error. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: RuleBasedCollator(const UnicodeString& rules, jpayne@69: ECollationStrength collationStrength, jpayne@69: UColAttributeValue decompositionMode, jpayne@69: UErrorCode& status); jpayne@69: jpayne@69: #ifndef U_HIDE_INTERNAL_API jpayne@69: /** jpayne@69: * TODO: document & propose as public API jpayne@69: * @internal jpayne@69: */ jpayne@69: RuleBasedCollator(const UnicodeString &rules, jpayne@69: UParseError &parseError, UnicodeString &reason, jpayne@69: UErrorCode &errorCode); jpayne@69: #endif /* U_HIDE_INTERNAL_API */ jpayne@69: jpayne@69: /** jpayne@69: * Copy constructor. jpayne@69: * @param other the RuleBasedCollator object to be copied jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: RuleBasedCollator(const RuleBasedCollator& other); jpayne@69: jpayne@69: jpayne@69: /** Opens a collator from a collator binary image created using jpayne@69: * cloneBinary. Binary image used in instantiation of the jpayne@69: * collator remains owned by the user and should stay around for jpayne@69: * the lifetime of the collator. The API also takes a base collator jpayne@69: * which must be the root collator. jpayne@69: * @param bin binary image owned by the user and required through the jpayne@69: * lifetime of the collator jpayne@69: * @param length size of the image. If negative, the API will try to jpayne@69: * figure out the length of the image jpayne@69: * @param base Base collator, for lookup of untailored characters. jpayne@69: * Must be the root collator, must not be NULL. jpayne@69: * The base is required to be present through the lifetime of the collator. jpayne@69: * @param status for catching errors jpayne@69: * @return newly created collator jpayne@69: * @see cloneBinary jpayne@69: * @stable ICU 3.4 jpayne@69: */ jpayne@69: RuleBasedCollator(const uint8_t *bin, int32_t length, jpayne@69: const RuleBasedCollator *base, jpayne@69: UErrorCode &status); jpayne@69: jpayne@69: /** jpayne@69: * Destructor. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual ~RuleBasedCollator(); jpayne@69: jpayne@69: /** jpayne@69: * Assignment operator. jpayne@69: * @param other other RuleBasedCollator object to copy from. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: RuleBasedCollator& operator=(const RuleBasedCollator& other); jpayne@69: jpayne@69: /** jpayne@69: * Returns true if argument is the same as this object. jpayne@69: * @param other Collator object to be compared. jpayne@69: * @return true if arguments is the same as this object. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual UBool operator==(const Collator& other) const; jpayne@69: jpayne@69: /** jpayne@69: * Makes a copy of this object. jpayne@69: * @return a copy of this object, owned by the caller jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual RuleBasedCollator* clone() const; jpayne@69: jpayne@69: /** jpayne@69: * Creates a collation element iterator for the source string. The caller of jpayne@69: * this method is responsible for the memory management of the return jpayne@69: * pointer. jpayne@69: * @param source the string over which the CollationElementIterator will jpayne@69: * iterate. jpayne@69: * @return the collation element iterator of the source string using this as jpayne@69: * the based Collator. jpayne@69: * @stable ICU 2.2 jpayne@69: */ jpayne@69: virtual CollationElementIterator* createCollationElementIterator( jpayne@69: const UnicodeString& source) const; jpayne@69: jpayne@69: /** jpayne@69: * Creates a collation element iterator for the source. The caller of this jpayne@69: * method is responsible for the memory management of the returned pointer. jpayne@69: * @param source the CharacterIterator which produces the characters over jpayne@69: * which the CollationElementItgerator will iterate. jpayne@69: * @return the collation element iterator of the source using this as the jpayne@69: * based Collator. jpayne@69: * @stable ICU 2.2 jpayne@69: */ jpayne@69: virtual CollationElementIterator* createCollationElementIterator( jpayne@69: const CharacterIterator& source) const; jpayne@69: jpayne@69: // Make deprecated versions of Collator::compare() visible. jpayne@69: using Collator::compare; jpayne@69: jpayne@69: /** jpayne@69: * The comparison function compares the character data stored in two jpayne@69: * different strings. Returns information about whether a string is less jpayne@69: * than, greater than or equal to another string. jpayne@69: * @param source the source string to be compared with. jpayne@69: * @param target the string that is to be compared with the source string. jpayne@69: * @param status possible error code jpayne@69: * @return Returns an enum value. UCOL_GREATER if source is greater jpayne@69: * than target; UCOL_EQUAL if source is equal to target; UCOL_LESS if source is less jpayne@69: * than target jpayne@69: * @stable ICU 2.6 jpayne@69: **/ jpayne@69: virtual UCollationResult compare(const UnicodeString& source, jpayne@69: const UnicodeString& target, jpayne@69: UErrorCode &status) const; jpayne@69: jpayne@69: /** jpayne@69: * Does the same thing as compare but limits the comparison to a specified jpayne@69: * length jpayne@69: * @param source the source string to be compared with. jpayne@69: * @param target the string that is to be compared with the source string. jpayne@69: * @param length the length the comparison is limited to jpayne@69: * @param status possible error code jpayne@69: * @return Returns an enum value. UCOL_GREATER if source (up to the specified jpayne@69: * length) is greater than target; UCOL_EQUAL if source (up to specified jpayne@69: * length) is equal to target; UCOL_LESS if source (up to the specified jpayne@69: * length) is less than target. jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: virtual UCollationResult compare(const UnicodeString& source, jpayne@69: const UnicodeString& target, jpayne@69: int32_t length, jpayne@69: UErrorCode &status) const; jpayne@69: jpayne@69: /** jpayne@69: * The comparison function compares the character data stored in two jpayne@69: * different string arrays. Returns information about whether a string array jpayne@69: * is less than, greater than or equal to another string array. jpayne@69: * @param source the source string array to be compared with. jpayne@69: * @param sourceLength the length of the source string array. If this value jpayne@69: * is equal to -1, the string array is null-terminated. jpayne@69: * @param target the string that is to be compared with the source string. jpayne@69: * @param targetLength the length of the target string array. If this value jpayne@69: * is equal to -1, the string array is null-terminated. jpayne@69: * @param status possible error code jpayne@69: * @return Returns an enum value. UCOL_GREATER if source is greater jpayne@69: * than target; UCOL_EQUAL if source is equal to target; UCOL_LESS if source is less jpayne@69: * than target jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: virtual UCollationResult compare(const char16_t* source, int32_t sourceLength, jpayne@69: const char16_t* target, int32_t targetLength, jpayne@69: UErrorCode &status) const; jpayne@69: jpayne@69: /** jpayne@69: * Compares two strings using the Collator. jpayne@69: * Returns whether the first one compares less than/equal to/greater than jpayne@69: * the second one. jpayne@69: * This version takes UCharIterator input. jpayne@69: * @param sIter the first ("source") string iterator jpayne@69: * @param tIter the second ("target") string iterator jpayne@69: * @param status ICU status jpayne@69: * @return UCOL_LESS, UCOL_EQUAL or UCOL_GREATER jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: virtual UCollationResult compare(UCharIterator &sIter, jpayne@69: UCharIterator &tIter, jpayne@69: UErrorCode &status) const; jpayne@69: jpayne@69: /** jpayne@69: * Compares two UTF-8 strings using the Collator. jpayne@69: * Returns whether the first one compares less than/equal to/greater than jpayne@69: * the second one. jpayne@69: * This version takes UTF-8 input. jpayne@69: * Note that a StringPiece can be implicitly constructed jpayne@69: * from a std::string or a NUL-terminated const char * string. jpayne@69: * @param source the first UTF-8 string jpayne@69: * @param target the second UTF-8 string jpayne@69: * @param status ICU status jpayne@69: * @return UCOL_LESS, UCOL_EQUAL or UCOL_GREATER jpayne@69: * @stable ICU 51 jpayne@69: */ jpayne@69: virtual UCollationResult compareUTF8(const StringPiece &source, jpayne@69: const StringPiece &target, jpayne@69: UErrorCode &status) const; jpayne@69: jpayne@69: /** jpayne@69: * Transforms the string into a series of characters jpayne@69: * that can be compared with CollationKey.compare(). jpayne@69: * jpayne@69: * Note that sort keys are often less efficient than simply doing comparison. jpayne@69: * For more details, see the ICU User Guide. jpayne@69: * jpayne@69: * @param source the source string. jpayne@69: * @param key the transformed key of the source string. jpayne@69: * @param status the error code status. jpayne@69: * @return the transformed key. jpayne@69: * @see CollationKey jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual CollationKey& getCollationKey(const UnicodeString& source, jpayne@69: CollationKey& key, jpayne@69: UErrorCode& status) const; jpayne@69: jpayne@69: /** jpayne@69: * Transforms a specified region of the string into a series of characters jpayne@69: * that can be compared with CollationKey.compare. jpayne@69: * jpayne@69: * Note that sort keys are often less efficient than simply doing comparison. jpayne@69: * For more details, see the ICU User Guide. jpayne@69: * jpayne@69: * @param source the source string. jpayne@69: * @param sourceLength the length of the source string. jpayne@69: * @param key the transformed key of the source string. jpayne@69: * @param status the error code status. jpayne@69: * @return the transformed key. jpayne@69: * @see CollationKey jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual CollationKey& getCollationKey(const char16_t *source, jpayne@69: int32_t sourceLength, jpayne@69: CollationKey& key, jpayne@69: UErrorCode& status) const; jpayne@69: jpayne@69: /** jpayne@69: * Generates the hash code for the rule-based collation object. jpayne@69: * @return the hash code. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual int32_t hashCode() const; jpayne@69: jpayne@69: #ifndef U_FORCE_HIDE_DEPRECATED_API jpayne@69: /** jpayne@69: * Gets the locale of the Collator jpayne@69: * @param type can be either requested, valid or actual locale. For more jpayne@69: * information see the definition of ULocDataLocaleType in jpayne@69: * uloc.h jpayne@69: * @param status the error code status. jpayne@69: * @return locale where the collation data lives. If the collator jpayne@69: * was instantiated from rules, locale is empty. jpayne@69: * @deprecated ICU 2.8 likely to change in ICU 3.0, based on feedback jpayne@69: */ jpayne@69: virtual Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const; jpayne@69: #endif // U_FORCE_HIDE_DEPRECATED_API jpayne@69: jpayne@69: /** jpayne@69: * Gets the tailoring rules for this collator. jpayne@69: * @return the collation tailoring from which this collator was created jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: const UnicodeString& getRules() const; jpayne@69: jpayne@69: /** jpayne@69: * Gets the version information for a Collator. jpayne@69: * @param info the version # information, the result will be filled in jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual void getVersion(UVersionInfo info) const; jpayne@69: jpayne@69: #ifndef U_HIDE_DEPRECATED_API jpayne@69: /** jpayne@69: * Returns the maximum length of any expansion sequences that end with the jpayne@69: * specified comparison order. jpayne@69: * jpayne@69: * This is specific to the kind of collation element values and sequences jpayne@69: * returned by the CollationElementIterator. jpayne@69: * Call CollationElementIterator::getMaxExpansion() instead. jpayne@69: * jpayne@69: * @param order a collation order returned by CollationElementIterator::previous jpayne@69: * or CollationElementIterator::next. jpayne@69: * @return maximum size of the expansion sequences ending with the collation jpayne@69: * element, or 1 if the collation element does not occur at the end of jpayne@69: * any expansion sequence jpayne@69: * @see CollationElementIterator#getMaxExpansion jpayne@69: * @deprecated ICU 51 Use CollationElementIterator::getMaxExpansion() instead. jpayne@69: */ jpayne@69: int32_t getMaxExpansion(int32_t order) const; jpayne@69: #endif /* U_HIDE_DEPRECATED_API */ jpayne@69: jpayne@69: /** jpayne@69: * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This jpayne@69: * method is to implement a simple version of RTTI, since not all C++ jpayne@69: * compilers support genuine RTTI. Polymorphic operator==() and clone() jpayne@69: * methods call this method. jpayne@69: * @return The class ID for this object. All objects of a given class have jpayne@69: * the same class ID. Objects of other classes have different class jpayne@69: * IDs. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual UClassID getDynamicClassID(void) const; jpayne@69: jpayne@69: /** jpayne@69: * Returns the class ID for this class. This is useful only for comparing to jpayne@69: * a return value from getDynamicClassID(). For example: jpayne@69: *
jpayne@69: * Base* polymorphic_pointer = createPolymorphicObject(); jpayne@69: * if (polymorphic_pointer->getDynamicClassID() == jpayne@69: * Derived::getStaticClassID()) ... jpayne@69: *jpayne@69: * @return The class ID for all objects of this class. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: static UClassID U_EXPORT2 getStaticClassID(void); jpayne@69: jpayne@69: #ifndef U_HIDE_DEPRECATED_API jpayne@69: /** jpayne@69: * Do not use this method: The caller and the ICU library might use different heaps. jpayne@69: * Use cloneBinary() instead which writes to caller-provided memory. jpayne@69: * jpayne@69: * Returns a binary format of this collator. jpayne@69: * @param length Returns the length of the data, in bytes jpayne@69: * @param status the error code status. jpayne@69: * @return memory, owned by the caller, of size 'length' bytes. jpayne@69: * @deprecated ICU 52. Use cloneBinary() instead. jpayne@69: */ jpayne@69: uint8_t *cloneRuleData(int32_t &length, UErrorCode &status) const; jpayne@69: #endif /* U_HIDE_DEPRECATED_API */ jpayne@69: jpayne@69: /** Creates a binary image of a collator. This binary image can be stored and jpayne@69: * later used to instantiate a collator using ucol_openBinary. jpayne@69: * This API supports preflighting. jpayne@69: * @param buffer a fill-in buffer to receive the binary image jpayne@69: * @param capacity capacity of the destination buffer jpayne@69: * @param status for catching errors jpayne@69: * @return size of the image jpayne@69: * @see ucol_openBinary jpayne@69: * @stable ICU 3.4 jpayne@69: */ jpayne@69: int32_t cloneBinary(uint8_t *buffer, int32_t capacity, UErrorCode &status) const; jpayne@69: jpayne@69: /** jpayne@69: * Returns current rules. Delta defines whether full rules are returned or jpayne@69: * just the tailoring. jpayne@69: * jpayne@69: * getRules(void) should normally be used instead. jpayne@69: * See http://userguide.icu-project.org/collation/customization#TOC-Building-on-Existing-Locales jpayne@69: * @param delta one of UCOL_TAILORING_ONLY, UCOL_FULL_RULES. jpayne@69: * @param buffer UnicodeString to store the result rules jpayne@69: * @stable ICU 2.2 jpayne@69: * @see UCOL_FULL_RULES jpayne@69: */ jpayne@69: void getRules(UColRuleOption delta, UnicodeString &buffer) const; jpayne@69: jpayne@69: /** jpayne@69: * Universal attribute setter jpayne@69: * @param attr attribute type jpayne@69: * @param value attribute value jpayne@69: * @param status to indicate whether the operation went on smoothly or there were errors jpayne@69: * @stable ICU 2.2 jpayne@69: */ jpayne@69: virtual void setAttribute(UColAttribute attr, UColAttributeValue value, jpayne@69: UErrorCode &status); jpayne@69: jpayne@69: /** jpayne@69: * Universal attribute getter. jpayne@69: * @param attr attribute type jpayne@69: * @param status to indicate whether the operation went on smoothly or there were errors jpayne@69: * @return attribute value jpayne@69: * @stable ICU 2.2 jpayne@69: */ jpayne@69: virtual UColAttributeValue getAttribute(UColAttribute attr, jpayne@69: UErrorCode &status) const; jpayne@69: jpayne@69: /** jpayne@69: * Sets the variable top to the top of the specified reordering group. jpayne@69: * The variable top determines the highest-sorting character jpayne@69: * which is affected by UCOL_ALTERNATE_HANDLING. jpayne@69: * If that attribute is set to UCOL_NON_IGNORABLE, then the variable top has no effect. jpayne@69: * @param group one of UCOL_REORDER_CODE_SPACE, UCOL_REORDER_CODE_PUNCTUATION, jpayne@69: * UCOL_REORDER_CODE_SYMBOL, UCOL_REORDER_CODE_CURRENCY; jpayne@69: * or UCOL_REORDER_CODE_DEFAULT to restore the default max variable group jpayne@69: * @param errorCode Standard ICU error code. Its input value must jpayne@69: * pass the U_SUCCESS() test, or else the function returns jpayne@69: * immediately. Check for U_FAILURE() on output or use with jpayne@69: * function chaining. (See User Guide for details.) jpayne@69: * @return *this jpayne@69: * @see getMaxVariable jpayne@69: * @stable ICU 53 jpayne@69: */ jpayne@69: virtual Collator &setMaxVariable(UColReorderCode group, UErrorCode &errorCode); jpayne@69: jpayne@69: /** jpayne@69: * Returns the maximum reordering group whose characters are affected by UCOL_ALTERNATE_HANDLING. jpayne@69: * @return the maximum variable reordering group. jpayne@69: * @see setMaxVariable jpayne@69: * @stable ICU 53 jpayne@69: */ jpayne@69: virtual UColReorderCode getMaxVariable() const; jpayne@69: jpayne@69: #ifndef U_FORCE_HIDE_DEPRECATED_API jpayne@69: /** jpayne@69: * Sets the variable top to the primary weight of the specified string. jpayne@69: * jpayne@69: * Beginning with ICU 53, the variable top is pinned to jpayne@69: * the top of one of the supported reordering groups, jpayne@69: * and it must not be beyond the last of those groups. jpayne@69: * See setMaxVariable(). jpayne@69: * @param varTop one or more (if contraction) char16_ts to which the variable top should be set jpayne@69: * @param len length of variable top string. If -1 it is considered to be zero terminated. jpayne@69: * @param status error code. If error code is set, the return value is undefined. Errors set by this function are: