/*
******************************************************************************
-* Copyright (C) 1996-2006, International Business Machines Corporation and
+* Copyright (C) 1996-2013, International Business Machines Corporation and
* others. All Rights Reserved.
******************************************************************************
*/
+/**
+ * \file
+ * \brief C++ API: RuleBasedCollator class provides the simple implementation of Collator.
+ */
+
/**
* File tblcoll.h
*
#include "unicode/utypes.h"
-/**
- * \file
- * \brief C++ API: RuleBasedCollator class provides the simple implementation of Collator.
- */
#if !UCONFIG_NO_COLLATION
* <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://dev.icu-project.org/cgi-bin/viewcvs.cgi/~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>
* RuleBasedCollator is a thin C++ wrapper over the C implementation.
* <p>
* For more information about the collation service see
- * <a href="http://icu.sourceforge.net/userguide/Collate_Intro.html">the users guide</a>.
+ * <a href="http://icu-project.org/userguide/Collate_Intro.html">the users guide</a>.
* <p>
* 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 <a href="http://www.unicode.org/unicode/reports/tr10/">UCA sort order</a>.
* <p>
* Sort ordering may be customized by providing your own set of rules. For more on
- * this subject see the <a href="http://icu.sourceforge.net/userguide/Collate_Customization.html">
+ * this subject see the <a href="http://icu-project.org/userguide/Collate_Customization.html">
* Collation customization</a> section of the users guide.
* <p>
* Note, RuleBasedCollator is not to be subclassed.
* @param status for catching errors
* @return newly created collator
* @see cloneBinary
- * @draft ICU 3.4
+ * @stable ICU 3.4
*/
RuleBasedCollator(const uint8_t *bin, int32_t length,
const RuleBasedCollator *base,
virtual UBool operator==(const Collator& other) const;
/**
- * Returns true if argument is not the same as this object.
- * @param other Collator object to be compared
- * @return returns true if argument is not the same as this object.
- * @stable ICU 2.0
- */
- virtual UBool operator!=(const Collator& other) const;
-
- /**
- * Makes a deep copy of the object.
- * The caller owns the returned object.
- * @return the cloned 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;
virtual CollationElementIterator* createCollationElementIterator(
const CharacterIterator& source) const;
- /**
- * 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.
- * @param source the source string.
- * @param target the target string to be compared with the source string.
- * @return 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.
- * @deprecated ICU 2.6 Use overload with UErrorCode&
- */
- virtual EComparisonResult compare(const UnicodeString& source,
- const UnicodeString& target) const;
-
+ // Make deprecated versions of Collator::compare() visible.
+ using Collator::compare;
/**
* The comparison function compares the character data stored in two
const UnicodeString& target,
UErrorCode &status) const;
- /**
- * 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.
- * @param source the source string.
- * @param target the target string to be compared with the source string.
- * @param length compares up to the specified length
- * @return 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.
- * @deprecated ICU 2.6 Use overload with UErrorCode&
- */
- virtual EComparisonResult compare(const UnicodeString& source,
- const UnicodeString& target,
- int32_t length) const;
-
/**
* Does the same thing as compare but limits the comparison to a specified
* length
int32_t length,
UErrorCode &status) const;
- /**
- * 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.
- * @param target the string that is to be compared with the source string.
- * @param targetLength the length of the target string array. If this value
- * is equal to -1, the string array is null-terminated.
- * @return 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
- * @deprecated ICU 2.6 Use overload with UErrorCode&
- */
- 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. Returns information about whether a string array
const UChar* target, int32_t targetLength,
UErrorCode &status) const;
+ /**
+ * 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;
+
/**
* Transforms a specified region of the string into a series of characters
* that can be compared with CollationKey.compare. Use a CollationKey when
* @param status the error code status.
* @return the transformed key.
* @see CollationKey
- * @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 transformed key.
* @see CollationKey
- * @deprecated ICU 2.8 Use getSortKey(...) instead
+ * @stable ICU 2.0
*/
virtual CollationKey& getCollationKey(const UChar *source,
int32_t sourceLength,
* was instantiated from rules, locale is empty.
* @deprecated ICU 2.8 likely to change in ICU 3.0, based on feedback
*/
- virtual const Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const;
+ virtual Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const;
/**
- * Gets the table-based rules for the collation object.
- * @return returns the collation rules that the table collation object was
- * created from.
+ * Gets the tailoring rules for this collator.
+ * @return the collation tailoring from which this collator was created
* @stable ICU 2.0
*/
const UnicodeString& getRules(void) const;
*/
virtual void getVersion(UVersionInfo info) const;
+#ifndef U_HIDE_DEPRECATED_API
/**
- * Return the maximum length of any expansion sequences that end with the
+ * Returns the maximum length of any expansion sequences that end with the
* specified comparison order.
- * @param order a collation order returned by previous or next.
+ *
+ * This is specific to the kind of collation element values and sequences
+ * returned by the CollationElementIterator.
+ * Call CollationElementIterator::getMaxExpansion() instead.
+ *
+ * @param order a collation order returned by CollationElementIterator::previous
+ * or CollationElementIterator::next.
* @return maximum size of the expansion sequences ending with the collation
- * element or 1 if collation element does not occur at the end of
+ * element, or 1 if the collation element does not occur at the end of
* any expansion sequence
* @see CollationElementIterator#getMaxExpansion
- * @stable ICU 2.0
+ * @deprecated ICU 51 Use CollationElementIterator::getMaxExpansion() instead.
*/
int32_t getMaxExpansion(int32_t order) const;
+#endif /* U_HIDE_DEPRECATED_API */
/**
* Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This
* @param status for catching errors
* @return size of the image
* @see ucol_openBinary
- * @draft ICU 3.4
+ * @stable ICU 3.4
*/
int32_t cloneBinary(uint8_t *buffer, int32_t capacity, UErrorCode &status);
/**
* Returns current rules. Delta defines whether full rules are returned or
* just the tailoring.
+ *
+ * getRules(void) should normally be used instead.
+ * See http://userguide.icu-project.org/collation/customization#TOC-Building-on-Existing-Locales
* @param delta one of UCOL_TAILORING_ONLY, UCOL_FULL_RULES.
* @param buffer UnicodeString to store the result rules
* @stable ICU 2.2
+ * @see UCOL_FULL_RULES
*/
void getRules(UColRuleOption delta, UnicodeString &buffer);
* @stable ICU 2.2
*/
virtual UColAttributeValue getAttribute(UColAttribute attr,
- UErrorCode &status);
+ UErrorCode &status) const;
/**
* 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);
+ virtual uint32_t setVariableTop(const UnicodeString &varTop, UErrorCode &status);
/**
* 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);
+ virtual void setVariableTop(uint32_t varTop, UErrorCode &status);
/**
* 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
- */
- virtual Collator* safeClone(void);
-
/**
* Get the sort key as an array of bytes from an UnicodeString.
* @param source string to be processed.
uint8_t *result, int32_t resultLength) const;
/**
- * Determines the minimum strength that will be use 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
- * are ignored.
- * @return the current comparison level.
- * @see RuleBasedCollator#setStrength
- * @deprecated ICU 2.6 Use getAttribute(UCOL_STRENGTH...) instead
- */
- virtual ECollationStrength getStrength(void) const;
-
- /**
- * Sets the minimum strength to be used in comparison or transformation.
- * @see RuleBasedCollator#getStrength
- * @param newStrength the new comparison level.
- * @deprecated ICU 2.6 Use setAttribute(UCOL_STRENGTH...) instead
- */
- 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
+ * @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.
+ * @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
+ * @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
+ * @stable ICU 4.8
+ */
+ static int32_t U_EXPORT2 getEquivalentReorderCodes(int32_t reorderCode,
+ int32_t* dest,
+ int32_t destCapacity,
+ UErrorCode& status);
private:
// private static constants -----------------------------------------------
- static const int32_t UNMAPPED;
- static const int32_t CHARINDEX; // need look up in .commit()
- static const int32_t EXPANDCHARINDEX; // Expand index follows
- static const int32_t CONTRACTCHARINDEX; // contract indexes follow
-
- static const int32_t PRIMARYORDERINCREMENT;
- static const int32_t SECONDARYORDERINCREMENT;
- static const int32_t TERTIARYORDERINCREMENT;
- static const int32_t PRIMARYORDERMASK;
- static const int32_t SECONDARYORDERMASK;
- static const int32_t TERTIARYORDERMASK;
- static const int32_t IGNORABLEMASK;
- static const int32_t PRIMARYDIFFERENCEONLY;
- static const int32_t SECONDARYDIFFERENCEONLY;
- static const int32_t PRIMARYORDERSHIFT;
- static const int32_t SECONDARYORDERSHIFT;
-
- static const int32_t COLELEMENTSTART;
- static const int32_t PRIMARYLOWZEROMASK;
- static const int32_t RESETSECONDARYTERTIARY;
- static const int32_t RESETTERTIARY;
-
- static const int32_t PRIMIGNORABLE;
+ enum {
+ /* need look up in .commit() */
+ CHARINDEX = 0x70000000,
+ /* Expand index follows */
+ EXPANDCHARINDEX = 0x7E000000,
+ /* contract indexes follows */
+ CONTRACTCHARINDEX = 0x7F000000,
+ /* unmapped character values */
+ UNMAPPED = 0xFFFFFFFF,
+ /* primary strength increment */
+ PRIMARYORDERINCREMENT = 0x00010000,
+ /* secondary strength increment */
+ SECONDARYORDERINCREMENT = 0x00000100,
+ /* tertiary strength increment */
+ TERTIARYORDERINCREMENT = 0x00000001,
+ /* mask off anything but primary order */
+ PRIMARYORDERMASK = 0xffff0000,
+ /* mask off anything but secondary order */
+ SECONDARYORDERMASK = 0x0000ff00,
+ /* mask off anything but tertiary order */
+ TERTIARYORDERMASK = 0x000000ff,
+ /* mask off ignorable char order */
+ IGNORABLEMASK = 0x0000ffff,
+ /* use only the primary difference */
+ PRIMARYDIFFERENCEONLY = 0xffff0000,
+ /* use only the primary and secondary difference */
+ SECONDARYDIFFERENCEONLY = 0xffffff00,
+ /* primary order shift */
+ PRIMARYORDERSHIFT = 16,
+ /* secondary order shift */
+ SECONDARYORDERSHIFT = 8,
+ /* starting value for collation elements */
+ COLELEMENTSTART = 0x02020202,
+ /* testing mask for primary low element */
+ PRIMARYLOWZEROMASK = 0x00FF0000,
+ /* reseting value for secondaries and tertiaries */
+ RESETSECONDARYTERTIARY = 0x00000202,
+ /* reseting value for tertiaries */
+ RESETTERTIARY = 0x00000002,
+
+ PRIMIGNORABLE = 0x0202
+ };
// private data members ---------------------------------------------------
* Hence the responsibility of cleaning up the ucollator is not done by
* this RuleBasedCollator. The isDataOwned flag is set to FALSE.
* @param collator new ucollator data
- * @param rules corresponding collation rules
*/
void setUCollator(UCollator *collator);
public:
+#ifndef U_HIDE_INTERNAL_API
/**
* Get UCollator data struct. Used only by StringSearch & intltest.
* @return UCollator data struct
* @internal
*/
const UCollator * getUCollator();
+#endif /* U_HIDE_INTERNAL_API */
protected:
/**
* Used internally by registraton to define the requested and valid locales.
* @param requestedLocale the requsted 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);
private:
-
// if not owned and not a write through alias, copy the ucollator
void checkOwned(void);
// utility to init rule string used by checkOwned and construct
void setRuleStringFromCollator();
- /**
- * Converts C's UCollationResult to EComparisonResult
- * @param result member of the enum UComparisonResult
- * @return EComparisonResult equivalent of UCollationResult
- * @deprecated ICU 2.6. We will not need it.
- */
- Collator::EComparisonResult getEComparisonResult(
- const UCollationResult &result) const;
-
- /**
- * Converts C's UCollationStrength to ECollationStrength
- * @param strength member of the enum UCollationStrength
- * @return ECollationStrength equivalent of UCollationStrength
- */
- Collator::ECollationStrength getECollationStrength(
- const UCollationStrength &strength) const;
-
- /**
- * Converts C++'s ECollationStrength to UCollationStrength
- * @param strength member of the enum ECollationStrength
- * @return UCollationStrength equivalent of ECollationStrength
- */
- UCollationStrength getUCollationStrength(
- const Collator::ECollationStrength &strength) const;
+public:
+ /** 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;
};
// inline method implementation ---------------------------------------------
ucollator = collator;
dataIsOwned = FALSE;
isWriteThroughAlias = TRUE;
- setRuleStringFromCollator();
+ setRuleStringFromCollator();
}
inline const UCollator * RuleBasedCollator::getUCollator()
return ucollator;
}
-inline Collator::EComparisonResult RuleBasedCollator::getEComparisonResult(
- const UCollationResult &result) const
-{
- switch (result)
- {
- case UCOL_LESS :
- return Collator::LESS;
- case UCOL_EQUAL :
- return Collator::EQUAL;
- default :
- return Collator::GREATER;
- }
-}
-
-inline Collator::ECollationStrength RuleBasedCollator::getECollationStrength(
- const UCollationStrength &strength) const
-{
- switch (strength)
- {
- case UCOL_PRIMARY :
- return Collator::PRIMARY;
- case UCOL_SECONDARY :
- return Collator::SECONDARY;
- case UCOL_TERTIARY :
- return Collator::TERTIARY;
- case UCOL_QUATERNARY :
- return Collator::QUATERNARY;
- default :
- return Collator::IDENTICAL;
- }
-}
-
-inline UCollationStrength RuleBasedCollator::getUCollationStrength(
- const Collator::ECollationStrength &strength) const
-{
- switch (strength)
- {
- case Collator::PRIMARY :
- return UCOL_PRIMARY;
- case Collator::SECONDARY :
- return UCOL_SECONDARY;
- case Collator::TERTIARY :
- return UCOL_TERTIARY;
- case Collator::QUATERNARY :
- return UCOL_QUATERNARY;
- default :
- return UCOL_IDENTICAL;
- }
-}
-
U_NAMESPACE_END
#endif /* #if !UCONFIG_NO_COLLATION */
projects / apple / icu.git / blobdiff