/usr/include/unicode/coleitr.h (12990B)
* "ca" -> the first key is key('c') and second key is key('a').
* "cha" -> the first key is key('ch') and second key is key('a').
* And in German,
* \htmlonly "æb"-> the first key is key('a'), the second key is key('e'), and
* the third key is key('b'). \endhtmlonly
* The key of a character, is an integer composed of primary order(short),
* secondary order(char), and tertiary order(char). Java strictly defines the
* size and signedness of its primitive data types. Therefore, the static
* functions primaryOrder(), secondaryOrder(), and tertiaryOrder() return
* int32_t to ensure the correctness of the key value.
* Example of the iterator usage: (without error checking) *
* \code
* void CollationElementIterator_Example()
* {
* UnicodeString str = "This is a test";
* UErrorCode success = U_ZERO_ERROR;
* RuleBasedCollator* rbc =
* (RuleBasedCollator*) RuleBasedCollator::createInstance(success);
* CollationElementIterator* c =
* rbc->createCollationElementIterator( str );
* int32_t order = c->next(success);
* c->reset();
* order = c->previous(success);
* delete c;
* delete rbc;
* }
* \endcode
*
* * CollationElementIterator::next returns the collation order of the next * character based on the comparison level of the collator. * CollationElementIterator::previous returns the collation order of the * previous character based on the comparison level of the collator. * The Collation Element Iterator moves only in one direction between calls to * CollationElementIterator::reset. That is, CollationElementIterator::next() * and CollationElementIterator::previous can not be inter-used. Whenever * CollationElementIterator::previous is to be called after * CollationElementIterator::next() or vice versa, * CollationElementIterator::reset has to be called first to reset the status, * shifting pointers to either the end or the start of the string. Hence at the * next call of CollationElementIterator::previous or * CollationElementIterator::next(), the first or last collation order will be * returned. * If a change of direction is done without a CollationElementIterator::reset(), * the result is undefined. * The result of a forward iterate (CollationElementIterator::next) and * reversed result of the backward iterate (CollationElementIterator::previous) * on the same string are equivalent, if collation orders with the value * UCOL_IGNORABLE are ignored. * Character based on the comparison level of the collator. A collation order * consists of primary order, secondary order and tertiary order. The data * type of the collation order is t_int32. * * Note, CollationElementIterator should not be subclassed. * @see Collator * @see RuleBasedCollator * @version 1.8 Jan 16 2001 */ class U_I18N_API CollationElementIterator : public UObject { public: // CollationElementIterator public data member ------------------------------ enum { /** * NULLORDER indicates that an error has occured while processing * @stable ICU 2.0 */ NULLORDER = (int32_t)0xffffffff }; // CollationElementIterator public constructor/destructor ------------------- /** * Copy constructor. * * @param other the object to be copied from * @stable ICU 2.0 */ CollationElementIterator(const CollationElementIterator& other); /** * Destructor * @stable ICU 2.0 */ virtual ~CollationElementIterator(); // CollationElementIterator public methods ---------------------------------- /** * Returns true if "other" is the same as "this" * * @param other the object to be compared * @return true if "other" is the same as "this" * @stable ICU 2.0 */ UBool operator==(const CollationElementIterator& other) const; /** * Returns true if "other" is not the same as "this". * * @param other the object to be compared * @return true if "other" is not the same as "this" * @stable ICU 2.0 */ UBool operator!=(const CollationElementIterator& other) const; /** * Resets the cursor to the beginning of the string. * @stable ICU 2.0 */ void reset(void); /** * Gets the ordering priority of the next character in the string. * @param status the error code status. * @return the next character's ordering. otherwise returns NULLORDER if an * error has occured or if the end of string has been reached * @stable ICU 2.0 */ int32_t next(UErrorCode& status); /** * Get the ordering priority of the previous collation element in the string. * @param status the error code status. * @return the previous element's ordering. otherwise returns NULLORDER if an * error has occured or if the start of string has been reached * @stable ICU 2.0 */ int32_t previous(UErrorCode& status); /** * Gets the primary order of a collation order. * @param order the collation order * @return the primary order of a collation order. * @stable ICU 2.0 */ static inline int32_t primaryOrder(int32_t order); /** * Gets the secondary order of a collation order. * @param order the collation order * @return the secondary order of a collation order. * @stable ICU 2.0 */ static inline int32_t secondaryOrder(int32_t order); /** * Gets the tertiary order of a collation order. * @param order the collation order * @return the tertiary order of a collation order. * @stable ICU 2.0 */ static inline int32_t tertiaryOrder(int32_t order); /** * Return the maximum length of any expansion sequences that end with the * specified comparison order. * @param order a collation order returned by previous or 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 any * expansion sequence * @stable ICU 2.0 */ int32_t getMaxExpansion(int32_t order) const; /** * Gets the comparison order in the desired strength. Ignore the other * differences. * @param order The order value * @stable ICU 2.0 */ int32_t strengthOrder(int32_t order) const; /** * Sets the source string. * @param str the source string. * @param status the error code status. * @stable ICU 2.0 */ void setText(const UnicodeString& str, UErrorCode& status); /** * Sets the source string. * @param str the source character iterator. * @param status the error code status. * @stable ICU 2.0 */ void setText(CharacterIterator& str, UErrorCode& status); /** * Checks if a comparison order is ignorable. * @param order the collation order. * @return TRUE if a character is ignorable, FALSE otherwise. * @stable ICU 2.0 */ static inline UBool isIgnorable(int32_t order); /** * Gets the offset of the currently processed character in the source string. * @return the offset of the character. * @stable ICU 2.0 */ int32_t getOffset(void) const; /** * Sets the offset of the currently processed character in the source string. * @param newOffset the new offset. * @param status the error code status. * @return the offset of the character. * @stable ICU 2.0 */ void setOffset(int32_t newOffset, UErrorCode& status); /** * ICU "poor man's RTTI", returns a UClassID for the actual class. * * @stable ICU 2.2 */ virtual UClassID getDynamicClassID() const; /** * ICU "poor man's RTTI", returns a UClassID for this class. * * @stable ICU 2.2 */ static UClassID U_EXPORT2 getStaticClassID(); protected: // CollationElementIterator protected constructors -------------------------- /** * @stable ICU 2.0 */ friend class RuleBasedCollator; /** * CollationElementIterator constructor. This takes the source string and the * collation object. The cursor will walk thru the source string based on the * predefined collation rules. If the source string is empty, NULLORDER will * be returned on the calls to next(). * @param sourceText the source string. * @param order the collation object. * @param status the error code status. * @stable ICU 2.0 */ CollationElementIterator(const UnicodeString& sourceText, const RuleBasedCollator* order, UErrorCode& status); /** * CollationElementIterator constructor. This takes the source string and the * collation object. The cursor will walk thru the source string based on the * predefined collation rules. If the source string is empty, NULLORDER will * be returned on the calls to next(). * @param sourceText the source string. * @param order the collation object. * @param status the error code status. * @stable ICU 2.0 */ CollationElementIterator(const CharacterIterator& sourceText, const RuleBasedCollator* order, UErrorCode& status); // CollationElementIterator protected methods ------------------------------- /** * Assignment operator * * @param other the object to be copied * @stable ICU 2.0 */ const CollationElementIterator& operator=(const CollationElementIterator& other); private: CollationElementIterator(); // default constructor not implemented // CollationElementIterator private data members ---------------------------- /** * Data wrapper for collation elements */ UCollationElements *m_data_; /** * Indicates if m_data_ belongs to this object. */ UBool isDataOwned_; }; // CollationElementIterator inline method defination -------------------------- /** * Get the primary order of a collation order. * @param order the collation order * @return the primary order of a collation order. */ inline int32_t CollationElementIterator::primaryOrder(int32_t order) { order &= RuleBasedCollator::PRIMARYORDERMASK; return (order >> RuleBasedCollator::PRIMARYORDERSHIFT); } /** * Get the secondary order of a collation order. * @param order the collation order * @return the secondary order of a collation order. */ inline int32_t CollationElementIterator::secondaryOrder(int32_t order) { order = order & RuleBasedCollator::SECONDARYORDERMASK; return (order >> RuleBasedCollator::SECONDARYORDERSHIFT); } /** * Get the tertiary order of a collation order. * @param order the collation order * @return the tertiary order of a collation order. */ inline int32_t CollationElementIterator::tertiaryOrder(int32_t order) { return (order &= RuleBasedCollator::TERTIARYORDERMASK); } inline int32_t CollationElementIterator::getMaxExpansion(int32_t order) const { return ucol_getMaxExpansion(m_data_, (uint32_t)order); } inline UBool CollationElementIterator::isIgnorable(int32_t order) { return (primaryOrder(order) == RuleBasedCollator::PRIMIGNORABLE); } U_NAMESPACE_END #endif /* #if !UCONFIG_NO_COLLATION */ #endif