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