icuSources/i18n/unicode/coleitr.h

   1 /*
   2  ******************************************************************************
   3  *   Copyright (C) 1997-2004, International Business Machines
   4  *   Corporation and others.  All Rights Reserved.
   5  ******************************************************************************
   6  */
   7
   8 /**
   9 * File coleitr.h
  10 *
  11 *
  12 *
  13 * Created by: Helena Shih
  14 *
  15 * Modification History:
  16 *
  17 *  Date       Name        Description
  18 *
  19 *  8/18/97    helena      Added internal API documentation.
  20 * 08/03/98    erm         Synched with 1.2 version CollationElementIterator.java
  21 * 12/10/99    aliu        Ported Thai collation support from Java.
  22 * 01/25/01    swquek      Modified into a C++ wrapper calling C APIs (ucoliter.h)
  23 * 02/19/01    swquek      Removed CollationElementsIterator() since it is
  24 *                         private constructor and no calls are made to it
  25 */
  26
  27 #ifndef COLEITR_H
  28 #define COLEITR_H
  29
  30 #include "unicode/utypes.h"
  31
  32 #if !UCONFIG_NO_COLLATION
  33
  34 #include "unicode/uobject.h"
  35 #include "unicode/tblcoll.h"
  36 #include "unicode/ucoleitr.h"
  37
  38 /**
  39  * The UCollationElements struct.
  40  * For usage in C programs.
  41  * @stable ICU 2.0
  42  */
  43 typedef struct UCollationElements UCollationElements;
  44
  45 U_NAMESPACE_BEGIN
  46
  47 /**
  48 * The CollationElementIterator class is used as an iterator to walk through
  49 * each character of an international string. Use the iterator to return the
  50 * ordering priority of the positioned character. The ordering priority of a
  51 * character, which we refer to as a key, defines how a character is collated in
  52 * the given collation object.
  53 * For example, consider the following in Spanish:
  54 * <pre>
  55 * \code
  56 *        "ca" -> the first key is key('c') and second key is key('a').
  57 *        "cha" -> the first key is key('ch') and second key is key('a').
  58 * \endcode
  59 * </pre>
  60 * And in German,
  61 * <pre>
  62 * \code
  63 *        "æb"-> the first key is key('a'), the second key is key('e'), and
  64 *        the third key is key('b').
  65 * \endcode
  66 * </pre>
  67 * The key of a character, is an integer composed of primary order(short),
  68 * secondary order(char), and tertiary order(char). Java strictly defines the
  69 * size and signedness of its primitive data types. Therefore, the static
  70 * functions primaryOrder(), secondaryOrder(), and tertiaryOrder() return
  71 * int32_t to ensure the correctness of the key value.
  72 * <p>Example of the iterator usage: (without error checking)
  73 * <pre>
  74 * \code
  75 *   void CollationElementIterator_Example()
  76 *   {
  77 *       UnicodeString str = "This is a test";
  78 *       UErrorCode success = U_ZERO_ERROR;
  79 *       RuleBasedCollator* rbc =
  80 *           (RuleBasedCollator*) RuleBasedCollator::createInstance(success);
  81 *       CollationElementIterator* c =
  82 *           rbc->createCollationElementIterator( str );
  83 *       int32_t order = c->next(success);
  84 *       c->reset();
  85 *       order = c->previous(success);
  86 *       delete c;
  87 *       delete rbc;
  88 *   }
  89 * \endcode
  90 * </pre>
  91 * <p>
  92 * CollationElementIterator::next returns the collation order of the next
  93 * character based on the comparison level of the collator.
  94 * CollationElementIterator::previous returns the collation order of the
  95 * previous character based on the comparison level of the collator.
  96 * The Collation Element Iterator moves only in one direction between calls to
  97 * CollationElementIterator::reset. That is, CollationElementIterator::next()
  98 * and CollationElementIterator::previous can not be inter-used. Whenever
  99 * CollationElementIterator::previous is to be called after
 100 * CollationElementIterator::next() or vice versa,
 101 * CollationElementIterator::reset has to be called first to reset the status,
 102 * shifting pointers to either the end or the start of the string. Hence at the
 103 * next call of CollationElementIterator::previous or
 104 * CollationElementIterator::next(), the first or last collation order will be
 105 * returned.
 106 * If a change of direction is done without a CollationElementIterator::reset(),
 107 * the result is undefined.
 108 * The result of a forward iterate (CollationElementIterator::next) and
 109 * reversed result of the backward iterate (CollationElementIterator::previous)
 110 * on the same string are equivalent, if collation orders with the value
 111 * UCOL_IGNORABLE are ignored.
 112 * Character based on the comparison level of the collator.  A collation order
 113 * consists of primary order, secondary order and tertiary order.  The data
 114 * type of the collation order is <strong>t_int32</strong>.
 115 *
 116 * Note, CollationElementIterator should not be subclassed.
 117 * @see     Collator
 118 * @see     RuleBasedCollator
 119 * @version 1.8 Jan 16 2001
 120 */
 121 class U_I18N_API CollationElementIterator : public UObject {
 122 public:
 123
 124     // CollationElementIterator public data member ------------------------------
 125
 126     /**
 127     * NULLORDER indicates that an error has occured while processing
 128     * @stable ICU 2.0
 129     */
 130     static int32_t const NULLORDER;
 131
 132     // CollationElementIterator public constructor/destructor -------------------
 133
 134     /**
 135     * Copy constructor.
 136     *
 137     * @param other    the object to be copied from
 138     * @stable ICU 2.0
 139     */
 140     CollationElementIterator(const CollationElementIterator& other);
 141
 142     /**
 143     * Destructor
 144     * @stable ICU 2.0
 145     */
 146     virtual ~CollationElementIterator();
 147
 148     // CollationElementIterator public methods ----------------------------------
 149
 150     /**
 151     * Returns true if "other" is the same as "this"
 152     *
 153     * @param other    the object to be compared
 154     * @return         true if "other" is the same as "this"
 155     * @stable ICU 2.0
 156     */
 157     UBool operator==(const CollationElementIterator& other) const;
 158
 159     /**
 160     * Returns true if "other" is not the same as "this".
 161     *
 162     * @param other    the object to be compared
 163     * @return         true if "other" is not the same as "this"
 164     * @stable ICU 2.0
 165     */
 166     UBool operator!=(const CollationElementIterator& other) const;
 167
 168     /**
 169     * Resets the cursor to the beginning of the string.
 170     * @stable ICU 2.0
 171     */
 172     void reset(void);
 173
 174     /**
 175     * Gets the ordering priority of the next character in the string.
 176     * @param status the error code status.
 177     * @return the next character's ordering. otherwise returns NULLORDER if an
 178     *         error has occured or if the end of string has been reached
 179     * @stable ICU 2.0
 180     */
 181     int32_t next(UErrorCode& status);
 182
 183     /**
 184     * Get the ordering priority of the previous collation element in the string.
 185     * @param status the error code status.
 186     * @return the previous element's ordering. otherwise returns NULLORDER if an
 187     *         error has occured or if the start of string has been reached
 188     * @stable ICU 2.0
 189     */
 190     int32_t previous(UErrorCode& status);
 191
 192     /**
 193     * Gets the primary order of a collation order.
 194     * @param order the collation order
 195     * @return the primary order of a collation order.
 196     * @stable ICU 2.0
 197     */
 198     static inline int32_t primaryOrder(int32_t order);
 199
 200     /**
 201     * Gets the secondary order of a collation order.
 202     * @param order the collation order
 203     * @return the secondary order of a collation order.
 204     * @stable ICU 2.0
 205     */
 206     static inline int32_t secondaryOrder(int32_t order);
 207
 208     /**
 209     * Gets the tertiary order of a collation order.
 210     * @param order the collation order
 211     * @return the tertiary order of a collation order.
 212     * @stable ICU 2.0
 213     */
 214     static inline int32_t tertiaryOrder(int32_t order);
 215
 216     /**
 217     * Return the maximum length of any expansion sequences that end with the
 218     * specified comparison order.
 219     * @param order a collation order returned by previous or next.
 220     * @return maximum size of the expansion sequences ending with the collation
 221     *         element or 1 if collation element does not occur at the end of any
 222     *         expansion sequence
 223     * @stable ICU 2.0
 224     */
 225     int32_t getMaxExpansion(int32_t order) const;
 226
 227     /**
 228     * Gets the comparison order in the desired strength. Ignore the other
 229     * differences.
 230     * @param order The order value
 231     * @stable ICU 2.0
 232     */
 233     int32_t strengthOrder(int32_t order) const;
 234
 235     /**
 236     * Sets the source string.
 237     * @param str the source string.
 238     * @param status the error code status.
 239     * @stable ICU 2.0
 240     */
 241     void setText(const UnicodeString& str, UErrorCode& status);
 242
 243     /**
 244     * Sets the source string.
 245     * @param str the source character iterator.
 246     * @param status the error code status.
 247     * @stable ICU 2.0
 248     */
 249     void setText(CharacterIterator& str, UErrorCode& status);
 250
 251     /**
 252     * Checks if a comparison order is ignorable.
 253     * @param order the collation order.
 254     * @return TRUE if a character is ignorable, FALSE otherwise.
 255     * @stable ICU 2.0
 256     */
 257     static inline UBool isIgnorable(int32_t order);
 258
 259     /**
 260     * Gets the offset of the currently processed character in the source string.
 261     * @return the offset of the character.
 262     * @stable ICU 2.0
 263     */
 264     int32_t getOffset(void) const;
 265
 266     /**
 267     * Sets the offset of the currently processed character in the source string.
 268     * @param newOffset the new offset.
 269     * @param status the error code status.
 270     * @return the offset of the character.
 271     * @stable ICU 2.0
 272     */
 273     void setOffset(int32_t newOffset, UErrorCode& status);
 274
 275     /**
 276     * ICU "poor man's RTTI", returns a UClassID for the actual class.
 277     *
 278     * @stable ICU 2.2
 279     */
 280     virtual UClassID getDynamicClassID() const;
 281
 282     /**
 283     * ICU "poor man's RTTI", returns a UClassID for this class.
 284     *
 285     * @stable ICU 2.2
 286     */
 287     static UClassID U_EXPORT2 getStaticClassID();
 288
 289 protected:
 290
 291     // CollationElementIterator protected constructors --------------------------
 292     /**
 293     * @stable ICU 2.0
 294     */
 295     friend class RuleBasedCollator;
 296
 297     /**
 298     * CollationElementIterator constructor. This takes the source string and the
 299     * collation object. The cursor will walk thru the source string based on the
 300     * predefined collation rules. If the source string is empty, NULLORDER will
 301     * be returned on the calls to next().
 302     * @param sourceText    the source string.
 303     * @param order         the collation object.
 304     * @param status        the error code status.
 305     * @stable ICU 2.0
 306     */
 307     CollationElementIterator(const UnicodeString& sourceText,
 308         const RuleBasedCollator* order, UErrorCode& status);
 309
 310     /**
 311     * CollationElementIterator constructor. This takes the source string and the
 312     * collation object.  The cursor will walk thru the source string based on the
 313     * predefined collation rules.  If the source string is empty, NULLORDER will
 314     * be returned on the calls to next().
 315     * @param sourceText    the source string.
 316     * @param order         the collation object.
 317     * @param status        the error code status.
 318     * @stable ICU 2.0
 319     */
 320     CollationElementIterator(const CharacterIterator& sourceText,
 321         const RuleBasedCollator* order, UErrorCode& status);
 322
 323     // CollationElementIterator protected methods -------------------------------
 324
 325     /**
 326     * Assignment operator
 327     *
 328     * @param other    the object to be copied
 329     * @stable ICU 2.0
 330     */
 331     const CollationElementIterator&
 332         operator=(const CollationElementIterator& other);
 333
 334 private:
 335     CollationElementIterator(); // default constructor not implemented
 336
 337     // CollationElementIterator private data members ----------------------------
 338
 339     /**
 340     * Data wrapper for collation elements
 341     */
 342     UCollationElements *m_data_;
 343
 344     /**
 345     * Indicates if m_data_ belongs to this object.
 346     */
 347     UBool isDataOwned_;
 348
 349 };
 350
 351 // CollationElementIterator inline method defination --------------------------
 352
 353 /**
 354 * Get the primary order of a collation order.
 355 * @param order the collation order
 356 * @return the primary order of a collation order.
 357 */
 358 inline int32_t CollationElementIterator::primaryOrder(int32_t order)
 359 {
 360     order &= RuleBasedCollator::PRIMARYORDERMASK;
 361     return (order >> RuleBasedCollator::PRIMARYORDERSHIFT);
 362 }
 363
 364 /**
 365 * Get the secondary order of a collation order.
 366 * @param order the collation order
 367 * @return the secondary order of a collation order.
 368 */
 369 inline int32_t CollationElementIterator::secondaryOrder(int32_t order)
 370 {
 371     order = order & RuleBasedCollator::SECONDARYORDERMASK;
 372     return (order >> RuleBasedCollator::SECONDARYORDERSHIFT);
 373 }
 374
 375 /**
 376 * Get the tertiary order of a collation order.
 377 * @param order the collation order
 378 * @return the tertiary order of a collation order.
 379 */
 380 inline int32_t CollationElementIterator::tertiaryOrder(int32_t order)
 381 {
 382     return (order &= RuleBasedCollator::TERTIARYORDERMASK);
 383 }
 384
 385 inline int32_t CollationElementIterator::getMaxExpansion(int32_t order) const
 386 {
 387     return ucol_getMaxExpansion(m_data_, (uint32_t)order);
 388 }
 389
 390 inline UBool CollationElementIterator::isIgnorable(int32_t order)
 391 {
 392     return (primaryOrder(order) == RuleBasedCollator::PRIMIGNORABLE);
 393 }
 394
 395 U_NAMESPACE_END
 396
 397 #endif /* #if !UCONFIG_NO_COLLATION */
 398
 399 #endif