ICU 71.1 71.1

coll.h
Go to the documentation of this file.
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
6 * Corporation and others. All Rights Reserved.
7 ******************************************************************************
8 */
9
52 #ifndef COLL_H
53 #define COLL_H
54
55 #include "unicode/utypes.h"
56
57 #if U_SHOW_CPLUSPLUS_API
58
59 #if !UCONFIG_NO_COLLATION
60
61 #include "unicode/uobject.h"
62 #include "unicode/ucol.h"
63 #include "unicode/unorm.h"
64 #include "unicode/locid.h"
65 #include "unicode/uniset.h"
66 #include "unicode/umisc.h"
67 #include "unicode/uiter.h"
68 #include "unicode/stringpiece.h"
69
70 U_NAMESPACE_BEGIN
71
72 class StringEnumeration;
73
74 #if !UCONFIG_NO_SERVICE
75
78 class CollatorFactory;
79 #endif
80
84 class CollationKey;
85
167 class U_I18N_API Collator : public UObject {
168 public:
169
170 // Collator public enums -----------------------------------------------
171
197 enum ECollationStrength
198 {
199 PRIMARY = UCOL_PRIMARY, // 0
200 SECONDARY = UCOL_SECONDARY, // 1
201 TERTIARY = UCOL_TERTIARY, // 2
202 QUATERNARY = UCOL_QUATERNARY, // 3
203 IDENTICAL = UCOL_IDENTICAL // 15
204 };
205
206
207 // Cannot use #ifndef U_HIDE_DEPRECATED_API for the following, it is
208 // used by virtual methods that cannot have that conditional.
209 #ifndef U_FORCE_HIDE_DEPRECATED_API
210
220 enum EComparisonResult
221 {
222 LESS = UCOL_LESS, // -1
223 EQUAL = UCOL_EQUAL, // 0
224 GREATER = UCOL_GREATER // 1
225 };
226 #endif // U_FORCE_HIDE_DEPRECATED_API
227
228 // Collator public destructor -----------------------------------------
229
234 virtual ~Collator();
235
236 // Collator public methods --------------------------------------------
237
256 virtual bool operator==(const Collator& other) const;
257
265 virtual bool operator!=(const Collator& other) const;
266
272 virtual Collator* clone() const = 0;
273
293 static Collator* U_EXPORT2 createInstance(UErrorCode& err);
294
328 static Collator* U_EXPORT2 createInstance(const Locale& loc, UErrorCode& err);
329
330 #ifndef U_FORCE_HIDE_DEPRECATED_API
331
342 virtual EComparisonResult compare(const UnicodeString& source,
343 const UnicodeString& target) const;
344 #endif // U_FORCE_HIDE_DEPRECATED_API
345
358 virtual UCollationResult compare(const UnicodeString& source,
359 const UnicodeString& target,
360 UErrorCode &status) const = 0;
361
362 #ifndef U_FORCE_HIDE_DEPRECATED_API
363
375 virtual EComparisonResult compare(const UnicodeString& source,
376 const UnicodeString& target,
377 int32_t length) const;
378 #endif // U_FORCE_HIDE_DEPRECATED_API
379
393 virtual UCollationResult compare(const UnicodeString& source,
394 const UnicodeString& target,
395 int32_t length,
396 UErrorCode &status) const = 0;
397
398 #ifndef U_FORCE_HIDE_DEPRECATED_API
399
432 virtual EComparisonResult compare(const char16_t* source, int32_t sourceLength,
433 const char16_t* target, int32_t targetLength)
434 const;
435 #endif // U_FORCE_HIDE_DEPRECATED_API
436
453 virtual UCollationResult compare(const char16_t* source, int32_t sourceLength,
454 const char16_t* target, int32_t targetLength,
455 UErrorCode &status) const = 0;
456
468 virtual UCollationResult compare(UCharIterator &sIter,
469 UCharIterator &tIter,
470 UErrorCode &status) const;
471
485 virtual UCollationResult compareUTF8(const StringPiece &source,
486 const StringPiece &target,
487 UErrorCode &status) const;
488
507 virtual CollationKey& getCollationKey(const UnicodeString& source,
508 CollationKey& key,
509 UErrorCode& status) const = 0;
510
530 virtual CollationKey& getCollationKey(const char16_t*source,
531 int32_t sourceLength,
532 CollationKey& key,
533 UErrorCode& status) const = 0;
538 virtual int32_t hashCode(void) const = 0;
539
540 #ifndef U_FORCE_HIDE_DEPRECATED_API
541
553 virtual Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const = 0;
554 #endif // U_FORCE_HIDE_DEPRECATED_API
555
565 UBool greater(const UnicodeString& source, const UnicodeString& target)
566 const;
567
577 UBool greaterOrEqual(const UnicodeString& source,
578 const UnicodeString& target) const;
579
589 UBool equals(const UnicodeString& source, const UnicodeString& target) const;
590
591 #ifndef U_FORCE_HIDE_DEPRECATED_API
592
602 virtual ECollationStrength getStrength(void) const;
603
622 virtual void setStrength(ECollationStrength newStrength);
623 #endif // U_FORCE_HIDE_DEPRECATED_API
624
640 virtual int32_t getReorderCodes(int32_t *dest,
641 int32_t destCapacity,
642 UErrorCode& status) const;
643
659 virtual void setReorderCodes(const int32_t* reorderCodes,
660 int32_t reorderCodesLength,
661 UErrorCode& status) ;
662
683 static int32_t U_EXPORT2 getEquivalentReorderCodes(int32_t reorderCode,
684 int32_t* dest,
685 int32_t destCapacity,
686 UErrorCode& status);
687
697 static UnicodeString& U_EXPORT2 getDisplayName(const Locale& objectLocale,
698 const Locale& displayLocale,
699 UnicodeString& name);
700
709 static UnicodeString& U_EXPORT2 getDisplayName(const Locale& objectLocale,
710 UnicodeString& name);
711
723 static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
724
733 static StringEnumeration* U_EXPORT2 getAvailableLocales(void);
734
744 static StringEnumeration* U_EXPORT2 getKeywords(UErrorCode& status);
745
757 static StringEnumeration* U_EXPORT2 getKeywordValues(const char *keyword, UErrorCode& status);
758
775 static StringEnumeration* U_EXPORT2 getKeywordValuesForLocale(const char* keyword, const Locale& locale,
776 UBool commonlyUsed, UErrorCode& status);
777
805 static Locale U_EXPORT2 getFunctionalEquivalent(const char* keyword, const Locale& locale,
806 UBool& isAvailable, UErrorCode& status);
807
808 #if !UCONFIG_NO_SERVICE
809
820 static URegistryKey U_EXPORT2 registerInstance(Collator* toAdopt, const Locale& locale, UErrorCode& status);
821
832 static URegistryKey U_EXPORT2 registerFactory(CollatorFactory* toAdopt, UErrorCode& status);
833
847 static UBool U_EXPORT2 unregister(URegistryKey key, UErrorCode& status);
848 #endif /* UCONFIG_NO_SERVICE */
849
855 virtual void getVersion(UVersionInfo info) const = 0;
856
867 virtual UClassID getDynamicClassID(void) const override = 0;
868
877 virtual void setAttribute(UColAttribute attr, UColAttributeValue value,
878 UErrorCode &status) = 0;
879
888 virtual UColAttributeValue getAttribute(UColAttribute attr,
889 UErrorCode &status) const = 0;
890
909 virtual Collator &setMaxVariable(UColReorderCode group, UErrorCode &errorCode);
910
919 virtual UColReorderCode getMaxVariable() const;
920
921 #ifndef U_FORCE_HIDE_DEPRECATED_API
922
938 virtual uint32_t setVariableTop(const char16_t *varTop, int32_t len, UErrorCode &status) = 0;
939
955 virtual uint32_t setVariableTop(const UnicodeString &varTop, UErrorCode &status) = 0;
956
968 virtual void setVariableTop(uint32_t varTop, UErrorCode &status) = 0;
969 #endif // U_FORCE_HIDE_DEPRECATED_API
970
978 virtual uint32_t getVariableTop(UErrorCode &status) const = 0;
979
989 virtual UnicodeSet *getTailoredSet(UErrorCode &status) const;
990
991 #ifndef U_FORCE_HIDE_DEPRECATED_API
992
999 virtual Collator* safeClone() const;
1000 #endif // U_FORCE_HIDE_DEPRECATED_API
1001
1018 virtual int32_t getSortKey(const UnicodeString& source,
1019 uint8_t* result,
1020 int32_t resultLength) const = 0;
1021
1041 virtual int32_t getSortKey(const char16_t*source, int32_t sourceLength,
1042 uint8_t*result, int32_t resultLength) const = 0;
1043
1081 static int32_t U_EXPORT2 getBound(const uint8_t *source,
1082 int32_t sourceLength,
1083 UColBoundMode boundType,
1084 uint32_t noOfLevels,
1085 uint8_t *result,
1086 int32_t resultLength,
1087 UErrorCode &status);
1088
1089
1090 protected:
1091
1092 // Collator protected constructors -------------------------------------
1093
1101 Collator();
1102
1103 #ifndef U_HIDE_DEPRECATED_API
1104
1115 Collator(UCollationStrength collationStrength,
1116 UNormalizationMode decompositionMode);
1117 #endif /* U_HIDE_DEPRECATED_API */
1118
1124 Collator(const Collator& other);
1125
1126 public:
1134 virtual void setLocales(const Locale& requestedLocale, const Locale& validLocale, const Locale& actualLocale);
1135
1159 virtual int32_t internalGetShortDefinitionString(const char *locale,
1160 char *buffer,
1161 int32_t capacity,
1162 UErrorCode &status) const;
1163
1168 virtual UCollationResult internalCompareUTF8(
1169 const char *left, int32_t leftLength,
1170 const char *right, int32_t rightLength,
1171 UErrorCode &errorCode) const;
1172
1177 virtual int32_t
1178 internalNextSortKeyPart(
1179 UCharIterator *iter, uint32_t state[2],
1180 uint8_t *dest, int32_t count, UErrorCode &errorCode) const;
1181
1182 #ifndef U_HIDE_INTERNAL_API
1183
1184 static inline Collator *fromUCollator(UCollator *uc) {
1185 return reinterpret_cast<Collator *>(uc);
1186 }
1188 static inline const Collator *fromUCollator(const UCollator *uc) {
1189 return reinterpret_cast<const Collator *>(uc);
1190 }
1192 inline UCollator *toUCollator() {
1193 return reinterpret_cast<UCollator *>(this);
1194 }
1196 inline const UCollator *toUCollator() const {
1197 return reinterpret_cast<const UCollator *>(this);
1198 }
1199 #endif // U_HIDE_INTERNAL_API
1200
1201 private:
1205 Collator& operator=(const Collator& other);
1206
1207 friend class CFactory;
1208 friend class SimpleCFactory;
1209 friend class ICUCollatorFactory;
1210 friend class ICUCollatorService;
1211 static Collator* makeInstance(const Locale& desiredLocale,
1212 UErrorCode& status);
1213 };
1214
1215 #if !UCONFIG_NO_SERVICE
1216
1232 class U_I18N_API CollatorFactory : public UObject {
1233 public:
1234
1239 virtual ~CollatorFactory();
1240
1248 virtual UBool visible(void) const;
1249
1257 virtual Collator* createCollator(const Locale& loc) = 0;
1258
1269 virtual UnicodeString& getDisplayName(const Locale& objectLocale,
1270 const Locale& displayLocale,
1271 UnicodeString& result);
1272
1282 virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) = 0;
1283 };
1284 #endif /* UCONFIG_NO_SERVICE */
1285
1286 // Collator inline methods -----------------------------------------------
1287
1288 U_NAMESPACE_END
1289
1290 #endif /* #if !UCONFIG_NO_COLLATION */
1291
1292 #endif /* U_SHOW_CPLUSPLUS_API */
1293
1294 #endif
UCOL_IDENTICAL
@ UCOL_IDENTICAL
Identical collation strength.
Definition: ucol.h:108
UCOL_QUATERNARY
@ UCOL_QUATERNARY
Quaternary collation strength.
Definition: ucol.h:106
UCOL_EQUAL
@ UCOL_EQUAL
string a == string b
Definition: ucol.h:78
icu::CollationKey
Collation keys are generated by the Collator class.
Definition: sortkey.h:101
UColAttribute
UColAttribute
Attributes that collation service understands.
Definition: ucol.h:245
utypes.h
Basic definitions for ICU, for both C and C++ APIs.
icu::Collator::fromUCollator
static const Collator * fromUCollator(const UCollator *uc)
Definition: coll.h:1188
icu::UnicodeSet
A mutable set of Unicode characters and multicharacter strings.
Definition: uniset.h:285
icu::Collator::ECollationStrength
ECollationStrength
Base letter represents a primary difference.
Definition: coll.h:197
U_I18N_API
#define U_I18N_API
Definition: utypes.h:301
UBool
int8_t UBool
The ICU boolean type, a signed-byte integer.
Definition: umachine.h:269
ULocDataLocaleType
ULocDataLocaleType
Constants for *_getLocale() Allow user to select whether she wants information on requested,...
Definition: uloc.h:338
UCOL_LESS
@ UCOL_LESS
string a < string b
Definition: ucol.h:82
icu::operator==
U_EXPORT UBool operator==(const StringPiece &x, const StringPiece &y)
Global operator == for StringPiece.
UCOL_PRIMARY
@ UCOL_PRIMARY
Primary collation strength.
Definition: ucol.h:97
icu::Collator
The Collator class performs locale-sensitive string comparison.
Definition: coll.h:167
UColAttributeValue
UColAttributeValue
Enum containing attribute values for controlling collation behavior.
Definition: ucol.h:92
UCollationResult
UCollationResult
UCOL_LESS is returned if source string is compared to be less than target string in the ucol_strcoll(...
Definition: ucol.h:76
umisc.h
C API:misc definitions.
UCOL_SECONDARY
@ UCOL_SECONDARY
Secondary collation strength.
Definition: ucol.h:99
stringpiece.h
C++ API: StringPiece: Read-only byte string wrapper class.
icu::UnicodeString
UnicodeString is a string class that stores Unicode characters directly and provides similar function...
Definition: unistr.h:295
icu::Collator::toUCollator
UCollator * toUCollator()
Definition: coll.h:1192
icu::UObject
UObject is the common ICU "boilerplate" class.
Definition: uobject.h:223
UClassID
void * UClassID
UClassID is used to identify classes without using the compiler's RTTI.
Definition: uobject.h:96
UErrorCode
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:415
icu::StringEnumeration
Base class for 'pure' C++ implementations of uenum api.
Definition: strenum.h:61
icu::UObject::getDynamicClassID
virtual UClassID getDynamicClassID() const
ICU4C "poor man's RTTI", returns a UClassID for the actual ICU class.
UColBoundMode
UColBoundMode
enum that is taken by ucol_getBound API See below for explanation do not change the values assigned...
Definition: ucol.h:1061
UNormalizationMode
UNormalizationMode
Constants for normalization modes.
Definition: unorm.h:140
icu::Collator::toUCollator
const UCollator * toUCollator() const
Definition: coll.h:1196
UCollator
struct UCollator UCollator
structure representing a collator object instance
Definition: ucol.h:61
unorm.h
C API: Unicode Normalization.
icu::operator!=
bool operator!=(const StringPiece &x, const StringPiece &y)
Global operator != for StringPiece.
Definition: stringpiece.h:335
UCharIterator
C API for code unit iteration.
Definition: uiter.h:341
UCOL_TERTIARY
@ UCOL_TERTIARY
Tertiary collation strength.
Definition: ucol.h:101
uiter.h
C API: Unicode Character Iteration.
icu::Collator::fromUCollator
static Collator * fromUCollator(UCollator *uc)
Definition: coll.h:1184
UVersionInfo
uint8_t UVersionInfo[U_MAX_VERSION_LENGTH]
The binary form of a version on ICU APIs is an array of 4 uint8_t.
Definition: uversion.h:59
locid.h
C++ API: Locale ID object.
uobject.h
C++ API: Common ICU base class UObject.
uniset.h
C++ API: Unicode Set.
icu::StringPiece
A string-like object that points to a sized piece of memory.
Definition: stringpiece.h:60
icu::CollatorFactory
A factory, used with registerFactory, the creates multiple collators and provides display names for t...
Definition: coll.h:1232
icu::Collator::EComparisonResult
EComparisonResult
LESS is returned if source string is compared to be less than target string in the compare() method.
Definition: coll.h:220
icu::Locale
A Locale object represents a specific geographical, political, or cultural region.
Definition: locid.h:195
ucol.h
C API: Collator.
UCOL_GREATER
@ UCOL_GREATER
string a > string b
Definition: ucol.h:80
UColReorderCode
UColReorderCode
Enum containing the codes for reordering segments of the collation table that are not script codes.
Definition: ucol.h:149
URegistryKey
const typedef void * URegistryKey
Opaque type returned by registerInstance, registerFactory and unregister for service registration.
Definition: umisc.h:57