Coverage Report

Created: 2018-09-25 14:53

/src/mozilla-central/intl/icu/source/i18n/unicode/coleitr.h
Line
Count
Source (jump to first uncovered line)
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
U_NAMESPACE_BEGIN
47
48
struct CollationData;
49
50
class CharacterIterator;
51
class CollationIterator;
52
class RuleBasedCollator;
53
class UCollationPCE;
54
class UVector32;
55
56
/**
57
* The CollationElementIterator class is used as an iterator to walk through     
58
* each character of an international string. Use the iterator to return the
59
* ordering priority of the positioned character. The ordering priority of a 
60
* character, which we refer to as a key, defines how a character is collated in 
61
* the given collation object.
62
* For example, consider the following in Slovak and in traditional Spanish collation:
63
* <pre>
64
*        "ca" -> the first key is key('c') and second key is key('a').
65
*        "cha" -> the first key is key('ch') and second key is key('a').</pre>
66
* And in German phonebook collation,
67
* <pre> \htmlonly       "&#x00E6;b"-> the first key is key('a'), the second key is key('e'), and
68
*        the third key is key('b'). \endhtmlonly </pre>
69
* The key of a character, is an integer composed of primary order(short),
70
* secondary order(char), and tertiary order(char). Java strictly defines the 
71
* size and signedness of its primitive data types. Therefore, the static
72
* functions primaryOrder(), secondaryOrder(), and tertiaryOrder() return 
73
* int32_t to ensure the correctness of the key value.
74
* <p>Example of the iterator usage: (without error checking)
75
* <pre>
76
* \code
77
*   void CollationElementIterator_Example()
78
*   {
79
*       UnicodeString str = "This is a test";
80
*       UErrorCode success = U_ZERO_ERROR;
81
*       RuleBasedCollator* rbc =
82
*           (RuleBasedCollator*) RuleBasedCollator::createInstance(success);
83
*       CollationElementIterator* c =
84
*           rbc->createCollationElementIterator( str );
85
*       int32_t order = c->next(success);
86
*       c->reset();
87
*       order = c->previous(success);
88
*       delete c;
89
*       delete rbc;
90
*   }
91
* \endcode
92
* </pre>
93
* <p>
94
* The method next() returns the collation order of the next character based on
95
* the comparison level of the collator. The method previous() returns the
96
* collation order of the previous character based on the comparison level of
97
* the collator. The Collation Element Iterator moves only in one direction
98
* between calls to reset(), setOffset(), or setText(). That is, next() 
99
* and previous() can not be inter-used. Whenever previous() is to be called after 
100
* next() or vice versa, reset(), setOffset() or setText() has to be called first
101
* to reset the status, shifting pointers to either the end or the start of
102
* the string (reset() or setText()), or the specified position (setOffset()).
103
* Hence at the next call of next() or previous(), the first or last collation order,
104
* or collation order at the spefcifieid position will be returned. If a change of
105
* direction is done without one of these calls, the result is undefined.
106
* <p>
107
* The result of a forward iterate (next()) and reversed result of the backward
108
* iterate (previous()) on the same string are equivalent, if collation orders
109
* with the value 0 are ignored.
110
* Character based on the comparison level of the collator.  A collation order 
111
* consists of primary order, secondary order and tertiary order.  The data 
112
* type of the collation order is <strong>int32_t</strong>. 
113
*
114
* Note, CollationElementIterator should not be subclassed.
115
* @see     Collator
116
* @see     RuleBasedCollator
117
* @version 1.8 Jan 16 2001
118
*/
119
class U_I18N_API CollationElementIterator U_FINAL : public UObject {
120
public: 
121
122
    // CollationElementIterator public data member ------------------------------
123
124
    enum {
125
        /**
126
         * NULLORDER indicates that an error has occured while processing
127
         * @stable ICU 2.0
128
         */
129
        NULLORDER = (int32_t)0xffffffff
130
    };
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
#ifndef U_HIDE_INTERNAL_API
290
    /** @internal */
291
0
    static inline CollationElementIterator *fromUCollationElements(UCollationElements *uc) {
292
0
        return reinterpret_cast<CollationElementIterator *>(uc);
293
0
    }
294
    /** @internal */
295
0
    static inline const CollationElementIterator *fromUCollationElements(const UCollationElements *uc) {
296
0
        return reinterpret_cast<const CollationElementIterator *>(uc);
297
0
    }
298
    /** @internal */
299
0
    inline UCollationElements *toUCollationElements() {
300
0
        return reinterpret_cast<UCollationElements *>(this);
301
0
    }
302
    /** @internal */
303
0
    inline const UCollationElements *toUCollationElements() const {
304
0
        return reinterpret_cast<const UCollationElements *>(this);
305
0
    }
306
#endif  // U_HIDE_INTERNAL_API
307
308
private:
309
    friend class RuleBasedCollator;
310
    friend class UCollationPCE;
311
312
    /**
313
    * CollationElementIterator constructor. This takes the source string and the 
314
    * collation object. The cursor will walk thru the source string based on the 
315
    * predefined collation rules. If the source string is empty, NULLORDER will 
316
    * be returned on the calls to next().
317
    * @param sourceText    the source string.
318
    * @param order         the collation object.
319
    * @param status        the error code status.
320
    */
321
    CollationElementIterator(const UnicodeString& sourceText,
322
        const RuleBasedCollator* order, UErrorCode& status);
323
    // Note: The constructors should take settings & tailoring, not a collator,
324
    // to avoid circular dependencies.
325
    // However, for operator==() we would need to be able to compare tailoring data for equality
326
    // without making CollationData or CollationTailoring depend on TailoredSet.
327
    // (See the implementation of RuleBasedCollator::operator==().)
328
    // That might require creating an intermediate class that would be used
329
    // by both CollationElementIterator and RuleBasedCollator
330
    // but only contain the part of RBC== related to data and rules.
331
332
    /**
333
    * CollationElementIterator constructor. This takes the source string and the 
334
    * collation object.  The cursor will walk thru the source string based on the 
335
    * predefined collation rules.  If the source string is empty, NULLORDER will 
336
    * be returned on the calls to next().
337
    * @param sourceText    the source string.
338
    * @param order         the collation object.
339
    * @param status        the error code status.
340
    */
341
    CollationElementIterator(const CharacterIterator& sourceText,
342
        const RuleBasedCollator* order, UErrorCode& status);
343
344
    /**
345
    * Assignment operator
346
    *
347
    * @param other    the object to be copied
348
    */
349
    const CollationElementIterator&
350
        operator=(const CollationElementIterator& other);
351
352
    CollationElementIterator(); // default constructor not implemented
353
354
    /** Normalizes dir_=1 (just after setOffset()) to dir_=0 (just after reset()). */
355
0
    inline int8_t normalizeDir() const { return dir_ == 1 ? 0 : dir_; }
356
357
    static UHashtable *computeMaxExpansions(const CollationData *data, UErrorCode &errorCode);
358
359
    static int32_t getMaxExpansion(const UHashtable *maxExpansions, int32_t order);
360
361
    // CollationElementIterator private data members ----------------------------
362
363
    CollationIterator *iter_;  // owned
364
    const RuleBasedCollator *rbc_;  // aliased
365
    uint32_t otherHalf_;
366
    /**
367
     * <0: backwards; 0: just after reset() (previous() begins from end);
368
     * 1: just after setOffset(); >1: forward
369
     */
370
    int8_t dir_;
371
    /**
372
     * Stores offsets from expansions and from unsafe-backwards iteration,
373
     * so that getOffset() returns intermediate offsets for the CEs
374
     * that are consistent with forward iteration.
375
     */
376
    UVector32 *offsets_;
377
378
    UnicodeString string_;
379
};
380
381
// CollationElementIterator inline method definitions --------------------------
382
383
inline int32_t CollationElementIterator::primaryOrder(int32_t order)
384
0
{
385
0
    return (order >> 16) & 0xffff;
386
0
}
387
388
inline int32_t CollationElementIterator::secondaryOrder(int32_t order)
389
0
{
390
0
    return (order >> 8) & 0xff;
391
0
}
392
393
inline int32_t CollationElementIterator::tertiaryOrder(int32_t order)
394
0
{
395
0
    return order & 0xff;
396
0
}
397
398
inline UBool CollationElementIterator::isIgnorable(int32_t order)
399
0
{
400
0
    return (order & 0xffff0000) == 0;
401
0
}
402
403
U_NAMESPACE_END
404
405
#endif /* #if !UCONFIG_NO_COLLATION */
406
407
#endif