Loading...
Searching...
No Matches
icu::CollationElementIterator Class Referencefinal

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

`#include <coleitr.h>`

Inheritance diagram for icu::CollationElementIterator:

## Public Types

enum | { NULLORDER = static_cast<int32_t>(0xffffffff) }

## Public Member Functions

| CollationElementIterator (const CollationElementIterator &other)
| Copy constructor.
virtual | ~CollationElementIterator ()
| Destructor.
bool | operator== (const CollationElementIterator &other) const
| Returns true if "other" is the same as "this".
bool | operator!= (const CollationElementIterator &other) const
| Returns true if "other" is not the same as "this".
void | reset ()
| 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 () 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 override
| ICU "poor man's RTTI", returns a UClassID for the actual class.
UCollationElements * | toUCollationElements ()
const UCollationElements * | toUCollationElements () const
Public Member Functions inherited from icu::UObject
virtual | ~UObject ()
| Destructor.

## 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.
static CollationElementIterator * | fromUCollationElements (UCollationElements *uc)
static const CollationElementIterator * | fromUCollationElements (const UCollationElements *uc)

## Friends

class | RuleBasedCollator
class | UCollationPCE

## 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 Slovak and in traditional Spanish collation:

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

      "æ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;
    }
    icu::CollationElementIterator::previousint32_t previous(UErrorCode &status)Get the ordering priority of the previous collation element in the string.
    icu::CollationElementIterator::CollationElementIteratorCollationElementIterator(const CollationElementIterator &other)Copy constructor.
    icu::CollationElementIterator::nextint32_t next(UErrorCode &status)Gets the ordering priority of the next character in the string.
    icu::CollationElementIterator::resetvoid reset()Resets the cursor to the beginning of the string.
    icu::Collator::createInstancestatic Collator * createInstance(UErrorCode &err)Creates the Collator object for the current default locale.
    icu::RuleBasedCollator::createCollationElementIteratorU_I18N_API CollationElementIterator * createCollationElementIterator(const UnicodeString &source) constCreates a collation element iterator for the source string.
    icu::UnicodeStringUnicodeString is a string class that stores Unicode characters directly and provides similar function...Definition unistr.h:303
    UErrorCodeUErrorCodeStandard ICU4C error code type, a substitute for exceptions.Definition utypes.h:509
    U_ZERO_ERROR@ U_ZERO_ERRORNo error, no warning.Definition utypes.h:544

The method next() returns the collation order of the next character based on the comparison level of the collator. The method 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 reset(), setOffset(), or setText(). That is, next() and previous() can not be inter-used. Whenever previous() is to be called after next() or vice versa, reset(), setOffset() or setText() has to be called first to reset the status, shifting pointers to either the end or the start of the string (reset() or setText()), or the specified position (setOffset()). Hence at the next call of next() or previous(), the first or last collation order, or collation order at the specified position will be returned. If a change of direction is done without one of these calls, the result is undefined.

The result of a forward iterate (next()) and reversed result of the backward iterate (previous()) on the same string are equivalent, if collation orders with the value 0 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 int32_t.

Note, CollationElementIterator should not be subclassed.

See also
  Collator
  RuleBasedCollator

Version
  1.8 Jan 16 2001

Definition at line 121 of file coleitr.h.

## Member Enumeration Documentation

## anonymous enum

anonymous enum

Enumerator

NULLORDER

NULLORDER indicates that an error has occurred while processing.

Stable
  ICU 2.0

Definition at line 126 of file coleitr.h.

## Constructor & Destructor Documentation

## CollationElementIterator()

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

Copy constructor.

Parameters

  other | the object to be copied from

Stable
  ICU 2.0

References CollationElementIterator().

Referenced by CollationElementIterator(), fromUCollationElements(), fromUCollationElements(), operator!=(), and operator==().

## ~CollationElementIterator()

virtual icu::CollationElementIterator::~CollationElementIterator | ( |  | ) |

virtual

Destructor.

Stable
  ICU 2.0

## Member Function Documentation

## fromUCollationElements() [1/2]

const CollationElementIterator * icu::CollationElementIterator::fromUCollationElements | ( | const UCollationElements * | uc | ) |

inline static

Internal
  Do not use. This API is for internal use only.

Definition at line 297 of file coleitr.h.

References CollationElementIterator().

## fromUCollationElements() [2/2]

CollationElementIterator * icu::CollationElementIterator::fromUCollationElements | ( | UCollationElements * | uc | ) |

inline static

Internal
  Do not use. This API is for internal use only.

Definition at line 293 of file coleitr.h.

References CollationElementIterator().

## getDynamicClassID()

virtual UClassID icu::CollationElementIterator::getDynamicClassID | ( |  | ) | const

override virtual

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

Stable
  ICU 2.2

Reimplemented from icu::UObject.

## getMaxExpansion()

int32_t icu::CollationElementIterator::getMaxExpansion | ( | int32_t | order | ) | const

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

## getOffset()

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

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

Returns
  the offset of the character.

Stable
  ICU 2.0

## getStaticClassID()

UClassID icu::CollationElementIterator::getStaticClassID | ( |  | ) |

static

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

Stable
  ICU 2.2

## isIgnorable()

UBool icu::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 400 of file coleitr.h.

References isIgnorable().

Referenced by isIgnorable(), and setText().

## next()

int32_t icu::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 occurred or if the end of string has been reached

Stable
  ICU 2.0

## operator!=()

bool icu::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

References CollationElementIterator().

## operator==()

bool icu::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

References CollationElementIterator().

## previous()

int32_t icu::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 occurred or if the start of string has been reached

Stable
  ICU 2.0

References primaryOrder(), secondaryOrder(), and tertiaryOrder().

## primaryOrder()

int32_t icu::CollationElementIterator::primaryOrder | ( | int32_t | order | ) |

inline static

Gets the primary order of a collation order.

Parameters

  order | the collation order

Returns
  the primary order of a collation order.

Stable
  ICU 2.0

Definition at line 385 of file coleitr.h.

References primaryOrder().

Referenced by previous(), and primaryOrder().

## reset()

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

Resets the cursor to the beginning of the string.

Stable
  ICU 2.0

## secondaryOrder()

int32_t icu::CollationElementIterator::secondaryOrder | ( | int32_t | order | ) |

inline static

Gets the secondary order of a collation order.

Parameters

  order | the collation order

Returns
  the secondary order of a collation order.

Stable
  ICU 2.0

Definition at line 390 of file coleitr.h.

References secondaryOrder().

Referenced by previous(), and secondaryOrder().

## setOffset()

void icu::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

## setText() [1/2]

void icu::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

References isIgnorable().

## setText() [2/2]

void icu::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

## strengthOrder()

int32_t icu::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

## tertiaryOrder()

int32_t icu::CollationElementIterator::tertiaryOrder | ( | int32_t | order | ) |

inline static

Gets the tertiary order of a collation order.

Parameters

  order | the collation order

Returns
  the tertiary order of a collation order.

Stable
  ICU 2.0

Definition at line 395 of file coleitr.h.

References tertiaryOrder().

Referenced by previous(), and tertiaryOrder().

## toUCollationElements() [1/2]

UCollationElements * icu::CollationElementIterator::toUCollationElements | ( |  | ) |

inline

Internal
  Do not use. This API is for internal use only.

Definition at line 301 of file coleitr.h.

## toUCollationElements() [2/2]

const UCollationElements * icu::CollationElementIterator::toUCollationElements | ( |  | ) | const

inline

Internal
  Do not use. This API is for internal use only.

Definition at line 305 of file coleitr.h.

## Friends And Related Symbol Documentation

## RuleBasedCollator

friend class RuleBasedCollator

friend

Definition at line 311 of file coleitr.h.

## UCollationPCE

friend class UCollationPCE

friend

Definition at line 312 of file coleitr.h.

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

- i18n/unicode/coleitr.h