* \code
* "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').
* \endcode
*
* And in German,
*
* \code
* "ęb"-> the first key is key('a'), the second key is key('e'), and
* the third key is key('b').
* \endcode
*
* 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);
* int32_t primaryOrder = CollationElementIterator::primaryOrder( order );
* delete c;
* delete rbc;
* }
* \endcode
*
*
* CollationElementIterator::next returns the collation order of the next
* 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 int32_t. The first 16 bits of a
* collation order is its primary order; the next 8 bits is the secondary order
* and the last 8 bits is the tertiary order.
*
* Note, CollationElementIterator should not be subclassed.
* @see Collator
* @see RuleBasedCollator
* @version 1.8 Jan 16 2001
*/
class U_I18N_API CollationElementIterator
{
public:
// CollationElementIterator public data member ------------------------------
/**
* NULLORDER indicates the iterator has consumed the last element.
*/
static int32_t const NULLORDER;
// CollationElementIterator public constructor/destructor -------------------
/**
* Copy constructor.
*/
CollationElementIterator(const CollationElementIterator& other);
/**
* Destructor
*/
~CollationElementIterator();
// CollationElementIterator public methods ----------------------------------
/**
* Returns true if "other" is the same as "this"
*/
UBool operator==(const CollationElementIterator& other) const;
/**
* Returns true if "other" is not the same as "this".
*/
UBool operator!=(const CollationElementIterator& other) const;
/**
* Resets the cursor to the beginning of the string.
*/
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. NULLORDER returned if the end of
* string is reached.
*/
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. NULLORDER returned if the beginning
* of string is reached.
*/
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.
*/
static 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.
*/
static 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.
*/
static 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 the maximum length of any expansion sequences ending with the
* specified order.
*/
int32_t getMaxExpansion(int32_t order) const;
/**
* Gets the comparison order in the desired strength. Ignore the other
* differences.
* @param order The order value
*/
int32_t strengthOrder(int32_t order) const;
/**
* Sets the source string.
* @param str the source string.
* @param status the error code status.
*/
void setText(const UnicodeString& str, UErrorCode& status);
/**
* Sets the source string.
* @param str the source character iterator.
* @param status the error code status.
*/
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.
*/
static UBool isIgnorable(int32_t order);
/**
* Gets the offset of the currently processed character in the source string.
* @return the offset of the character.
*/
UTextOffset 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.
*/
void setOffset(UTextOffset newOffset, UErrorCode& status);
protected:
// CollationElementIterator protected constructors --------------------------
/**
* 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 startOffset the beginning offset of the string where the cursor
* starts the iterating.
* @param endOffset the ending offset of the string where the cursor stops the
* iterating.
* @param order the collation object.
*/
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 startOffset the beginning offset of the string where the cursor
* starts the iterating.
* @param endOffset the ending offset of the string where the cursor stops the
* iterating.
* @param order the collation object.
*/
CollationElementIterator(const CharacterIterator& sourceText,
const RuleBasedCollator* order, UErrorCode& status);
// CollationElementIterator protected methods -------------------------------
/**
* Assignment operator
*/
const CollationElementIterator&
operator=(const CollationElementIterator& other);
private:
friend class RuleBasedCollator;
// CollationElementIterator private data members ----------------------------
static const int32_t UNMAPPEDCHARVALUE;
Normalizer* text; // owning
VectorOfInt* bufferAlias; // not owned
/**
* ownBuffer wants to be a subobject, not a pointer, but that means exposing
* the internal class VectorOfInt by #including the internal header
* "tables.h" -- not allowed! ownBuffer is a fixed-size 2-element vector that
* is used to handle Thai collation; bufferAlias points to ownBuffer in some
* situations. [j159 - aliu]
*/
VectorOfInt* ownBuffer;
/**
* reorderBuffer is created on demand, so it doesn't want to be a subobject --
* pointer is fine. It is created and bufferAlias is set to it under certain
* conditions. Once created, it is reused for the life of this object. Because
* of the implementation of VectorOfInt, it grows monotonically. [j159 - aliu]
*/
VectorOfInt* reorderBuffer;
int32_t expIndex;
UnicodeString key;
const RuleBasedCollator* orderAlias;
// CollationElementIterator private constructor/destructor ------------------
/**
* Default constructor.
*/
CollationElementIterator();
/**
* Constructor.
* @param order RuleBasedCollator object
*/
CollationElementIterator(const RuleBasedCollator* order);
// CollationElementIterator private methods ---------------------------------
/**
* Gets the ordering priority of the next contracting character in the string.
* @param ch the starting character of a contracting character token
* @param status the error code status.
* @return the next contracting character's ordering. Returns NULLORDER if the
* end of string is reached.
*/
// int32_t nextContractChar(UChar32 ch, UErrorCode& status);
/**
* Gets the ordering priority of the previous contracting character in the
* string.
* @param ch the starting character of a contracting character token
* @param status the error code status.
* @return the previous contracting character's ordering. Returns NULLORDER if
* the start of string is reached.
*/
// int32_t prevContractChar(UChar32 ch, UErrorCode& status);
// inline static UBool isThaiPreVowel(UChar32 ch);
// inline static UBool isThaiBaseConsonant(UChar32 ch);
/*
VectorOfInt* makeReorderedBuffer(UChar colFirst, int32_t lastValue,
VectorOfInt* lastExpansion, UBool forward,
UErrorCode& status);
*/
};
// 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 orderAlias->getMaxExpansion(order);
}
inline UBool CollationElementIterator::isIgnorable(int32_t order)
{
return (primaryOrder(order) == RuleBasedCollator::PRIMIGNORABLE);
}
/**
* Determine if a character is a Thai vowel (which sorts after
* its base consonant).
*/
/*
inline UBool CollationElementIterator::isThaiPreVowel(UChar32 ch)
{
return ((uint32_t)ch - 0xe40) <= (0xe44 - 0xe40);
}
*/
/**
* Determine if a character is a Thai base consonant
*/
/*
inline UBool CollationElementIterator::isThaiBaseConsonant(UChar32 ch)
{
return ((uint32_t)ch - 0xe01) <= (0xe2e - 0xe01);
}
*/
#endif