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
76U_NAMESPACE_BEGIN
77
78struct CollationCacheEntry;
79struct CollationData;
80struct CollationSettings;
81struct CollationTailoring;
82/**
83* @stable ICU 2.0
84*/
85class StringSearch;
86/**
87* @stable ICU 2.0
88*/
89class CollationElementIterator;
90class CollationKey;
91class SortKeyByteSink;
92class UnicodeSet;
93class UnicodeString;
94class 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="http://userguide.icu-project.org/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="http://userguide.icu-project.org/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 */
115class U_I18N_API RuleBasedCollator : public Collator {
116public:
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 UBool 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 http://userguide.icu-project.org/collation/customization#TOC-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 * http://userguide.icu-project.org/collation/concepts#TOC-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 static inline RuleBasedCollator *rbcFromUCollator(UCollator *uc) {
787 return dynamic_cast<RuleBasedCollator *>(fromUCollator(uc));
788 }
789 /** @internal */
790 static inline const RuleBasedCollator *rbcFromUCollator(const UCollator *uc) {
791 return dynamic_cast<const RuleBasedCollator *>(fromUCollator(uc));
792 }
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
801protected:
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
811private:
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 void setAttributeDefault(int32_t attribute) {
846 explicitlySetAttributes &= ~((uint32_t)1 << attribute);
847 }
848 void setAttributeExplicitly(int32_t attribute) {
849 explicitlySetAttributes |= (uint32_t)1 << attribute;
850 }
851 UBool attributeHasBeenSetExplicitly(int32_t attribute) const {
852 // assert(0 <= attribute < ATTR_LIMIT);
853 return (UBool)((explicitlySetAttributes & ((uint32_t)1 << attribute)) != 0);
854 }
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
880U_NAMESPACE_END
881
882#endif // !UCONFIG_NO_COLLATION
883
884#endif /* U_SHOW_CPLUSPLUS_API */
885
886#endif // TBLCOLL_H
887