/* ****************************************************************************** * Copyright (C) 1997-2008, International Business Machines * Corporation and others. All Rights Reserved. ****************************************************************************** */ /** * \file * \brief C++ API: Collation Element Iterator. */ /** * File coleitr.h * * * * Created by: Helena Shih * * Modification History: * * Date Name Description * * 8/18/97 helena Added internal API documentation. * 08/03/98 erm Synched with 1.2 version CollationElementIterator.java * 12/10/99 aliu Ported Thai collation support from Java. * 01/25/01 swquek Modified into a C++ wrapper calling C APIs (ucoliter.h) * 02/19/01 swquek Removed CollationElementsIterator() since it is * private constructor and no calls are made to it */ #ifndef COLEITR_H #define COLEITR_H #include "unicode/utypes.h" #if !UCONFIG_NO_COLLATION #include "unicode/uobject.h" #include "unicode/tblcoll.h" #include "unicode/ucoleitr.h" /** * The UCollationElements struct. * For usage in C programs. * @stable ICU 2.0 */ typedef struct UCollationElements UCollationElements; U_NAMESPACE_BEGIN /** * The CollationElementIterator class is used as an iterator to walk through * each character of an international string. Use the iterator to return the * ordering priority of the positioned character. The ordering priority of a * character, which we refer to as a key, defines how a character is collated in * the given collation object. * For example, consider the following in Spanish: * <pre> * "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').</pre> * And in German, * <pre> \htmlonly "æb"-> the first key is key('a'), the second key is key('e'), and * the third key is key('b'). \endhtmlonly </pre> * 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. * <p>Example of the iterator usage: (without error checking) * <pre> * \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 * </pre> * <p> * 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 <strong>t_int32</strong>. * * 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