RuleBasedCollator Class Reference

The RuleBasedCollator class provides the simple implementation of Collator, using data-driven tables. More...

#include <tblcoll.h>

Inheritance diagram for RuleBasedCollator:

Public Member Functions
	RuleBasedCollator (const UnicodeString &rules, UErrorCode &status)
	RuleBasedCollator constructor.
	RuleBasedCollator (const UnicodeString &rules, ECollationStrength collationStrength, UErrorCode &status)
	RuleBasedCollator constructor.
	RuleBasedCollator (const UnicodeString &rules, UColAttributeValue decompositionMode, UErrorCode &status)
	RuleBasedCollator constructor.
	RuleBasedCollator (const UnicodeString &rules, ECollationStrength collationStrength, UColAttributeValue decompositionMode, UErrorCode &status)
	RuleBasedCollator constructor.
	RuleBasedCollator (const RuleBasedCollator &other)
	Copy constructor.
virtual	~RuleBasedCollator ()
	Destructor.
RuleBasedCollator &	operator= (const RuleBasedCollator &other)
	Assignment operator.
virtual UBool	operator== (const Collator &other) const
	Returns true if argument is the same as this object.
virtual UBool	operator!= (const Collator &other) const
	Returns true if argument is not the same as this object.
virtual Collator *	clone (void) const
	Makes a deep copy of the object.
virtual CollationElementIterator *	createCollationElementIterator (const UnicodeString &source) const
	Creates a collation element iterator for the source string.
virtual CollationElementIterator *	createCollationElementIterator (const CharacterIterator &source) const
	Creates a collation element iterator for the source.
virtual EComparisonResult	compare (const UnicodeString &source, const UnicodeString &target) const
	Compares a range of character data stored in two different strings based on the collation rules.
virtual EComparisonResult	compare (const UnicodeString &source, const UnicodeString &target, int32_t length) const
	Compares a range of character data stored in two different strings based on the collation rules up to the specified length.
virtual EComparisonResult	compare (const UChar *source, int32_t sourceLength, const UChar *target, int32_t targetLength) const
	The comparison function compares the character data stored in two different string arrays.
virtual CollationKey &	getCollationKey (const UnicodeString &source, CollationKey &key, UErrorCode &status) const
	Transforms a specified region of the string into a series of characters that can be compared with CollationKey.compare.
virtual CollationKey &	getCollationKey (const UChar *source, int32_t sourceLength, CollationKey &key, UErrorCode &status) const
	Transforms a specified region of the string into a series of characters that can be compared with CollationKey.compare.
virtual int32_t	hashCode (void) const
	Generates the hash code for the rule-based collation object.
virtual const Locale	getLocale (ULocDataLocaleType type, UErrorCode &status) const
	Gets the locale of the Collator.
const UnicodeString &	getRules (void) const
	Gets the table-based rules for the collation object.
virtual void	getVersion (UVersionInfo info) const
	Gets the version information for a Collator.
int32_t	getMaxExpansion (int32_t order) const
	Return the maximum length of any expansion sequences that end with the specified comparison order.
virtual UClassID	getDynamicClassID (void) const
	Returns a unique class ID POLYMORPHICALLY.
uint8_t *	cloneRuleData (int32_t &length, UErrorCode &status)
	Returns the binary format of the class's rules.
void	getRules (UColRuleOption delta, UnicodeString &buffer)
	Returns current rules.
virtual void	setAttribute (UColAttribute attr, UColAttributeValue value, UErrorCode &status)
	Universal attribute setter.
virtual UColAttributeValue	getAttribute (UColAttribute attr, UErrorCode &status)
	Universal attribute getter.
virtual uint32_t	setVariableTop (const UChar *varTop, int32_t len, UErrorCode &status)
	Sets the variable top to a collation element value of a string supplied.
virtual uint32_t	setVariableTop (const UnicodeString varTop, UErrorCode &status)
	Sets the variable top to a collation element value of a string supplied.
virtual void	setVariableTop (const uint32_t varTop, UErrorCode &status)
	Sets the variable top to a collation element value supplied.
virtual uint32_t	getVariableTop (UErrorCode &status) const
	Gets the variable top value of a Collator.
virtual Collator *	safeClone (void)
	Thread safe cloning operation.
virtual int32_t	getSortKey (const UnicodeString &source, uint8_t *result, int32_t resultLength) const
	Get the sort key as an array of bytes from an UnicodeString.
virtual int32_t	getSortKey (const UChar *source, int32_t sourceLength, uint8_t *result, int32_t resultLength) const
	Get the sort key as an array of bytes from an UChar buffer.
virtual ECollationStrength	getStrength (void) const
	Determines the minimum strength that will be use in comparison or transformation.
virtual void	setStrength (ECollationStrength newStrength)
	Sets the minimum strength to be used in comparison or transformation.
	RuleBasedCollator (const UnicodeString &rules, Normalizer::EMode decompositionMode, UErrorCode &status)
	RuleBasedCollator constructor.
	RuleBasedCollator (const UnicodeString &rules, ECollationStrength collationStrength, Normalizer::EMode decompositionMode, UErrorCode &status)
	RuleBasedCollator constructor.
virtual void	setDecomposition (Normalizer::EMode mode)
	Set the decomposition mode of the Collator object.
virtual Normalizer::EMode	getDecomposition (void) const
	Get the decomposition mode of the Collator object.
Static Public Member Functions
static UClassID	getStaticClassID (void)
	Returns the class ID for this class.
Friends
class	CollationElementIterator
	Used to iterate over collation elements in a character source.
class	Collator
	Collator ONLY needs access to RuleBasedCollator(const Locale&, UErrorCode&).
class	StringSearch
	Searching over collation elements in a character source.

---

Detailed Description

The RuleBasedCollator class provides the simple implementation of Collator, using data-driven tables.

The user can create a customized table-based collation.

Important: The ICU collation service has been reimplemented in order to achieve better performance and UCA compliance. For details, see the collation design document.

RuleBasedCollator is a thin C++ wrapper over the C implementation.

For more information about the collation service see the users guide.

Collation service provides correct sorting orders for most locales supported in ICU. If specific data for a locale is not available, the orders eventually falls back to the UCA sort order.

Sort ordering may be customized by providing your own set of rules. For more on this subject see the Collation customization section of the users guide.

See also:

Collator

Version:

2.0 11/15/2001

---

Constructor & Destructor Documentation

RuleBasedCollator::RuleBasedCollator (  const UnicodeString &  rules, UErrorCode &  status )

RuleBasedCollator constructor. This takes the table rules and builds a collation table out of them. Please see RuleBasedCollator class description for more details on the collation rule syntax. Parameters: rules  the collation rules to build the collation table from. status  reporting a success or an error. See also: Locale

RuleBasedCollator::RuleBasedCollator (  const UnicodeString &  rules, ECollationStrength  collationStrength, UErrorCode &  status )

RuleBasedCollator constructor. This takes the table rules and builds a collation table out of them. Please see RuleBasedCollator class description for more details on the collation rule syntax. Parameters: rules  the collation rules to build the collation table from. collationStrength  default strength for comparison status  reporting a success or an error. See also: Locale

RuleBasedCollator::RuleBasedCollator (  const UnicodeString &  rules, UColAttributeValue  decompositionMode, UErrorCode &  status )

RuleBasedCollator constructor. This takes the table rules and builds a collation table out of them. Please see RuleBasedCollator class description for more details on the collation rule syntax. Parameters: rules  the collation rules to build the collation table from. decompositionMode  the normalisation mode status  reporting a success or an error. See also: Locale

RuleBasedCollator::RuleBasedCollator (  const UnicodeString &  rules, ECollationStrength  collationStrength, UColAttributeValue  decompositionMode, UErrorCode &  status )

RuleBasedCollator constructor. This takes the table rules and builds a collation table out of them. Please see RuleBasedCollator class description for more details on the collation rule syntax. Parameters: rules  the collation rules to build the collation table from. collationStrength  default strength for comparison decompositionMode  the normalisation mode status  reporting a success or an error. See also: Locale

RuleBasedCollator::RuleBasedCollator (  const RuleBasedCollator &  other  )

Copy constructor. Parameters: the  RuleBasedCollator object to be copied See also: Locale

virtual RuleBasedCollator::~RuleBasedCollator (   )  [virtual]

Destructor.

RuleBasedCollator::RuleBasedCollator (  const UnicodeString &  rules, Normalizer::EMode  decompositionMode, UErrorCode &  status )

RuleBasedCollator constructor. This takes the table rules and builds a collation table out of them. Please see RuleBasedCollator class description for more details on the collation rule syntax. Parameters: rules  the collation rules to build the collation table from. decompositionMode  the normalisation mode status  reporting a success or an error. See also: Locale Deprecated: To be removed after 2002-sep-30, specify the decomposition mode with a UColAttributeValue.

RuleBasedCollator::RuleBasedCollator (  const UnicodeString &  rules, ECollationStrength  collationStrength, Normalizer::EMode  decompositionMode, UErrorCode &  status )

RuleBasedCollator constructor. This takes the table rules and builds a collation table out of them. Please see RuleBasedCollator class description for more details on the collation rule syntax. Parameters: rules  the collation rules to build the collation table from. collationStrength  default strength for comparison decompositionMode  the normalisation mode status  reporting a success or an error. See also: Locale Deprecated: To be removed after 2002-sep-30, specify the decomposition mode with a UColAttributeValue.

---

Member Function Documentation

virtual Collator* RuleBasedCollator::clone (  void   )  const [virtual]

Makes a deep copy of the object. The caller owns the returned object. Returns: the cloned object. Implements Collator.

uint8_t* RuleBasedCollator::cloneRuleData (  int32_t &  length, UErrorCode &  status )

Returns the binary format of the class's rules. The format is that of .col files. Parameters: length  Returns the length of the data, in bytes status  the error code status. Returns: memory, owned by the caller, of size 'length' bytes. ICU 1.8

virtual EComparisonResult RuleBasedCollator::compare (  const UChar *  source, int32_t  sourceLength, const UChar *  target, int32_t  targetLength )  const [virtual]

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); Parameters: source  the source string array to be compared with. sourceLength  the length of the source string array. If this value is equal to -1, the string array is null-terminated. target  the string that is to be compared with the source string. targetLength  the length of the target string array. If this value is equal to -1, the string array is null-terminated. Returns: 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 ICU 1.8 Implements Collator.

virtual EComparisonResult RuleBasedCollator::compare (  const UnicodeString &  source, const UnicodeString &  target, int32_t  length )  const [virtual]

Compares a range of character data stored in two different strings based on the collation rules up to the specified length. Returns information about whether a string is less than, greater than or equal to another string in a language. This can be overriden in a subclass. Parameters: source  the source string. target  the target string to be compared with the source string. length  compares up to the specified length Returns: the comparison result. GREATER if the source string is greater than the target string, LESS if the source is less than the target. Otherwise, returns EQUAL. Implements Collator.

virtual EComparisonResult RuleBasedCollator::compare (  const UnicodeString &  source, const UnicodeString &  target )  const [virtual]

Compares a range of character data stored in two different strings based on the collation rules. Returns information about whether a string is less than, greater than or equal to another string in a language. This can be overriden in a subclass. Parameters: source  the source string. target  the target string to be compared with the source string. Returns: the comparison result. GREATER if the source string is greater than the target string, LESS if the source is less than the target. Otherwise, returns EQUAL. Implements Collator.

virtual CollationElementIterator* RuleBasedCollator::createCollationElementIterator (  const CharacterIterator &  source  )  const [virtual]

Creates a collation element iterator for the source. The caller of this method is responsible for the memory management of the returned pointer. Parameters: source  the CharacterIterator which produces the characters over which the CollationElementItgerator will iterate. Returns: the collation element iterator of the source using this as the based Collator. ICU 1.8

virtual CollationElementIterator* RuleBasedCollator::createCollationElementIterator (  const UnicodeString &  source  )  const [virtual]

Creates a collation element iterator for the source string. The caller of this method is responsible for the memory management of the return pointer. Parameters: source  the string over which the CollationElementIterator will iterate. Returns: the collation element iterator of the source string using this as the based Collator. ICU 1.8

virtual UColAttributeValue RuleBasedCollator::getAttribute (  UColAttribute  attr, UErrorCode &  status )  [virtual]

Universal attribute getter. Parameters: attr  attribute type status  to indicate whether the operation went on smoothly or there were errors Returns: attribute value ICU 1.8 Implements Collator.

virtual CollationKey& RuleBasedCollator::getCollationKey (  const UChar *  source, int32_t  sourceLength, CollationKey &  key, UErrorCode &  status )  const [virtual]

Transforms a specified region of the string into a series of characters that can be compared with CollationKey.compare. Use a CollationKey when you need to do repeated comparisions on the same string. For a single comparison the compare method will be faster. Parameters: source  the source string. key  the transformed key of the source string. status  the error code status. Returns: the transformed key. See also: CollationKey Implements Collator.

virtual CollationKey& RuleBasedCollator::getCollationKey (  const UnicodeString &  source, CollationKey &  key, UErrorCode &  status )  const [virtual]

Transforms a specified region of the string into a series of characters that can be compared with CollationKey.compare. Use a CollationKey when you need to do repeated comparisions on the same string. For a single comparison the compare method will be faster. Parameters: source  the source string. key  the transformed key of the source string. status  the error code status. Returns: the transformed key. See also: CollationKey Implements Collator.

virtual Normalizer::EMode RuleBasedCollator::getDecomposition (  void   )  const [virtual]

Get the decomposition mode of the Collator object. Returns: the decomposition mode See also: Collator::setDecomposition Deprecated: To be removed after 2002-sep-30; use getAttribute(). Implements Collator.

virtual UClassID RuleBasedCollator::getDynamicClassID (  void   )  const [inline, virtual]

Returns a unique class ID POLYMORPHICALLY. Pure virtual override. 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. Returns: 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. Implements Collator.

virtual const Locale RuleBasedCollator::getLocale (  ULocDataLocaleType  type, UErrorCode &  status )  const [virtual]

Gets the locale of the Collator. Parameters: type  can be either requested, valid or actual locale. For more information see the definition of ULocDataLocaleType in uloc.h Returns: locale where the collation data lives. If the collator was instantiated from rules, locale is empty. ICU 2.1 Implements Collator.

int32_t RuleBasedCollator::getMaxExpansion (  int32_t  order  )  const

Return the maximum length of any expansion sequences that end with the specified comparison order. Parameters: order  a collation order returned by previous or next. Returns: maximum size of the expansion sequences ending with the collation element or 1 if collation element does not occur at the end of any expansion sequence See also: CollationElementIterator::getMaxExpansion

void RuleBasedCollator::getRules (  UColRuleOption  delta, UnicodeString &  buffer )

Returns current rules. Delta defines whether full rules are returned or just the tailoring. Parameters: delta  one of UCOL_TAILORING_ONLY, UCOL_FULL_RULES. buffer  UnicodeString to store the result rules ICU 1.8

const UnicodeString& RuleBasedCollator::getRules (  void   )  const

Gets the table-based rules for the collation object. Returns: returns the collation rules that the table collation object was created from.

virtual int32_t RuleBasedCollator::getSortKey (  const UChar *  source, int32_t  sourceLength, uint8_t *  result, int32_t  resultLength )  const [virtual]

Get the sort key as an array of bytes from an UChar buffer. Parameters: source  string to be processed. sourceLength  length of string to be processed. If -1, the string is 0 terminated and length will be decided by the function. result  buffer to store result in. If NULL, number of bytes needed will be returned. resultLength  length of the result buffer. If if not enough the buffer will be filled to capacity. Returns: Number of bytes needed for storing the sort key ICU 1.8 Implements Collator.

virtual int32_t RuleBasedCollator::getSortKey (  const UnicodeString &  source, uint8_t *  result, int32_t  resultLength )  const [virtual]

Get the sort key as an array of bytes from an UnicodeString. Parameters: source  string to be processed. result  buffer to store result in. If NULL, number of bytes needed will be returned. resultLength  length of the result buffer. If if not enough the buffer will be filled to capacity. Returns: Number of bytes needed for storing the sort key Implements Collator.

static UClassID RuleBasedCollator::getStaticClassID (  void   )  [inline, static]

Returns the class ID for this class. This is useful only for comparing to a return value from getDynamicClassID(). For example: Base* polymorphic_pointer = createPolymorphicObject(); if (polymorphic_pointer->getDynamicClassID() == Derived::getStaticClassID()) ... Returns: The class ID for all objects of this class.

virtual ECollationStrength RuleBasedCollator::getStrength (  void   )  const [virtual]

Determines the minimum strength that will be use in comparison or transformation. E.g. with strength == SECONDARY, the tertiary difference is ignored E.g. with strength == PRIMARY, the secondary and tertiary difference are ignored. Returns: the current comparison level. See also: RuleBasedCollator::setStrength Implements Collator.

virtual uint32_t RuleBasedCollator::getVariableTop (  UErrorCode &  status  )  const [virtual]

Gets the variable top value of a Collator. Lower 16 bits are undefined and should be ignored. Parameters: status  error code (not changed by function). If error code is set, the return value is undefined. ICU 2.0 Implements Collator.

virtual void RuleBasedCollator::getVersion (  UVersionInfo  info  )  const [virtual]

Gets the version information for a Collator. Parameters: info  the version # information, the result will be filled in Implements Collator.

virtual int32_t RuleBasedCollator::hashCode (  void   )  const [virtual]

Generates the hash code for the rule-based collation object. Returns: the hash code. Implements Collator.

UBool RuleBasedCollator::operator!= (  const Collator &  other  )  const [inline, virtual]

Returns true if argument is not the same as this object. Parameters: other  Collator object to be compared Returns: returns true if argument is not the same as this object. Reimplemented from Collator.

RuleBasedCollator& RuleBasedCollator::operator= (  const RuleBasedCollator &  other  )

Assignment operator. Parameters: other  other RuleBasedCollator object to compare with.

virtual UBool RuleBasedCollator::operator== (  const Collator &  other  )  const [virtual]

Returns true if argument is the same as this object. Parameters: other  Collator object to be compared. Returns: true if arguments is the same as this object. Reimplemented from Collator.

virtual Collator* RuleBasedCollator::safeClone (  void   )  [virtual]

Thread safe cloning operation. Returns: pointer to the new clone, user should remove it. ICU 1.8 Implements Collator.

virtual void RuleBasedCollator::setAttribute (  UColAttribute  attr, UColAttributeValue  value, UErrorCode &  status )  [virtual]

Universal attribute setter. Parameters: attr  attribute type value  attribute value status  to indicate whether the operation went on smoothly or there were errors ICU 1.8 Implements Collator.

virtual void RuleBasedCollator::setDecomposition (  Normalizer::EMode  mode  )  [virtual]

Set the decomposition mode of the Collator object. success is equal to U_ILLEGAL_ARGUMENT_ERROR if error occurs. Parameters: the  new decomposition mode See also: Collator::getDecomposition Deprecated: To be removed after 2002-sep-30; use setAttribute(). Implements Collator.

virtual void RuleBasedCollator::setStrength (  ECollationStrength  newStrength  )  [virtual]

Sets the minimum strength to be used in comparison or transformation. See also: RuleBasedCollator::getStrength Parameters: newStrength  the new comparison level. Implements Collator.

virtual void RuleBasedCollator::setVariableTop (  const uint32_t  varTop, UErrorCode &  status )  [virtual]

Sets the variable top to a collation element value supplied. Variable top is set to the upper 16 bits. Lower 16 bits are ignored. Parameters: varTop  CE value, as returned by setVariableTop or ucol)getVariableTop status  error code (not changed by function) ICU 2.0 Implements Collator.

virtual uint32_t RuleBasedCollator::setVariableTop (  const UnicodeString  varTop, UErrorCode &  status )  [virtual]

Sets the variable top to a collation element value of a string supplied. Parameters: varTop  an UnicodeString size 1 or more (if contraction) of UChars to which the variable top should be set status  error code. If error code is set, the return value is undefined. Errors set by this function are: U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no such a contraction U_PRIMARY_TOO_LONG_ERROR if the primary for the variable top has more than two bytes Returns: a 32 bit value containing the value of the variable top in upper 16 bits. Lower 16 bits are undefined ICU 2.0 Implements Collator.

virtual uint32_t RuleBasedCollator::setVariableTop (  const UChar *  varTop, int32_t  len, UErrorCode &  status )  [virtual]

Sets the variable top to a collation element value of a string supplied. Parameters: varTop  one or more (if contraction) UChars to which the variable top should be set len  length of variable top string. If -1 it is considered to be zero terminated. status  error code. If error code is set, the return value is undefined. Errors set by this function are: U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no such a contraction U_PRIMARY_TOO_LONG_ERROR if the primary for the variable top has more than two bytes Returns: a 32 bit value containing the value of the variable top in upper 16 bits. Lower 16 bits are undefined ICU 2.0 Implements Collator.

---

The documentation for this class was generated from the following file:

• tblcoll.h

---