ICU 63.1 63.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 !UCONFIG_NO_COLLATION
58
59 #include "unicode/uobject.h"
60 #include "unicode/ucol.h"
61 #include "unicode/unorm.h"
62 #include "unicode/locid.h"
63 #include "unicode/uniset.h"
64 #include "unicode/umisc.h"
65 #include "unicode/uiter.h"
66 #include "unicode/stringpiece.h"
67
68 U_NAMESPACE_BEGIN
69
70 class StringEnumeration;
71
72 #if !UCONFIG_NO_SERVICE
73
76 class CollatorFactory;
77 #endif
78
82 class CollationKey;
83
165 class U_I18N_API Collator : public UObject {
166 public:
167
168 // Collator public enums -----------------------------------------------
169
195 enum ECollationStrength
196 {
197 PRIMARY = UCOL_PRIMARY, // 0
198 SECONDARY = UCOL_SECONDARY, // 1
199 TERTIARY = UCOL_TERTIARY, // 2
200 QUATERNARY = UCOL_QUATERNARY, // 3
201 IDENTICAL = UCOL_IDENTICAL // 15
202 };
203
204
205 // Cannot use #ifndef U_HIDE_DEPRECATED_API for the following, it is
206 // used by virtual methods that cannot have that conditional.
217 enum EComparisonResult
218 {
219 LESS = UCOL_LESS, // -1
220 EQUAL = UCOL_EQUAL, // 0
221 GREATER = UCOL_GREATER // 1
222 };
223
224 // Collator public destructor -----------------------------------------
225
230 virtual ~Collator();
231
232 // Collator public methods --------------------------------------------
233
252 virtual UBool operator==(const Collator& other) const;
253
261 virtual UBool operator!=(const Collator& other) const;
262
268 virtual Collator* clone(void) const = 0;
269
289 static Collator* U_EXPORT2 createInstance(UErrorCode& err);
290
324 static Collator* U_EXPORT2 createInstance(const Locale& loc, UErrorCode& err);
325
337 virtual EComparisonResult compare(const UnicodeString& source,
338 const UnicodeString& target) const;
339
352 virtual UCollationResult compare(const UnicodeString& source,
353 const UnicodeString& target,
354 UErrorCode &status) const = 0;
355
368 virtual EComparisonResult compare(const UnicodeString& source,
369 const UnicodeString& target,
370 int32_t length) const;
371
385 virtual UCollationResult compare(const UnicodeString& source,
386 const UnicodeString& target,
387 int32_t length,
388 UErrorCode &status) const = 0;
389
423 virtual EComparisonResult compare(const char16_t* source, int32_t sourceLength,
424 const char16_t* target, int32_t targetLength)
425 const;
426
443 virtual UCollationResult compare(const char16_t* source, int32_t sourceLength,
444 const char16_t* target, int32_t targetLength,
445 UErrorCode &status) const = 0;
446
458 virtual UCollationResult compare(UCharIterator &sIter,
459 UCharIterator &tIter,
460 UErrorCode &status) const;
461
475 virtual UCollationResult compareUTF8(const StringPiece &source,
476 const StringPiece &target,
477 UErrorCode &status) const;
478
497 virtual CollationKey& getCollationKey(const UnicodeString& source,
498 CollationKey& key,
499 UErrorCode& status) const = 0;
500
520 virtual CollationKey& getCollationKey(const char16_t*source,
521 int32_t sourceLength,
522 CollationKey& key,
523 UErrorCode& status) const = 0;
528 virtual int32_t hashCode(void) const = 0;
529
542 virtual Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const = 0;
543
553 UBool greater(const UnicodeString& source, const UnicodeString& target)
554 const;
555
565 UBool greaterOrEqual(const UnicodeString& source,
566 const UnicodeString& target) const;
567
577 UBool equals(const UnicodeString& source, const UnicodeString& target) const;
578
589 virtual ECollationStrength getStrength(void) const;
590
609 virtual void setStrength(ECollationStrength newStrength);
610
626 virtual int32_t getReorderCodes(int32_t *dest,
627 int32_t destCapacity,
628 UErrorCode& status) const;
629
645 virtual void setReorderCodes(const int32_t* reorderCodes,
646 int32_t reorderCodesLength,
647 UErrorCode& status) ;
648
669 static int32_t U_EXPORT2 getEquivalentReorderCodes(int32_t reorderCode,
670 int32_t* dest,
671 int32_t destCapacity,
672 UErrorCode& status);
673
683 static UnicodeString& U_EXPORT2 getDisplayName(const Locale& objectLocale,
684 const Locale& displayLocale,
685 UnicodeString& name);
686
695 static UnicodeString& U_EXPORT2 getDisplayName(const Locale& objectLocale,
696 UnicodeString& name);
697
709 static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
710
719 static StringEnumeration* U_EXPORT2 getAvailableLocales(void);
720
730 static StringEnumeration* U_EXPORT2 getKeywords(UErrorCode& status);
731
743 static StringEnumeration* U_EXPORT2 getKeywordValues(const char *keyword, UErrorCode& status);
744
761 static StringEnumeration* U_EXPORT2 getKeywordValuesForLocale(const char* keyword, const Locale& locale,
762 UBool commonlyUsed, UErrorCode& status);
763
791 static Locale U_EXPORT2 getFunctionalEquivalent(const char* keyword, const Locale& locale,
792 UBool& isAvailable, UErrorCode& status);
793
794 #if !UCONFIG_NO_SERVICE
795
806 static URegistryKey U_EXPORT2 registerInstance(Collator* toAdopt, const Locale& locale, UErrorCode& status);
807
818 static URegistryKey U_EXPORT2 registerFactory(CollatorFactory* toAdopt, UErrorCode& status);
819
833 static UBool U_EXPORT2 unregister(URegistryKey key, UErrorCode& status);
834 #endif /* UCONFIG_NO_SERVICE */
835
841 virtual void getVersion(UVersionInfo info) const = 0;
842
853 virtual UClassID getDynamicClassID(void) const = 0;
854
863 virtual void setAttribute(UColAttribute attr, UColAttributeValue value,
864 UErrorCode &status) = 0;
865
874 virtual UColAttributeValue getAttribute(UColAttribute attr,
875 UErrorCode &status) const = 0;
876
895 virtual Collator &setMaxVariable(UColReorderCode group, UErrorCode &errorCode);
896
905 virtual UColReorderCode getMaxVariable() const;
906
923 virtual uint32_t setVariableTop(const char16_t *varTop, int32_t len, UErrorCode &status) = 0;
924
940 virtual uint32_t setVariableTop(const UnicodeString &varTop, UErrorCode &status) = 0;
941
953 virtual void setVariableTop(uint32_t varTop, UErrorCode &status) = 0;
954
962 virtual uint32_t getVariableTop(UErrorCode &status) const = 0;
963
973 virtual UnicodeSet *getTailoredSet(UErrorCode &status) const;
974
982 virtual Collator* safeClone(void) const;
983
1000 virtual int32_t getSortKey(const UnicodeString& source,
1001 uint8_t* result,
1002 int32_t resultLength) const = 0;
1003
1023 virtual int32_t getSortKey(const char16_t*source, int32_t sourceLength,
1024 uint8_t*result, int32_t resultLength) const = 0;
1025
1063 static int32_t U_EXPORT2 getBound(const uint8_t *source,
1064 int32_t sourceLength,
1065 UColBoundMode boundType,
1066 uint32_t noOfLevels,
1067 uint8_t *result,
1068 int32_t resultLength,
1069 UErrorCode &status);
1070
1071
1072 protected:
1073
1074 // Collator protected constructors -------------------------------------
1075
1083 Collator();
1084
1085 #ifndef U_HIDE_DEPRECATED_API
1086
1097 Collator(UCollationStrength collationStrength,
1098 UNormalizationMode decompositionMode);
1099 #endif /* U_HIDE_DEPRECATED_API */
1100
1106 Collator(const Collator& other);
1107
1108 public:
1116 virtual void setLocales(const Locale& requestedLocale, const Locale& validLocale, const Locale& actualLocale);
1117
1141 virtual int32_t internalGetShortDefinitionString(const char *locale,
1142 char *buffer,
1143 int32_t capacity,
1144 UErrorCode &status) const;
1145
1150 virtual UCollationResult internalCompareUTF8(
1151 const char *left, int32_t leftLength,
1152 const char *right, int32_t rightLength,
1153 UErrorCode &errorCode) const;
1154
1159 virtual int32_t
1160 internalNextSortKeyPart(
1161 UCharIterator *iter, uint32_t state[2],
1162 uint8_t *dest, int32_t count, UErrorCode &errorCode) const;
1163
1164 #ifndef U_HIDE_INTERNAL_API
1165
1166 static inline Collator *fromUCollator(UCollator *uc) {
1167 return reinterpret_cast<Collator *>(uc);
1168 }
1170 static inline const Collator *fromUCollator(const UCollator *uc) {
1171 return reinterpret_cast<const Collator *>(uc);
1172 }
1174 inline UCollator *toUCollator() {
1175 return reinterpret_cast<UCollator *>(this);
1176 }
1178 inline const UCollator *toUCollator() const {
1179 return reinterpret_cast<const UCollator *>(this);
1180 }
1181 #endif // U_HIDE_INTERNAL_API
1182
1183 private:
1187 Collator& operator=(const Collator& other);
1188
1189 friend class CFactory;
1190 friend class SimpleCFactory;
1191 friend class ICUCollatorFactory;
1192 friend class ICUCollatorService;
1193 static Collator* makeInstance(const Locale& desiredLocale,
1194 UErrorCode& status);
1195 };
1196
1197 #if !UCONFIG_NO_SERVICE
1198
1214 class U_I18N_API CollatorFactory : public UObject {
1215 public:
1216
1221 virtual ~CollatorFactory();
1222
1230 virtual UBool visible(void) const;
1231
1239 virtual Collator* createCollator(const Locale& loc) = 0;
1240
1251 virtual UnicodeString& getDisplayName(const Locale& objectLocale,
1252 const Locale& displayLocale,
1253 UnicodeString& result);
1254
1264 virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) = 0;
1265 };
1266 #endif /* UCONFIG_NO_SERVICE */
1267
1268 // Collator inline methods -----------------------------------------------
1269
1270 U_NAMESPACE_END
1271
1272 #endif /* #if !UCONFIG_NO_COLLATION */
1273
1274 #endif
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
UCOL_LESS
string a < string b
Definition: ucol.h:79
icu::Collator
The Collator class performs locale-sensitive string comparison.
Definition: coll.h:165
icu::Collator::toUCollator
const UCollator * toUCollator() const
Definition: coll.h:1178
UCollationResult
UCollationResult
UCOL_LESS is returned if source string is compared to be less than target string in the ucol_strcoll(...
Definition: ucol.h:73
UNormalizationMode
UNormalizationMode
Constants for normalization modes.
Definition: unorm.h:138
icu::operator==
U_EXPORT UBool operator==(const StringPiece &x, const StringPiece &y)
Global operator == for StringPiece.
UClassID
void * UClassID
UClassID is used to identify classes without using the compiler&#39;s RTTI.
Definition: uobject.h:90
icu::CollatorFactory
A factory, used with registerFactory, the creates multiple collators and provides display names for t...
Definition: coll.h:1214
umisc.h
C API:misc definitions.
UCharIterator
C API for code unit iteration.
Definition: uiter.h:341
icu::StringEnumeration
Base class for &#39;pure&#39; C++ implementations of uenum api.
Definition: strenum.h:57
UCOL_EQUAL
string a == string b
Definition: ucol.h:75
icu::Collator::fromUCollator
static const Collator * fromUCollator(const UCollator *uc)
Definition: coll.h:1170
icu::Collator::ECollationStrength
ECollationStrength
Base letter represents a primary difference.
Definition: coll.h:195
UColReorderCode
UColReorderCode
Enum containing the codes for reordering segments of the collation table that are not script codes...
Definition: ucol.h:146
UColAttribute
UColAttribute
Attributes that collation service understands.
Definition: ucol.h:242
U_I18N_API
#define U_I18N_API
Set to export library symbols from inside the i18n library, and to import them from outside...
Definition: utypes.h:301
icu::Collator::toUCollator
UCollator * toUCollator()
Definition: coll.h:1174
stringpiece.h
C++ API: StringPiece: Read-only byte string wrapper class.
U_NAMESPACE_BEGIN
#define U_NAMESPACE_BEGIN
This is used to begin a declaration of a public ICU C++ API.
Definition: uversion.h:137
UCOL_SECONDARY
Secondary collation strength.
Definition: ucol.h:96
icu::operator!=
UBool operator!=(const StringPiece &x, const StringPiece &y)
Global operator != for StringPiece.
Definition: stringpiece.h:218
unorm.h
C API: Unicode Normalization.
icu::UObject::getDynamicClassID
virtual UClassID getDynamicClassID() const
ICU4C "poor man&#39;s RTTI", returns a UClassID for the actual ICU class.
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:217
ucol.h
C API: Collator.
icu::CollationKey
Collation keys are generated by the Collator class.
Definition: sortkey.h:99
UCOL_TERTIARY
Tertiary collation strength.
Definition: ucol.h:98
icu::UnicodeSet
A mutable set of Unicode characters and multicharacter strings.
Definition: uniset.h:278
uiter.h
C API: Unicode Character Iteration.
uobject.h
C++ API: Common ICU base class UObject.
URegistryKey
const void * URegistryKey
Opaque type returned by registerInstance, registerFactory and unregister for service registration...
Definition: umisc.h:57
U_NAMESPACE_END
#define U_NAMESPACE_END
This is used to end a declaration of a public ICU C++ API.
Definition: uversion.h:138
UCOL_GREATER
string a > string b
Definition: ucol.h:77
UErrorCode
UErrorCode
Error code to replace exception handling, so that the code is compatible with all C++ compilers...
Definition: utypes.h:401
ULocDataLocaleType
ULocDataLocaleType
Constants for *_getLocale() Allow user to select whether she wants information on requested...
Definition: uloc.h:338
UColBoundMode
UColBoundMode
enum that is taken by ucol_getBound API See below for explanation do not change the values assigned ...
Definition: ucol.h:1057
locid.h
C++ API: Locale ID object.
UCollator
struct UCollator UCollator
structure representing a collator object instance
Definition: ucol.h:58
utypes.h
Basic definitions for ICU, for both C and C++ APIs.
icu::Collator::fromUCollator
static Collator * fromUCollator(UCollator *uc)
Definition: coll.h:1166
UCOL_IDENTICAL
Identical collation strength.
Definition: ucol.h:105
UCOL_QUATERNARY
Quaternary collation strength.
Definition: ucol.h:103
icu::UnicodeString
UnicodeString is a string class that stores Unicode characters directly and provides similar function...
Definition: unistr.h:289
UColAttributeValue
UColAttributeValue
Enum containing attribute values for controling collation behavior.
Definition: ucol.h:89
icu::StringPiece
A string-like object that points to a sized piece of memory.
Definition: stringpiece.h:54
icu::UObject
UObject is the common ICU "boilerplate" class.
Definition: uobject.h:220
UCOL_PRIMARY
Primary collation strength.
Definition: ucol.h:94
UBool
int8_t UBool
The ICU boolean type.
Definition: umachine.h:225
icu::Locale
A Locale object represents a specific geographical, political, or cultural region.
Definition: locid.h:192
uniset.h
C++ API: Unicode Set.