icuSources/i18n/unicode/coleitr.h

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