Remove copy of ICU headers from WebKit
[WebKit-https.git] / Source / WTF / icu / unicode / coleitr.h
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       "&#x00E6;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 U_FINAL : 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