/src/icu/source/i18n/unicode/tblcoll.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) 1996-2016, International Business Machines Corporation and |
6 | | * others. All Rights Reserved. |
7 | | ****************************************************************************** |
8 | | */ |
9 | | |
10 | | /** |
11 | | * \file |
12 | | * \brief C++ API: The RuleBasedCollator class implements the Collator abstract base class. |
13 | | */ |
14 | | |
15 | | /** |
16 | | * File tblcoll.h |
17 | | * |
18 | | * Created by: Helena Shih |
19 | | * |
20 | | * Modification History: |
21 | | * |
22 | | * Date Name Description |
23 | | * 2/5/97 aliu Added streamIn and streamOut methods. Added |
24 | | * constructor which reads RuleBasedCollator object from |
25 | | * a binary file. Added writeToFile method which streams |
26 | | * RuleBasedCollator out to a binary file. The streamIn |
27 | | * and streamOut methods use istream and ostream objects |
28 | | * in binary mode. |
29 | | * 2/12/97 aliu Modified to use TableCollationData sub-object to |
30 | | * hold invariant data. |
31 | | * 2/13/97 aliu Moved several methods into this class from Collation. |
32 | | * Added a private RuleBasedCollator(Locale&) constructor, |
33 | | * to be used by Collator::createDefault(). General |
34 | | * clean up. |
35 | | * 2/20/97 helena Added clone, operator==, operator!=, operator=, and copy |
36 | | * constructor and getDynamicClassID. |
37 | | * 3/5/97 aliu Modified constructFromFile() to add parameter |
38 | | * specifying whether or not binary loading is to be |
39 | | * attempted. This is required for dynamic rule loading. |
40 | | * 05/07/97 helena Added memory allocation error detection. |
41 | | * 6/17/97 helena Added IDENTICAL strength for compare, changed getRules to |
42 | | * use MergeCollation::getPattern. |
43 | | * 6/20/97 helena Java class name change. |
44 | | * 8/18/97 helena Added internal API documentation. |
45 | | * 09/03/97 helena Added createCollationKeyValues(). |
46 | | * 02/10/98 damiba Added compare with "length" parameter |
47 | | * 08/05/98 erm Synched with 1.2 version of RuleBasedCollator.java |
48 | | * 04/23/99 stephen Removed EDecompositionMode, merged with |
49 | | * Normalizer::EMode |
50 | | * 06/14/99 stephen Removed kResourceBundleSuffix |
51 | | * 11/02/99 helena Collator performance enhancements. Eliminates the |
52 | | * UnicodeString construction and special case for NO_OP. |
53 | | * 11/23/99 srl More performance enhancements. Updates to NormalizerIterator |
54 | | * internal state management. |
55 | | * 12/15/99 aliu Update to support Thai collation. Move NormalizerIterator |
56 | | * to implementation file. |
57 | | * 01/29/01 synwee Modified into a C++ wrapper which calls C API |
58 | | * (ucol.h) |
59 | | * 2012-2014 markus Rewritten in C++ again. |
60 | | */ |
61 | | |
62 | | #ifndef TBLCOLL_H |
63 | | #define TBLCOLL_H |
64 | | |
65 | | #include "unicode/utypes.h" |
66 | | |
67 | | #if U_SHOW_CPLUSPLUS_API |
68 | | |
69 | | #if !UCONFIG_NO_COLLATION |
70 | | |
71 | | #include "unicode/coll.h" |
72 | | #include "unicode/locid.h" |
73 | | #include "unicode/uiter.h" |
74 | | #include "unicode/ucol.h" |
75 | | |
76 | | U_NAMESPACE_BEGIN |
77 | | |
78 | | struct CollationCacheEntry; |
79 | | struct CollationData; |
80 | | struct CollationSettings; |
81 | | struct CollationTailoring; |
82 | | /** |
83 | | * @stable ICU 2.0 |
84 | | */ |
85 | | class StringSearch; |
86 | | /** |
87 | | * @stable ICU 2.0 |
88 | | */ |
89 | | class CollationElementIterator; |
90 | | class CollationKey; |
91 | | class SortKeyByteSink; |
92 | | class UnicodeSet; |
93 | | class UnicodeString; |
94 | | class UVector64; |
95 | | |
96 | | /** |
97 | | * The RuleBasedCollator class provides the implementation of |
98 | | * Collator, using data-driven tables. The user can create a customized |
99 | | * table-based collation. |
100 | | * <p> |
101 | | * For more information about the collation service see |
102 | | * <a href="https://unicode-org.github.io/icu/userguide/collation">the User Guide</a>. |
103 | | * <p> |
104 | | * Collation service provides correct sorting orders for most locales supported in ICU. |
105 | | * If specific data for a locale is not available, the orders eventually falls back |
106 | | * to the <a href="http://www.unicode.org/reports/tr35/tr35-collation.html#Root_Collation">CLDR root sort order</a>. |
107 | | * <p> |
108 | | * Sort ordering may be customized by providing your own set of rules. For more on |
109 | | * this subject see the <a href="https://unicode-org.github.io/icu/userguide/collation/customization"> |
110 | | * Collation Customization</a> section of the User Guide. |
111 | | * <p> |
112 | | * Note, RuleBasedCollator is not to be subclassed. |
113 | | * @see Collator |
114 | | */ |
115 | | class U_I18N_API RuleBasedCollator U_FINAL : public Collator { |
116 | | public: |
117 | | /** |
118 | | * RuleBasedCollator constructor. This takes the table rules and builds a |
119 | | * collation table out of them. Please see RuleBasedCollator class |
120 | | * description for more details on the collation rule syntax. |
121 | | * @param rules the collation rules to build the collation table from. |
122 | | * @param status reporting a success or an error. |
123 | | * @stable ICU 2.0 |
124 | | */ |
125 | | RuleBasedCollator(const UnicodeString& rules, UErrorCode& status); |
126 | | |
127 | | /** |
128 | | * RuleBasedCollator constructor. This takes the table rules and builds a |
129 | | * collation table out of them. Please see RuleBasedCollator class |
130 | | * description for more details on the collation rule syntax. |
131 | | * @param rules the collation rules to build the collation table from. |
132 | | * @param collationStrength strength for comparison |
133 | | * @param status reporting a success or an error. |
134 | | * @stable ICU 2.0 |
135 | | */ |
136 | | RuleBasedCollator(const UnicodeString& rules, |
137 | | ECollationStrength collationStrength, |
138 | | UErrorCode& status); |
139 | | |
140 | | /** |
141 | | * RuleBasedCollator constructor. This takes the table rules and builds a |
142 | | * collation table out of them. Please see RuleBasedCollator class |
143 | | * description for more details on the collation rule syntax. |
144 | | * @param rules the collation rules to build the collation table from. |
145 | | * @param decompositionMode the normalisation mode |
146 | | * @param status reporting a success or an error. |
147 | | * @stable ICU 2.0 |
148 | | */ |
149 | | RuleBasedCollator(const UnicodeString& rules, |
150 | | UColAttributeValue decompositionMode, |
151 | | UErrorCode& status); |
152 | | |
153 | | /** |
154 | | * RuleBasedCollator constructor. This takes the table rules and builds a |
155 | | * collation table out of them. Please see RuleBasedCollator class |
156 | | * description for more details on the collation rule syntax. |
157 | | * @param rules the collation rules to build the collation table from. |
158 | | * @param collationStrength strength for comparison |
159 | | * @param decompositionMode the normalisation mode |
160 | | * @param status reporting a success or an error. |
161 | | * @stable ICU 2.0 |
162 | | */ |
163 | | RuleBasedCollator(const UnicodeString& rules, |
164 | | ECollationStrength collationStrength, |
165 | | UColAttributeValue decompositionMode, |
166 | | UErrorCode& status); |
167 | | |
168 | | #ifndef U_HIDE_INTERNAL_API |
169 | | /** |
170 | | * TODO: document & propose as public API |
171 | | * @internal |
172 | | */ |
173 | | RuleBasedCollator(const UnicodeString &rules, |
174 | | UParseError &parseError, UnicodeString &reason, |
175 | | UErrorCode &errorCode); |
176 | | #endif /* U_HIDE_INTERNAL_API */ |
177 | | |
178 | | /** |
179 | | * Copy constructor. |
180 | | * @param other the RuleBasedCollator object to be copied |
181 | | * @stable ICU 2.0 |
182 | | */ |
183 | | RuleBasedCollator(const RuleBasedCollator& other); |
184 | | |
185 | | |
186 | | /** Opens a collator from a collator binary image created using |
187 | | * cloneBinary. Binary image used in instantiation of the |
188 | | * collator remains owned by the user and should stay around for |
189 | | * the lifetime of the collator. The API also takes a base collator |
190 | | * which must be the root collator. |
191 | | * @param bin binary image owned by the user and required through the |
192 | | * lifetime of the collator |
193 | | * @param length size of the image. If negative, the API will try to |
194 | | * figure out the length of the image |
195 | | * @param base Base collator, for lookup of untailored characters. |
196 | | * Must be the root collator, must not be NULL. |
197 | | * The base is required to be present through the lifetime of the collator. |
198 | | * @param status for catching errors |
199 | | * @return newly created collator |
200 | | * @see cloneBinary |
201 | | * @stable ICU 3.4 |
202 | | */ |
203 | | RuleBasedCollator(const uint8_t *bin, int32_t length, |
204 | | const RuleBasedCollator *base, |
205 | | UErrorCode &status); |
206 | | |
207 | | /** |
208 | | * Destructor. |
209 | | * @stable ICU 2.0 |
210 | | */ |
211 | | virtual ~RuleBasedCollator(); |
212 | | |
213 | | /** |
214 | | * Assignment operator. |
215 | | * @param other other RuleBasedCollator object to copy from. |
216 | | * @stable ICU 2.0 |
217 | | */ |
218 | | RuleBasedCollator& operator=(const RuleBasedCollator& other); |
219 | | |
220 | | /** |
221 | | * Returns true if argument is the same as this object. |
222 | | * @param other Collator object to be compared. |
223 | | * @return true if arguments is the same as this object. |
224 | | * @stable ICU 2.0 |
225 | | */ |
226 | | virtual bool operator==(const Collator& other) const; |
227 | | |
228 | | /** |
229 | | * Makes a copy of this object. |
230 | | * @return a copy of this object, owned by the caller |
231 | | * @stable ICU 2.0 |
232 | | */ |
233 | | virtual RuleBasedCollator* clone() const; |
234 | | |
235 | | /** |
236 | | * Creates a collation element iterator for the source string. The caller of |
237 | | * this method is responsible for the memory management of the return |
238 | | * pointer. |
239 | | * @param source the string over which the CollationElementIterator will |
240 | | * iterate. |
241 | | * @return the collation element iterator of the source string using this as |
242 | | * the based Collator. |
243 | | * @stable ICU 2.2 |
244 | | */ |
245 | | virtual CollationElementIterator* createCollationElementIterator( |
246 | | const UnicodeString& source) const; |
247 | | |
248 | | /** |
249 | | * Creates a collation element iterator for the source. The caller of this |
250 | | * method is responsible for the memory management of the returned pointer. |
251 | | * @param source the CharacterIterator which produces the characters over |
252 | | * which the CollationElementItgerator will iterate. |
253 | | * @return the collation element iterator of the source using this as the |
254 | | * based Collator. |
255 | | * @stable ICU 2.2 |
256 | | */ |
257 | | virtual CollationElementIterator* createCollationElementIterator( |
258 | | const CharacterIterator& source) const; |
259 | | |
260 | | // Make deprecated versions of Collator::compare() visible. |
261 | | using Collator::compare; |
262 | | |
263 | | /** |
264 | | * The comparison function compares the character data stored in two |
265 | | * different strings. Returns information about whether a string is less |
266 | | * than, greater than or equal to another string. |
267 | | * @param source the source string to be compared with. |
268 | | * @param target the string that is to be compared with the source string. |
269 | | * @param status possible error code |
270 | | * @return Returns an enum value. UCOL_GREATER if source is greater |
271 | | * than target; UCOL_EQUAL if source is equal to target; UCOL_LESS if source is less |
272 | | * than target |
273 | | * @stable ICU 2.6 |
274 | | **/ |
275 | | virtual UCollationResult compare(const UnicodeString& source, |
276 | | const UnicodeString& target, |
277 | | UErrorCode &status) const; |
278 | | |
279 | | /** |
280 | | * Does the same thing as compare but limits the comparison to a specified |
281 | | * length |
282 | | * @param source the source string to be compared with. |
283 | | * @param target the string that is to be compared with the source string. |
284 | | * @param length the length the comparison is limited to |
285 | | * @param status possible error code |
286 | | * @return Returns an enum value. UCOL_GREATER if source (up to the specified |
287 | | * length) is greater than target; UCOL_EQUAL if source (up to specified |
288 | | * length) is equal to target; UCOL_LESS if source (up to the specified |
289 | | * length) is less than target. |
290 | | * @stable ICU 2.6 |
291 | | */ |
292 | | virtual UCollationResult compare(const UnicodeString& source, |
293 | | const UnicodeString& target, |
294 | | int32_t length, |
295 | | UErrorCode &status) const; |
296 | | |
297 | | /** |
298 | | * The comparison function compares the character data stored in two |
299 | | * different string arrays. Returns information about whether a string array |
300 | | * is less than, greater than or equal to another string array. |
301 | | * @param source the source string array to be compared with. |
302 | | * @param sourceLength the length of the source string array. If this value |
303 | | * is equal to -1, the string array is null-terminated. |
304 | | * @param target the string that is to be compared with the source string. |
305 | | * @param targetLength the length of the target string array. If this value |
306 | | * is equal to -1, the string array is null-terminated. |
307 | | * @param status possible error code |
308 | | * @return Returns an enum value. UCOL_GREATER if source is greater |
309 | | * than target; UCOL_EQUAL if source is equal to target; UCOL_LESS if source is less |
310 | | * than target |
311 | | * @stable ICU 2.6 |
312 | | */ |
313 | | virtual UCollationResult compare(const char16_t* source, int32_t sourceLength, |
314 | | const char16_t* target, int32_t targetLength, |
315 | | UErrorCode &status) const; |
316 | | |
317 | | /** |
318 | | * Compares two strings using the Collator. |
319 | | * Returns whether the first one compares less than/equal to/greater than |
320 | | * the second one. |
321 | | * This version takes UCharIterator input. |
322 | | * @param sIter the first ("source") string iterator |
323 | | * @param tIter the second ("target") string iterator |
324 | | * @param status ICU status |
325 | | * @return UCOL_LESS, UCOL_EQUAL or UCOL_GREATER |
326 | | * @stable ICU 4.2 |
327 | | */ |
328 | | virtual UCollationResult compare(UCharIterator &sIter, |
329 | | UCharIterator &tIter, |
330 | | UErrorCode &status) const; |
331 | | |
332 | | /** |
333 | | * Compares two UTF-8 strings using the Collator. |
334 | | * Returns whether the first one compares less than/equal to/greater than |
335 | | * the second one. |
336 | | * This version takes UTF-8 input. |
337 | | * Note that a StringPiece can be implicitly constructed |
338 | | * from a std::string or a NUL-terminated const char * string. |
339 | | * @param source the first UTF-8 string |
340 | | * @param target the second UTF-8 string |
341 | | * @param status ICU status |
342 | | * @return UCOL_LESS, UCOL_EQUAL or UCOL_GREATER |
343 | | * @stable ICU 51 |
344 | | */ |
345 | | virtual UCollationResult compareUTF8(const StringPiece &source, |
346 | | const StringPiece &target, |
347 | | UErrorCode &status) const; |
348 | | |
349 | | /** |
350 | | * Transforms the string into a series of characters |
351 | | * that can be compared with CollationKey.compare(). |
352 | | * |
353 | | * Note that sort keys are often less efficient than simply doing comparison. |
354 | | * For more details, see the ICU User Guide. |
355 | | * |
356 | | * @param source the source string. |
357 | | * @param key the transformed key of the source string. |
358 | | * @param status the error code status. |
359 | | * @return the transformed key. |
360 | | * @see CollationKey |
361 | | * @stable ICU 2.0 |
362 | | */ |
363 | | virtual CollationKey& getCollationKey(const UnicodeString& source, |
364 | | CollationKey& key, |
365 | | UErrorCode& status) const; |
366 | | |
367 | | /** |
368 | | * Transforms a specified region of the string into a series of characters |
369 | | * that can be compared with CollationKey.compare. |
370 | | * |
371 | | * Note that sort keys are often less efficient than simply doing comparison. |
372 | | * For more details, see the ICU User Guide. |
373 | | * |
374 | | * @param source the source string. |
375 | | * @param sourceLength the length of the source string. |
376 | | * @param key the transformed key of the source string. |
377 | | * @param status the error code status. |
378 | | * @return the transformed key. |
379 | | * @see CollationKey |
380 | | * @stable ICU 2.0 |
381 | | */ |
382 | | virtual CollationKey& getCollationKey(const char16_t *source, |
383 | | int32_t sourceLength, |
384 | | CollationKey& key, |
385 | | UErrorCode& status) const; |
386 | | |
387 | | /** |
388 | | * Generates the hash code for the rule-based collation object. |
389 | | * @return the hash code. |
390 | | * @stable ICU 2.0 |
391 | | */ |
392 | | virtual int32_t hashCode() const; |
393 | | |
394 | | #ifndef U_FORCE_HIDE_DEPRECATED_API |
395 | | /** |
396 | | * Gets the locale of the Collator |
397 | | * @param type can be either requested, valid or actual locale. For more |
398 | | * information see the definition of ULocDataLocaleType in |
399 | | * uloc.h |
400 | | * @param status the error code status. |
401 | | * @return locale where the collation data lives. If the collator |
402 | | * was instantiated from rules, locale is empty. |
403 | | * @deprecated ICU 2.8 likely to change in ICU 3.0, based on feedback |
404 | | */ |
405 | | virtual Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const; |
406 | | #endif // U_FORCE_HIDE_DEPRECATED_API |
407 | | |
408 | | /** |
409 | | * Gets the tailoring rules for this collator. |
410 | | * @return the collation tailoring from which this collator was created |
411 | | * @stable ICU 2.0 |
412 | | */ |
413 | | const UnicodeString& getRules() const; |
414 | | |
415 | | /** |
416 | | * Gets the version information for a Collator. |
417 | | * @param info the version # information, the result will be filled in |
418 | | * @stable ICU 2.0 |
419 | | */ |
420 | | virtual void getVersion(UVersionInfo info) const; |
421 | | |
422 | | #ifndef U_HIDE_DEPRECATED_API |
423 | | /** |
424 | | * Returns the maximum length of any expansion sequences that end with the |
425 | | * specified comparison order. |
426 | | * |
427 | | * This is specific to the kind of collation element values and sequences |
428 | | * returned by the CollationElementIterator. |
429 | | * Call CollationElementIterator::getMaxExpansion() instead. |
430 | | * |
431 | | * @param order a collation order returned by CollationElementIterator::previous |
432 | | * or CollationElementIterator::next. |
433 | | * @return maximum size of the expansion sequences ending with the collation |
434 | | * element, or 1 if the collation element does not occur at the end of |
435 | | * any expansion sequence |
436 | | * @see CollationElementIterator#getMaxExpansion |
437 | | * @deprecated ICU 51 Use CollationElementIterator::getMaxExpansion() instead. |
438 | | */ |
439 | | int32_t getMaxExpansion(int32_t order) const; |
440 | | #endif /* U_HIDE_DEPRECATED_API */ |
441 | | |
442 | | /** |
443 | | * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This |
444 | | * method is to implement a simple version of RTTI, since not all C++ |
445 | | * compilers support genuine RTTI. Polymorphic operator==() and clone() |
446 | | * methods call this method. |
447 | | * @return The class ID for this object. All objects of a given class have |
448 | | * the same class ID. Objects of other classes have different class |
449 | | * IDs. |
450 | | * @stable ICU 2.0 |
451 | | */ |
452 | | virtual UClassID getDynamicClassID(void) const; |
453 | | |
454 | | /** |
455 | | * Returns the class ID for this class. This is useful only for comparing to |
456 | | * a return value from getDynamicClassID(). For example: |
457 | | * <pre> |
458 | | * Base* polymorphic_pointer = createPolymorphicObject(); |
459 | | * if (polymorphic_pointer->getDynamicClassID() == |
460 | | * Derived::getStaticClassID()) ... |
461 | | * </pre> |
462 | | * @return The class ID for all objects of this class. |
463 | | * @stable ICU 2.0 |
464 | | */ |
465 | | static UClassID U_EXPORT2 getStaticClassID(void); |
466 | | |
467 | | #ifndef U_HIDE_DEPRECATED_API |
468 | | /** |
469 | | * Do not use this method: The caller and the ICU library might use different heaps. |
470 | | * Use cloneBinary() instead which writes to caller-provided memory. |
471 | | * |
472 | | * Returns a binary format of this collator. |
473 | | * @param length Returns the length of the data, in bytes |
474 | | * @param status the error code status. |
475 | | * @return memory, owned by the caller, of size 'length' bytes. |
476 | | * @deprecated ICU 52. Use cloneBinary() instead. |
477 | | */ |
478 | | uint8_t *cloneRuleData(int32_t &length, UErrorCode &status) const; |
479 | | #endif /* U_HIDE_DEPRECATED_API */ |
480 | | |
481 | | /** Creates a binary image of a collator. This binary image can be stored and |
482 | | * later used to instantiate a collator using ucol_openBinary. |
483 | | * This API supports preflighting. |
484 | | * @param buffer a fill-in buffer to receive the binary image |
485 | | * @param capacity capacity of the destination buffer |
486 | | * @param status for catching errors |
487 | | * @return size of the image |
488 | | * @see ucol_openBinary |
489 | | * @stable ICU 3.4 |
490 | | */ |
491 | | int32_t cloneBinary(uint8_t *buffer, int32_t capacity, UErrorCode &status) const; |
492 | | |
493 | | /** |
494 | | * Returns current rules. Delta defines whether full rules are returned or |
495 | | * just the tailoring. |
496 | | * |
497 | | * getRules(void) should normally be used instead. |
498 | | * See https://unicode-org.github.io/icu/userguide/collation/customization#building-on-existing-locales |
499 | | * @param delta one of UCOL_TAILORING_ONLY, UCOL_FULL_RULES. |
500 | | * @param buffer UnicodeString to store the result rules |
501 | | * @stable ICU 2.2 |
502 | | * @see UCOL_FULL_RULES |
503 | | */ |
504 | | void getRules(UColRuleOption delta, UnicodeString &buffer) const; |
505 | | |
506 | | /** |
507 | | * Universal attribute setter |
508 | | * @param attr attribute type |
509 | | * @param value attribute value |
510 | | * @param status to indicate whether the operation went on smoothly or there were errors |
511 | | * @stable ICU 2.2 |
512 | | */ |
513 | | virtual void setAttribute(UColAttribute attr, UColAttributeValue value, |
514 | | UErrorCode &status); |
515 | | |
516 | | /** |
517 | | * Universal attribute getter. |
518 | | * @param attr attribute type |
519 | | * @param status to indicate whether the operation went on smoothly or there were errors |
520 | | * @return attribute value |
521 | | * @stable ICU 2.2 |
522 | | */ |
523 | | virtual UColAttributeValue getAttribute(UColAttribute attr, |
524 | | UErrorCode &status) const; |
525 | | |
526 | | /** |
527 | | * Sets the variable top to the top of the specified reordering group. |
528 | | * The variable top determines the highest-sorting character |
529 | | * which is affected by UCOL_ALTERNATE_HANDLING. |
530 | | * If that attribute is set to UCOL_NON_IGNORABLE, then the variable top has no effect. |
531 | | * @param group one of UCOL_REORDER_CODE_SPACE, UCOL_REORDER_CODE_PUNCTUATION, |
532 | | * UCOL_REORDER_CODE_SYMBOL, UCOL_REORDER_CODE_CURRENCY; |
533 | | * or UCOL_REORDER_CODE_DEFAULT to restore the default max variable group |
534 | | * @param errorCode Standard ICU error code. Its input value must |
535 | | * pass the U_SUCCESS() test, or else the function returns |
536 | | * immediately. Check for U_FAILURE() on output or use with |
537 | | * function chaining. (See User Guide for details.) |
538 | | * @return *this |
539 | | * @see getMaxVariable |
540 | | * @stable ICU 53 |
541 | | */ |
542 | | virtual Collator &setMaxVariable(UColReorderCode group, UErrorCode &errorCode); |
543 | | |
544 | | /** |
545 | | * Returns the maximum reordering group whose characters are affected by UCOL_ALTERNATE_HANDLING. |
546 | | * @return the maximum variable reordering group. |
547 | | * @see setMaxVariable |
548 | | * @stable ICU 53 |
549 | | */ |
550 | | virtual UColReorderCode getMaxVariable() const; |
551 | | |
552 | | #ifndef U_FORCE_HIDE_DEPRECATED_API |
553 | | /** |
554 | | * Sets the variable top to the primary weight of the specified string. |
555 | | * |
556 | | * Beginning with ICU 53, the variable top is pinned to |
557 | | * the top of one of the supported reordering groups, |
558 | | * and it must not be beyond the last of those groups. |
559 | | * See setMaxVariable(). |
560 | | * @param varTop one or more (if contraction) char16_ts to which the variable top should be set |
561 | | * @param len length of variable top string. If -1 it is considered to be zero terminated. |
562 | | * @param status error code. If error code is set, the return value is undefined. Errors set by this function are: <br> |
563 | | * U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no such contraction<br> |
564 | | * U_ILLEGAL_ARGUMENT_ERROR if the variable top is beyond |
565 | | * the last reordering group supported by setMaxVariable() |
566 | | * @return variable top primary weight |
567 | | * @deprecated ICU 53 Call setMaxVariable() instead. |
568 | | */ |
569 | | virtual uint32_t setVariableTop(const char16_t *varTop, int32_t len, UErrorCode &status); |
570 | | |
571 | | /** |
572 | | * Sets the variable top to the primary weight of the specified string. |
573 | | * |
574 | | * Beginning with ICU 53, the variable top is pinned to |
575 | | * the top of one of the supported reordering groups, |
576 | | * and it must not be beyond the last of those groups. |
577 | | * See setMaxVariable(). |
578 | | * @param varTop a UnicodeString size 1 or more (if contraction) of char16_ts to which the variable top should be set |
579 | | * @param status error code. If error code is set, the return value is undefined. Errors set by this function are: <br> |
580 | | * U_CE_NOT_FOUND_ERROR if more than one character was passed and there is no such contraction<br> |
581 | | * U_ILLEGAL_ARGUMENT_ERROR if the variable top is beyond |
582 | | * the last reordering group supported by setMaxVariable() |
583 | | * @return variable top primary weight |
584 | | * @deprecated ICU 53 Call setMaxVariable() instead. |
585 | | */ |
586 | | virtual uint32_t setVariableTop(const UnicodeString &varTop, UErrorCode &status); |
587 | | |
588 | | /** |
589 | | * Sets the variable top to the specified primary weight. |
590 | | * |
591 | | * Beginning with ICU 53, the variable top is pinned to |
592 | | * the top of one of the supported reordering groups, |
593 | | * and it must not be beyond the last of those groups. |
594 | | * See setMaxVariable(). |
595 | | * @param varTop primary weight, as returned by setVariableTop or ucol_getVariableTop |
596 | | * @param status error code |
597 | | * @deprecated ICU 53 Call setMaxVariable() instead. |
598 | | */ |
599 | | virtual void setVariableTop(uint32_t varTop, UErrorCode &status); |
600 | | #endif // U_FORCE_HIDE_DEPRECATED_API |
601 | | |
602 | | /** |
603 | | * Gets the variable top value of a Collator. |
604 | | * @param status error code (not changed by function). If error code is set, the return value is undefined. |
605 | | * @return the variable top primary weight |
606 | | * @see getMaxVariable |
607 | | * @stable ICU 2.0 |
608 | | */ |
609 | | virtual uint32_t getVariableTop(UErrorCode &status) const; |
610 | | |
611 | | /** |
612 | | * Get a UnicodeSet that contains all the characters and sequences tailored in |
613 | | * this collator. |
614 | | * @param status error code of the operation |
615 | | * @return a pointer to a UnicodeSet object containing all the |
616 | | * code points and sequences that may sort differently than |
617 | | * in the root collator. The object must be disposed of by using delete |
618 | | * @stable ICU 2.4 |
619 | | */ |
620 | | virtual UnicodeSet *getTailoredSet(UErrorCode &status) const; |
621 | | |
622 | | /** |
623 | | * Get the sort key as an array of bytes from a UnicodeString. |
624 | | * |
625 | | * Note that sort keys are often less efficient than simply doing comparison. |
626 | | * For more details, see the ICU User Guide. |
627 | | * |
628 | | * @param source string to be processed. |
629 | | * @param result buffer to store result in. If NULL, number of bytes needed |
630 | | * will be returned. |
631 | | * @param resultLength length of the result buffer. If if not enough the |
632 | | * buffer will be filled to capacity. |
633 | | * @return Number of bytes needed for storing the sort key |
634 | | * @stable ICU 2.0 |
635 | | */ |
636 | | virtual int32_t getSortKey(const UnicodeString& source, uint8_t *result, |
637 | | int32_t resultLength) const; |
638 | | |
639 | | /** |
640 | | * Get the sort key as an array of bytes from a char16_t buffer. |
641 | | * |
642 | | * Note that sort keys are often less efficient than simply doing comparison. |
643 | | * For more details, see the ICU User Guide. |
644 | | * |
645 | | * @param source string to be processed. |
646 | | * @param sourceLength length of string to be processed. If -1, the string |
647 | | * is 0 terminated and length will be decided by the function. |
648 | | * @param result buffer to store result in. If NULL, number of bytes needed |
649 | | * will be returned. |
650 | | * @param resultLength length of the result buffer. If if not enough the |
651 | | * buffer will be filled to capacity. |
652 | | * @return Number of bytes needed for storing the sort key |
653 | | * @stable ICU 2.2 |
654 | | */ |
655 | | virtual int32_t getSortKey(const char16_t *source, int32_t sourceLength, |
656 | | uint8_t *result, int32_t resultLength) const; |
657 | | |
658 | | /** |
659 | | * Retrieves the reordering codes for this collator. |
660 | | * @param dest The array to fill with the script ordering. |
661 | | * @param destCapacity The length of dest. If it is 0, then dest may be NULL and the function |
662 | | * will only return the length of the result without writing any codes (pre-flighting). |
663 | | * @param status A reference to an error code value, which must not indicate |
664 | | * a failure before the function call. |
665 | | * @return The length of the script ordering array. |
666 | | * @see ucol_setReorderCodes |
667 | | * @see Collator#getEquivalentReorderCodes |
668 | | * @see Collator#setReorderCodes |
669 | | * @stable ICU 4.8 |
670 | | */ |
671 | | virtual int32_t getReorderCodes(int32_t *dest, |
672 | | int32_t destCapacity, |
673 | | UErrorCode& status) const; |
674 | | |
675 | | /** |
676 | | * Sets the ordering of scripts for this collator. |
677 | | * @param reorderCodes An array of script codes in the new order. This can be NULL if the |
678 | | * length is also set to 0. An empty array will clear any reordering codes on the collator. |
679 | | * @param reorderCodesLength The length of reorderCodes. |
680 | | * @param status error code |
681 | | * @see ucol_setReorderCodes |
682 | | * @see Collator#getReorderCodes |
683 | | * @see Collator#getEquivalentReorderCodes |
684 | | * @stable ICU 4.8 |
685 | | */ |
686 | | virtual void setReorderCodes(const int32_t* reorderCodes, |
687 | | int32_t reorderCodesLength, |
688 | | UErrorCode& status) ; |
689 | | |
690 | | /** |
691 | | * Implements ucol_strcollUTF8(). |
692 | | * @internal |
693 | | */ |
694 | | virtual UCollationResult internalCompareUTF8( |
695 | | const char *left, int32_t leftLength, |
696 | | const char *right, int32_t rightLength, |
697 | | UErrorCode &errorCode) const; |
698 | | |
699 | | /** Get the short definition string for a collator. This internal API harvests the collator's |
700 | | * locale and the attribute set and produces a string that can be used for opening |
701 | | * a collator with the same attributes using the ucol_openFromShortString API. |
702 | | * This string will be normalized. |
703 | | * The structure and the syntax of the string is defined in the "Naming collators" |
704 | | * section of the users guide: |
705 | | * https://unicode-org.github.io/icu/userguide/collation/concepts#collator-naming-scheme |
706 | | * This function supports preflighting. |
707 | | * |
708 | | * This is internal, and intended to be used with delegate converters. |
709 | | * |
710 | | * @param locale a locale that will appear as a collators locale in the resulting |
711 | | * short string definition. If NULL, the locale will be harvested |
712 | | * from the collator. |
713 | | * @param buffer space to hold the resulting string |
714 | | * @param capacity capacity of the buffer |
715 | | * @param status for returning errors. All the preflighting errors are featured |
716 | | * @return length of the resulting string |
717 | | * @see ucol_openFromShortString |
718 | | * @see ucol_normalizeShortDefinitionString |
719 | | * @see ucol_getShortDefinitionString |
720 | | * @internal |
721 | | */ |
722 | | virtual int32_t internalGetShortDefinitionString(const char *locale, |
723 | | char *buffer, |
724 | | int32_t capacity, |
725 | | UErrorCode &status) const; |
726 | | |
727 | | /** |
728 | | * Implements ucol_nextSortKeyPart(). |
729 | | * @internal |
730 | | */ |
731 | | virtual int32_t internalNextSortKeyPart( |
732 | | UCharIterator *iter, uint32_t state[2], |
733 | | uint8_t *dest, int32_t count, UErrorCode &errorCode) const; |
734 | | |
735 | | // Do not enclose the default constructor with #ifndef U_HIDE_INTERNAL_API |
736 | | /** |
737 | | * Only for use in ucol_openRules(). |
738 | | * @internal |
739 | | */ |
740 | | RuleBasedCollator(); |
741 | | |
742 | | #ifndef U_HIDE_INTERNAL_API |
743 | | /** |
744 | | * Implements ucol_getLocaleByType(). |
745 | | * Needed because the lifetime of the locale ID string must match that of the collator. |
746 | | * getLocale() returns a copy of a Locale, with minimal lifetime in a C wrapper. |
747 | | * @internal |
748 | | */ |
749 | | const char *internalGetLocaleID(ULocDataLocaleType type, UErrorCode &errorCode) const; |
750 | | |
751 | | /** |
752 | | * Implements ucol_getContractionsAndExpansions(). |
753 | | * Gets this collator's sets of contraction strings and/or |
754 | | * characters and strings that map to multiple collation elements (expansions). |
755 | | * If addPrefixes is true, then contractions that are expressed as |
756 | | * prefix/pre-context rules are included. |
757 | | * @param contractions if not NULL, the set to hold the contractions |
758 | | * @param expansions if not NULL, the set to hold the expansions |
759 | | * @param addPrefixes include prefix contextual mappings |
760 | | * @param errorCode in/out ICU error code |
761 | | * @internal |
762 | | */ |
763 | | void internalGetContractionsAndExpansions( |
764 | | UnicodeSet *contractions, UnicodeSet *expansions, |
765 | | UBool addPrefixes, UErrorCode &errorCode) const; |
766 | | |
767 | | /** |
768 | | * Adds the contractions that start with character c to the set. |
769 | | * Ignores prefixes. Used by AlphabeticIndex. |
770 | | * @internal |
771 | | */ |
772 | | void internalAddContractions(UChar32 c, UnicodeSet &set, UErrorCode &errorCode) const; |
773 | | |
774 | | /** |
775 | | * Implements from-rule constructors, and ucol_openRules(). |
776 | | * @internal |
777 | | */ |
778 | | void internalBuildTailoring( |
779 | | const UnicodeString &rules, |
780 | | int32_t strength, |
781 | | UColAttributeValue decompositionMode, |
782 | | UParseError *outParseError, UnicodeString *outReason, |
783 | | UErrorCode &errorCode); |
784 | | |
785 | | /** @internal */ |
786 | 0 | static inline RuleBasedCollator *rbcFromUCollator(UCollator *uc) { |
787 | 0 | return dynamic_cast<RuleBasedCollator *>(fromUCollator(uc)); |
788 | 0 | } |
789 | | /** @internal */ |
790 | 0 | static inline const RuleBasedCollator *rbcFromUCollator(const UCollator *uc) { |
791 | 0 | return dynamic_cast<const RuleBasedCollator *>(fromUCollator(uc)); |
792 | 0 | } |
793 | | |
794 | | /** |
795 | | * Appends the CEs for the string to the vector. |
796 | | * @internal for tests & tools |
797 | | */ |
798 | | void internalGetCEs(const UnicodeString &str, UVector64 &ces, UErrorCode &errorCode) const; |
799 | | #endif // U_HIDE_INTERNAL_API |
800 | | |
801 | | protected: |
802 | | /** |
803 | | * Used internally by registration to define the requested and valid locales. |
804 | | * @param requestedLocale the requested locale |
805 | | * @param validLocale the valid locale |
806 | | * @param actualLocale the actual locale |
807 | | * @internal |
808 | | */ |
809 | | virtual void setLocales(const Locale& requestedLocale, const Locale& validLocale, const Locale& actualLocale); |
810 | | |
811 | | private: |
812 | | friend class CollationElementIterator; |
813 | | friend class Collator; |
814 | | |
815 | | RuleBasedCollator(const CollationCacheEntry *entry); |
816 | | |
817 | | /** |
818 | | * Enumeration of attributes that are relevant for short definition strings |
819 | | * (e.g., ucol_getShortDefinitionString()). |
820 | | * Effectively extends UColAttribute. |
821 | | */ |
822 | | enum Attributes { |
823 | | ATTR_VARIABLE_TOP = UCOL_ATTRIBUTE_COUNT, |
824 | | ATTR_LIMIT |
825 | | }; |
826 | | |
827 | | void adoptTailoring(CollationTailoring *t, UErrorCode &errorCode); |
828 | | |
829 | | // Both lengths must be <0 or else both must be >=0. |
830 | | UCollationResult doCompare(const char16_t *left, int32_t leftLength, |
831 | | const char16_t *right, int32_t rightLength, |
832 | | UErrorCode &errorCode) const; |
833 | | UCollationResult doCompare(const uint8_t *left, int32_t leftLength, |
834 | | const uint8_t *right, int32_t rightLength, |
835 | | UErrorCode &errorCode) const; |
836 | | |
837 | | void writeSortKey(const char16_t *s, int32_t length, |
838 | | SortKeyByteSink &sink, UErrorCode &errorCode) const; |
839 | | |
840 | | void writeIdenticalLevel(const char16_t *s, const char16_t *limit, |
841 | | SortKeyByteSink &sink, UErrorCode &errorCode) const; |
842 | | |
843 | | const CollationSettings &getDefaultSettings() const; |
844 | | |
845 | 0 | void setAttributeDefault(int32_t attribute) { |
846 | 0 | explicitlySetAttributes &= ~((uint32_t)1 << attribute); |
847 | 0 | } |
848 | 0 | void setAttributeExplicitly(int32_t attribute) { |
849 | 0 | explicitlySetAttributes |= (uint32_t)1 << attribute; |
850 | 0 | } |
851 | 0 | UBool attributeHasBeenSetExplicitly(int32_t attribute) const { |
852 | | // assert(0 <= attribute < ATTR_LIMIT); |
853 | 0 | return (UBool)((explicitlySetAttributes & ((uint32_t)1 << attribute)) != 0); |
854 | 0 | } |
855 | | |
856 | | /** |
857 | | * Tests whether a character is "unsafe" for use as a collation starting point. |
858 | | * |
859 | | * @param c code point or code unit |
860 | | * @return true if c is unsafe |
861 | | * @see CollationElementIterator#setOffset(int) |
862 | | */ |
863 | | UBool isUnsafe(UChar32 c) const; |
864 | | |
865 | | static void U_CALLCONV computeMaxExpansions(const CollationTailoring *t, UErrorCode &errorCode); |
866 | | UBool initMaxExpansions(UErrorCode &errorCode) const; |
867 | | |
868 | | void setFastLatinOptions(CollationSettings &ownedSettings) const; |
869 | | |
870 | | const CollationData *data; |
871 | | const CollationSettings *settings; // reference-counted |
872 | | const CollationTailoring *tailoring; // alias of cacheEntry->tailoring |
873 | | const CollationCacheEntry *cacheEntry; // reference-counted |
874 | | Locale validLocale; |
875 | | uint32_t explicitlySetAttributes; |
876 | | |
877 | | UBool actualLocaleIsSameAsValid; |
878 | | }; |
879 | | |
880 | | U_NAMESPACE_END |
881 | | |
882 | | #endif // !UCONFIG_NO_COLLATION |
883 | | |
884 | | #endif /* U_SHOW_CPLUSPLUS_API */ |
885 | | |
886 | | #endif // TBLCOLL_H |