ICU 74.1 74.1
Public Types | Public Member Functions | Static Public Member Functions | Friends
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:
icu::UObject icu::UMemory

Public Types

enum  { NULLORDER = (int32_t)0xffffffff }
 

Public Member Functions

 CollationElementIterator (const CollationElementIterator &other)
 Copy constructor. More...
 
virtual ~CollationElementIterator ()
 Destructor. More...
 
bool operator== (const CollationElementIterator &other) const
 Returns true if "other" is the same as "this". More...
 
bool operator!= (const CollationElementIterator &other) const
 Returns true if "other" is not the same as "this". More...
 
void reset (void)
 Resets the cursor to the beginning of the string. More...
 
int32_t next (UErrorCode &status)
 Gets the ordering priority of the next character in the string. More...
 
int32_t previous (UErrorCode &status)
 Get the ordering priority of the previous collation element in the string. More...
 
int32_t getMaxExpansion (int32_t order) const
 Return the maximum length of any expansion sequences that end with the specified comparison order. More...
 
int32_t strengthOrder (int32_t order) const
 Gets the comparison order in the desired strength. More...
 
void setText (const UnicodeString &str, UErrorCode &status)
 Sets the source string. More...
 
void setText (CharacterIterator &str, UErrorCode &status)
 Sets the source string. More...
 
int32_t getOffset (void) const
 Gets the offset of the currently processed character in the source string. More...
 
void setOffset (int32_t newOffset, UErrorCode &status)
 Sets the offset of the currently processed character in the source string. More...
 
virtual UClassID getDynamicClassID () const override
 ICU "poor man's RTTI", returns a UClassID for the actual class. More...
 
UCollationElementstoUCollationElements ()
 
const UCollationElementstoUCollationElements () const
 
- Public Member Functions inherited from icu::UObject
virtual ~UObject ()
 Destructor. More...
 
virtual UClassID getDynamicClassID () const
 ICU4C "poor man's RTTI", returns a UClassID for the actual ICU class. More...
 

Static Public Member Functions

static int32_t primaryOrder (int32_t order)
 Gets the primary order of a collation order. More...
 
static int32_t secondaryOrder (int32_t order)
 Gets the secondary order of a collation order. More...
 
static int32_t tertiaryOrder (int32_t order)
 Gets the tertiary order of a collation order. More...
 
static UBool isIgnorable (int32_t order)
 Checks if a comparison order is ignorable. More...
 
static UClassID getStaticClassID ()
 ICU "poor man's RTTI", returns a UClassID for this class. More...
 
static CollationElementIteratorfromUCollationElements (UCollationElements *uc)
 
static const CollationElementIteratorfromUCollationElements (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";
int32_t order = c->next(success);
c->reset();
order = c->previous(success);
delete c;
delete rbc;
}
The CollationElementIterator class is used as an iterator to walk through each character of an inte...
Definition: coleitr.h:121
void reset(void)
Resets the cursor to the beginning of the string.
int32_t previous(UErrorCode &status)
Get the ordering priority of the previous collation element in the string.
int32_t next(UErrorCode &status)
Gets the ordering priority of the next character in the string.
static Collator * createInstance(UErrorCode &err)
Creates the Collator object for the current default locale.
The RuleBasedCollator class provides the implementation of Collator, using data-driven tables.
Definition: tblcoll.h:115
virtual CollationElementIterator * createCollationElementIterator(const UnicodeString &source) const
Creates a collation element iterator for the source string.
UnicodeString is a string class that stores Unicode characters directly and provides similar function...
Definition: unistr.h:296
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:415
@ U_ZERO_ERROR
No error, no warning.
Definition: utypes.h:449

<p<blockquote>‍

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
otherthe object to be copied from
Stable:
ICU 2.0

◆ ~CollationElementIterator()

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

Destructor.

Stable:
ICU 2.0

Member Function Documentation

◆ fromUCollationElements() [1/2]

static const CollationElementIterator * icu::CollationElementIterator::fromUCollationElements ( const UCollationElements uc)
inlinestatic
Internal:
Do not use. This API is for internal use only.

Definition at line 297 of file coleitr.h.

◆ fromUCollationElements() [2/2]

static CollationElementIterator * icu::CollationElementIterator::fromUCollationElements ( UCollationElements uc)
inlinestatic
Internal:
Do not use. This API is for internal use only.

Definition at line 293 of file coleitr.h.

◆ getDynamicClassID()

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

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
ordera 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 ( void  ) const

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

Returns
the offset of the character.
Stable:
ICU 2.0

◆ getStaticClassID()

static 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)
inlinestatic

Checks if a comparison order is ignorable.

Parameters
orderthe collation order.
Returns
true if a character is ignorable, false otherwise.
Stable:
ICU 2.0

Definition at line 400 of file coleitr.h.

◆ next()

int32_t icu::CollationElementIterator::next ( UErrorCode status)

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

Parameters
statusthe 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
otherthe object to be compared
Returns
true if "other" is not the same as "this"
Stable:
ICU 2.0

◆ operator==()

bool icu::CollationElementIterator::operator== ( const CollationElementIterator other) const

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

Parameters
otherthe object to be compared
Returns
true if "other" is the same as "this"
Stable:
ICU 2.0

◆ previous()

int32_t icu::CollationElementIterator::previous ( UErrorCode status)

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

Parameters
statusthe 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

◆ primaryOrder()

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

Gets the primary order of a collation order.

Parameters
orderthe collation order
Returns
the primary order of a collation order.
Stable:
ICU 2.0

Definition at line 385 of file coleitr.h.

◆ reset()

void icu::CollationElementIterator::reset ( void  )

Resets the cursor to the beginning of the string.

Stable:
ICU 2.0

◆ secondaryOrder()

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

Gets the secondary order of a collation order.

Parameters
orderthe collation order
Returns
the secondary order of a collation order.
Stable:
ICU 2.0

Definition at line 390 of file coleitr.h.

◆ setOffset()

void icu::CollationElementIterator::setOffset ( int32_t  newOffset,
UErrorCode status 
)

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

Parameters
newOffsetthe new offset.
statusthe 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
strthe source character iterator.
statusthe error code status.
Stable:
ICU 2.0

◆ setText() [2/2]

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

Sets the source string.

Parameters
strthe source string.
statusthe 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
orderThe order value
Stable:
ICU 2.0

◆ tertiaryOrder()

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

Gets the tertiary order of a collation order.

Parameters
orderthe collation order
Returns
the tertiary order of a collation order.
Stable:
ICU 2.0

Definition at line 395 of file coleitr.h.

◆ 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 Function 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: