Logo Search packages:      
Sourcecode: icu version File versions  Download package

ucoleitr.h File Reference

Detailed Description

C API: UCollationElements.

The UCollationElements API 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,
 .       "<ae ligature>b"-> the first key is key('a'), the second key is key('e'), and
 .       the third key is key('b').

Example of the iterator usage: (without error checking)

 .  void CollationElementIterator_Example()
 .  {
 .      UChar *s;
 .      t_int32 order, primaryOrder;
 .      UCollationElements *c;
 .      UCollatorOld *coll;
 .      UErrorCode success = U_ZERO_ERROR;
 .      s=(UChar*)malloc(sizeof(UChar) * (strlen("This is a test")+1) );
 .      u_uastrcpy(s, "This is a test");
 .      coll = ucol_open(NULL, &success);
 .      c = ucol_openElements(coll, str, u_strlen(str), &status);
 .      order = ucol_next(c, &success);
 .      ucol_reset(c);
 .      order = ucol_prev(c, &success);
 .      free(s);
 .      ucol_close(coll);
 .      ucol_closeElements(c);
 .  }

ucol_next() returns the collation order of the next. ucol_prev() returns the collation order of the previous character. The Collation Element Iterator moves only in one direction between calls to ucol_reset. That is, ucol_next() and ucol_prev can not be inter-used. Whenever ucol_prev is to be called after ucol_next() or vice versa, ucol_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 ucol_prev or ucol_next, the first or last collation order will be returned. If a change of direction is done without a ucol_reset, the result is undefined. The result of a forward iterate (ucol_next) and reversed result of the backward iterate (ucol_prev) 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.

See also:

Definition in file ucoleitr.h.

#include "unicode/utypes.h"
#include "unicode/ucol.h"

Go to the source code of this file.


#define UCOL_NULLORDER   ((int32_t)0xFFFFFFFF)


typedef struct UCollationElements UCollationElements


U_STABLE void U_EXPORT2 ucol_closeElements (UCollationElements *elems)
U_INTERNAL void U_EXPORT2 ucol_forceHanImplicit (UCollationElements *elems, UErrorCode *status)
U_STABLE int32_t U_EXPORT2 ucol_getMaxExpansion (const UCollationElements *elems, int32_t order)
U_STABLE int32_t U_EXPORT2 ucol_getOffset (const UCollationElements *elems)
U_STABLE int32_t U_EXPORT2 ucol_keyHashCode (const uint8_t *key, int32_t length)
U_STABLE int32_t U_EXPORT2 ucol_next (UCollationElements *elems, UErrorCode *status)
U_INTERNAL int64_t U_EXPORT2 ucol_nextProcessed (UCollationElements *elems, int32_t *ixLow, int32_t *ixHigh, UErrorCode *status)
U_STABLE UCollationElements
ucol_openElements (const UCollator *coll, const UChar *text, int32_t textLength, UErrorCode *status)
U_STABLE int32_t U_EXPORT2 ucol_previous (UCollationElements *elems, UErrorCode *status)
U_INTERNAL int64_t U_EXPORT2 ucol_previousProcessed (UCollationElements *elems, int32_t *ixLow, int32_t *ixHigh, UErrorCode *status)
U_STABLE int32_t U_EXPORT2 ucol_primaryOrder (int32_t order)
U_STABLE void U_EXPORT2 ucol_reset (UCollationElements *elems)
U_STABLE int32_t U_EXPORT2 ucol_secondaryOrder (int32_t order)
U_STABLE void U_EXPORT2 ucol_setOffset (UCollationElements *elems, int32_t offset, UErrorCode *status)
U_STABLE void U_EXPORT2 ucol_setText (UCollationElements *elems, const UChar *text, int32_t textLength, UErrorCode *status)
U_STABLE int32_t U_EXPORT2 ucol_tertiaryOrder (int32_t order)

Generated by  Doxygen 1.6.0   Back to index