# CollationElementIterator Class Reference

The CollationElementIterator class is used as an iterator to walk through each character of an international string. More...

`#include <coleitr.h>`

Inheritance diagram for CollationElementIterator:

## Public Types
enum | { NULLORDER = (int32_t)0xffffffff }
## Public Member Functions
| CollationElementIterator (const CollationElementIterator &other)
| Copy constructor.
virtual | ~CollationElementIterator ()
| Destructor.
UBool | operator== (const CollationElementIterator &other) const
| 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".
void | reset (void)
| Resets the cursor to the beginning of the string.
int32_t | next (UErrorCode &status)
| Gets the ordering priority of the next character in the string.
int32_t | previous (UErrorCode &status)
| Get the ordering priority of the previous collation element in the string.
int32_t | getMaxExpansion (int32_t order) const
| Return the maximum length of any expansion sequences that end with the specified comparison order.
int32_t | strengthOrder (int32_t order) const
| Gets the comparison order in the desired strength.
void | setText (const UnicodeString &str, UErrorCode &status)
| Sets the source string.
void | setText (CharacterIterator &str, UErrorCode &status)
| Sets the source string.
int32_t | getOffset (void) const
| Gets the offset of the currently processed character in the source string.
void | setOffset (int32_t newOffset, UErrorCode &status)
| Sets the offset of the currently processed character in the source string.
virtual UClassID | getDynamicClassID () const
| ICU "poor man's RTTI", returns a UClassID for the actual class.
## Static Public Member Functions
static int32_t | primaryOrder (int32_t order)
| Gets the primary order of a collation order.
static int32_t | secondaryOrder (int32_t order)
| Gets the secondary order of a collation order.
static int32_t | tertiaryOrder (int32_t order)
| Gets the tertiary order of a collation order.
static UBool | isIgnorable (int32_t order)
| Checks if a comparison order is ignorable.
static UClassID | getStaticClassID ()
| ICU "poor man's RTTI", returns a UClassID for this class.
## Protected Member Functions
| CollationElementIterator (const UnicodeString &sourceText, const RuleBasedCollator *order, UErrorCode &status)
| CollationElementIterator constructor.
| CollationElementIterator (const CharacterIterator &sourceText, const RuleBasedCollator *order, UErrorCode &status)
| CollationElementIterator constructor.
const CollationElementIterator & | operator= (const CollationElementIterator &other)
| Assignment operator.
## Friends
class | RuleBasedCollator

## Detailed Description

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:

            "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,

      "æb"-> the first key is key('a'), the second key is key('e'), and
            the third key is key('b').

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)

        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;
       }

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 also:
  Collator
  RuleBasedCollator

Version:
  1.8 Jan 16 2001

Definition at line 120 of file coleitr.h.

## Member Enumeration Documentation

anonymous enum

Enumerator:

  NULLORDER | NULLORDER indicates that an error has occured while processing. Stable: ICU 2.0

Definition at line 125 of file coleitr.h.

## Constructor & Destructor Documentation

CollationElementIterator::CollationElementIterator | ( | const CollationElementIterator & | other | ) |

Copy constructor.

Parameters:

  | other | the object to be copied from

Stable:
  ICU 2.0

virtual CollationElementIterator::~CollationElementIterator | ( |  | ) | `[virtual]`

Destructor.

Stable:
  ICU 2.0

CollationElementIterator::CollationElementIterator | ( | const UnicodeString & | sourceText,
|  | const RuleBasedCollator * | order,
|  | UErrorCode & | status |
| ) |  |  | `[protected]`

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().

Parameters:

  | sourceText | the source string.
  | order | the collation object.
  | status | the error code status.

Stable:
  ICU 2.0

CollationElementIterator::CollationElementIterator | ( | const CharacterIterator & | sourceText,
|  | const RuleBasedCollator * | order,
|  | UErrorCode & | status |
| ) |  |  | `[protected]`

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().

Parameters:

  | sourceText | the source string.
  | order | the collation object.
  | status | the error code status.

Stable:
  ICU 2.0

## Member Function Documentation

virtual UClassID CollationElementIterator::getDynamicClassID | ( |  | ) | const`[virtual]`

ICU "poor man's RTTI", returns a UClassID for the actual class.

Stable:
  ICU 2.2

Implements UObject.

int32_t CollationElementIterator::getMaxExpansion | ( | int32_t | order | ) | const`[inline]`

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

Stable:
  ICU 2.0

Definition at line 386 of file coleitr.h.

References ucol_getMaxExpansion().

int32_t CollationElementIterator::getOffset | ( | void |  | ) | const

Gets the offset of the currently processed character in the source string.

Returns:
  the offset of the character.

Stable:
  ICU 2.0

static UClassID CollationElementIterator::getStaticClassID | ( |  | ) | `[static]`

ICU "poor man's RTTI", returns a UClassID for this class.

Stable:
  ICU 2.2

UBool CollationElementIterator::isIgnorable | ( | int32_t | order | ) | `[inline, static]`

Checks if a comparison order is ignorable.

Parameters:

  | order | the collation order.

Returns:
  TRUE if a character is ignorable, FALSE otherwise.

Stable:
  ICU 2.0

Definition at line 391 of file coleitr.h.

References primaryOrder().

int32_t CollationElementIterator::next | ( | UErrorCode & | status | ) |

Gets the ordering priority of the next character in the string.

Parameters:

  | status | the error code status.

Returns:
  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

UBool CollationElementIterator::operator!= | ( | const CollationElementIterator & | other | ) | const

Returns true if "other" is not the same as "this".

Parameters:

  | other | the object to be compared

Returns:
  true if "other" is not the same as "this"

Stable:
  ICU 2.0

const CollationElementIterator& CollationElementIterator::operator= | ( | const CollationElementIterator & | other | ) | `[protected]`

Assignment operator.

Parameters:

  | other | the object to be copied

Stable:
  ICU 2.0

UBool CollationElementIterator::operator== | ( | const CollationElementIterator & | other | ) | const

Returns true if "other" is the same as "this".

Parameters:

  | other | the object to be compared

Returns:
  true if "other" is the same as "this"

Stable:
  ICU 2.0

int32_t CollationElementIterator::previous | ( | UErrorCode & | status | ) |

Get the ordering priority of the previous collation element in the string.

Parameters:

  | status | the error code status.

Returns:
  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 CollationElementIterator::primaryOrder | ( | int32_t | order | ) | `[inline, static]`

Gets the primary order of a collation order.

Get the primary order of a collation order.

Parameters:

  | order | the collation order

Returns:
  the primary order of a collation order.

Stable:
  ICU 2.0

Parameters:

  | order | the collation order

Returns:
  the primary order of a collation order.

Definition at line 359 of file coleitr.h.

Referenced by isIgnorable().

void CollationElementIterator::reset | ( | void |  | ) |

Resets the cursor to the beginning of the string.

Stable:
  ICU 2.0

int32_t CollationElementIterator::secondaryOrder | ( | int32_t | order | ) | `[inline, static]`

Gets the secondary order of a collation order.

Get the secondary order of a collation order.

Parameters:

  | order | the collation order

Returns:
  the secondary order of a collation order.

Stable:
  ICU 2.0

Parameters:

  | order | the collation order

Returns:
  the secondary order of a collation order.

Definition at line 370 of file coleitr.h.

void CollationElementIterator::setOffset | ( | int32_t | newOffset,
|  | UErrorCode & | status |
| ) |  |  |

Sets the offset of the currently processed character in the source string.

Parameters:

  | newOffset | the new offset.
  | status | the error code status.

Returns:
  the offset of the character.

Stable:
  ICU 2.0

void CollationElementIterator::setText | ( | CharacterIterator & | str,
|  | UErrorCode & | status |
| ) |  |  |

Sets the source string.

Parameters:

  | str | the source character iterator.
  | status | the error code status.

Stable:
  ICU 2.0

void CollationElementIterator::setText | ( | const UnicodeString & | str,
|  | UErrorCode & | status |
| ) |  |  |

Sets the source string.

Parameters:

  | str | the source string.
  | status | the error code status.

Stable:
  ICU 2.0

int32_t CollationElementIterator::strengthOrder | ( | int32_t | order | ) | const

Gets the comparison order in the desired strength.

Ignore the other differences.

Parameters:

  | order | The order value

Stable:
  ICU 2.0

int32_t CollationElementIterator::tertiaryOrder | ( | int32_t | order | ) | `[inline, static]`

Gets the tertiary order of a collation order.

Get the tertiary order of a collation order.

Parameters:

  | order | the collation order

Returns:
  the tertiary order of a collation order.

Stable:
  ICU 2.0

Parameters:

  | order | the collation order

Returns:
  the tertiary order of a collation order.

Definition at line 381 of file coleitr.h.

## Friends And Related Function Documentation

friend class RuleBasedCollator`[friend]`

Stable:
  ICU 2.0

Definition at line 296 of file coleitr.h.

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

- coleitr.h

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Defines