intl/icu/source/i18n/unicode/coleitr.h@6474c204b198
intl/icu/source/i18n/unicode/coleitr.h
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
1 /*
2 ******************************************************************************
3 * Copyright (C) 1997-2013, International Business Machines
4 * Corporation and others. All Rights Reserved.
5 ******************************************************************************
6 */
8 /**
9 * \file
10 * \brief C++ API: Collation Element Iterator.
11 */
13 /**
14 * File coleitr.h
15 *
16 *
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 */
32 #ifndef COLEITR_H
33 #define COLEITR_H
35 #include "unicode/utypes.h"
38 #if !UCONFIG_NO_COLLATION
40 #include "unicode/uobject.h"
41 #include "unicode/tblcoll.h"
42 #include "unicode/ucoleitr.h"
44 /**
45 * The UCollationElements struct.
46 * For usage in C programs.
47 * @stable ICU 2.0
48 */
49 typedef struct UCollationElements UCollationElements;
51 U_NAMESPACE_BEGIN
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 Spanish:
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,
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 UCOL_IGNORABLE 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>t_int32</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:
119 // CollationElementIterator public data member ------------------------------
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 };
129 // CollationElementIterator public constructor/destructor -------------------
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);
139 /**
140 * Destructor
141 * @stable ICU 2.0
142 */
143 virtual ~CollationElementIterator();
145 // CollationElementIterator public methods ----------------------------------
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;
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;
165 /**
166 * Resets the cursor to the beginning of the string.
167 * @stable ICU 2.0
168 */
169 void reset(void);
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);
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);
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);
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);
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);
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;
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;
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);
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);
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);
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;
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);
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;
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();
286 private:
287 friend class RuleBasedCollator;
289 /**
290 * CollationElementIterator constructor. This takes the source string and the
291 * collation object. The cursor will walk thru the source string based on the
292 * predefined collation rules. If the source string is empty, NULLORDER will
293 * be returned on the calls to next().
294 * @param sourceText the source string.
295 * @param order the collation object.
296 * @param status the error code status.
297 */
298 CollationElementIterator(const UnicodeString& sourceText,
299 const RuleBasedCollator* order, UErrorCode& status);
301 /**
302 * CollationElementIterator constructor. This takes the source string and the
303 * collation object. The cursor will walk thru the source string based on the
304 * predefined collation rules. If the source string is empty, NULLORDER will
305 * be returned on the calls to next().
306 * @param sourceText the source string.
307 * @param order the collation object.
308 * @param status the error code status.
309 */
310 CollationElementIterator(const CharacterIterator& sourceText,
311 const RuleBasedCollator* order, UErrorCode& status);
313 /**
314 * Assignment operator
315 *
316 * @param other the object to be copied
317 */
318 const CollationElementIterator&
319 operator=(const CollationElementIterator& other);
321 CollationElementIterator(); // default constructor not implemented
323 // CollationElementIterator private data members ----------------------------
325 /**
326 * Data wrapper for collation elements
327 */
328 UCollationElements *m_data_;
330 /**
331 * Indicates if m_data_ belongs to this object.
332 */
333 UBool isDataOwned_;
334 };
336 // CollationElementIterator inline method defination --------------------------
338 /**
339 * Get the primary order of a collation order.
340 * @param order the collation order
341 * @return the primary order of a collation order.
342 */
343 inline int32_t CollationElementIterator::primaryOrder(int32_t order)
344 {
345 order &= RuleBasedCollator::PRIMARYORDERMASK;
346 return (order >> RuleBasedCollator::PRIMARYORDERSHIFT);
347 }
349 /**
350 * Get the secondary order of a collation order.
351 * @param order the collation order
352 * @return the secondary order of a collation order.
353 */
354 inline int32_t CollationElementIterator::secondaryOrder(int32_t order)
355 {
356 order = order & RuleBasedCollator::SECONDARYORDERMASK;
357 return (order >> RuleBasedCollator::SECONDARYORDERSHIFT);
358 }
360 /**
361 * Get the tertiary order of a collation order.
362 * @param order the collation order
363 * @return the tertiary order of a collation order.
364 */
365 inline int32_t CollationElementIterator::tertiaryOrder(int32_t order)
366 {
367 return (order &= RuleBasedCollator::TERTIARYORDERMASK);
368 }
370 inline int32_t CollationElementIterator::getMaxExpansion(int32_t order) const
371 {
372 return ucol_getMaxExpansion(m_data_, (uint32_t)order);
373 }
375 inline UBool CollationElementIterator::isIgnorable(int32_t order)
376 {
377 return (primaryOrder(order) == RuleBasedCollator::PRIMIGNORABLE);
378 }
380 U_NAMESPACE_END
382 #endif /* #if !UCONFIG_NO_COLLATION */
384 #endif
