ICU 62.1 62.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
69
70class StringEnumeration;
71
72#if !UCONFIG_NO_SERVICE
76class CollatorFactory;
77#endif
78
82class CollationKey;
83
166public:
167
168 // Collator public enums -----------------------------------------------
169
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.
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
290
325
338 const UnicodeString& target) const;
339
353 const UnicodeString& target,
354 UErrorCode &status) const = 0;
355
369 const UnicodeString& target,
370 int32_t length) const;
371
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
460 UErrorCode &status) const;
461
476 const StringPiece &target,
477 UErrorCode &status) const;
478
499 UErrorCode& status) const = 0;
500
520 virtual CollationKey& getCollationKey(const char16_t*source,
521 int32_t sourceLength,
523 UErrorCode& status) const = 0;
528 virtual int32_t hashCode(void) const = 0;
529
543
553 UBool greater(const UnicodeString& source, const UnicodeString& target)
554 const;
555
566 const UnicodeString& target) const;
567
577 UBool equals(const UnicodeString& source, const UnicodeString& target) const;
578
589 virtual ECollationStrength getStrength(void) const;
590
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,
648
670 int32_t* dest,
671 int32_t destCapacity,
673
684 const Locale& displayLocale,
685 UnicodeString& name);
686
696 UnicodeString& name);
697
709 static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
710
720
731
744
763
791 static Locale U_EXPORT2 getFunctionalEquivalent(const char* keyword, const Locale& locale,
793
794#if !UCONFIG_NO_SERVICE
807
819
834#endif /* UCONFIG_NO_SERVICE */
835
841 virtual void getVersion(UVersionInfo info) const = 0;
842
853 virtual UClassID getDynamicClassID(void) const = 0;
854
864 UErrorCode &status) = 0;
865
875 UErrorCode &status) const = 0;
876
896
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
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,
1066 uint32_t noOfLevels,
1067 uint8_t *result,
1068 int32_t resultLength,
1070
1071
1072protected:
1073
1074 // Collator protected constructors -------------------------------------
1075
1084
1085#ifndef U_HIDE_DEPRECATED_API
1099#endif /* U_HIDE_DEPRECATED_API */
1100
1107
1108public:
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
1151 const char *left, int32_t leftLength,
1152 const char *right, int32_t rightLength,
1153 UErrorCode &errorCode) const;
1154
1159 virtual int32_t
1161 UCharIterator *iter, uint32_t state[2],
1162 uint8_t *dest, int32_t count, UErrorCode &errorCode) const;
1163
1164#ifndef U_HIDE_INTERNAL_API
1167 return reinterpret_cast<Collator *>(uc);
1168 }
1170 static inline const Collator *fromUCollator(const UCollator *uc) {
1171 return reinterpret_cast<const Collator *>(uc);
1172 }
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
1183private:
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,
1195};
1196
1197#if !UCONFIG_NO_SERVICE
1215public:
1216
1222
1230 virtual UBool visible(void) const;
1231
1239 virtual Collator* createCollator(const Locale& loc) = 0;
1240
1252 const Locale& displayLocale,
1254
1264 virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) = 0;
1265};
1266#endif /* UCONFIG_NO_SERVICE */
1267
1268// Collator inline methods -----------------------------------------------
1269
1271
1272#endif /* #if !UCONFIG_NO_COLLATION */
1273
1274#endif
Collation keys are generated by the Collator class.
Definition sortkey.h:99
A factory, used with registerFactory, the creates multiple collators and provides display names for t...
Definition coll.h:1214
virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode &status)=0
Return an array of all the locale names directly supported by this factory.
virtual UBool visible(void) const
Return true if this factory is visible.
virtual UnicodeString & getDisplayName(const Locale &objectLocale, const Locale &displayLocale, UnicodeString &result)
Return the name of the collator for the objectLocale, localized for the displayLocale.
virtual Collator * createCollator(const Locale &loc)=0
Return a collator for the provided locale.
virtual ~CollatorFactory()
Destructor.
The Collator class performs locale-sensitive string comparison.
Definition coll.h:165
static Collator * createInstance(UErrorCode &err)
Creates the Collator object for the current default locale.
virtual UCollationResult internalCompareUTF8(const char *left, int32_t leftLength, const char *right, int32_t rightLength, UErrorCode &errorCode) const
Implements ucol_strcollUTF8().
static URegistryKey registerInstance(Collator *toAdopt, const Locale &locale, UErrorCode &status)
Register a new Collator.
virtual UBool operator==(const Collator &other) const
Returns TRUE if "other" is the same as "this".
UBool equals(const UnicodeString &source, const UnicodeString &target) const
Convenience method for comparing two strings based on the collation rules.
virtual Collator * safeClone(void) const
Same as clone().
UCollator * toUCollator()
Definition coll.h:1174
virtual void getVersion(UVersionInfo info) const =0
Gets the version information for a Collator.
static Locale getFunctionalEquivalent(const char *keyword, const Locale &locale, UBool &isAvailable, UErrorCode &status)
Return the functionally equivalent locale for the given requested locale, with respect to given keywo...
static UnicodeString & getDisplayName(const Locale &objectLocale, UnicodeString &name)
Get name of the object for the desired Locale, in the language of the default locale.
static Collator * fromUCollator(UCollator *uc)
Definition coll.h:1166
Collator()
Default constructor.
virtual EComparisonResult compare(const UnicodeString &source, const UnicodeString &target) const
The comparison function compares the character data stored in two different strings.
virtual void setLocales(const Locale &requestedLocale, const Locale &validLocale, const Locale &actualLocale)
Used internally by registration to define the requested and valid locales.
virtual void setAttribute(UColAttribute attr, UColAttributeValue value, UErrorCode &status)=0
Universal attribute setter.
static UnicodeString & getDisplayName(const Locale &objectLocale, const Locale &displayLocale, UnicodeString &name)
Get name of the object for the desired Locale, in the desired language.
virtual UBool operator!=(const Collator &other) const
Returns true if "other" is not the same as "this".
static StringEnumeration * getAvailableLocales(void)
Return a StringEnumeration over the locales available at the time of the call, including registered l...
UBool greaterOrEqual(const UnicodeString &source, const UnicodeString &target) const
Convenience method for comparing two strings based on the collation rules.
virtual int32_t getSortKey(const UnicodeString &source, uint8_t *result, int32_t resultLength) const =0
Get the sort key as an array of bytes from a UnicodeString.
virtual UCollationResult compareUTF8(const StringPiece &source, const StringPiece &target, UErrorCode &status) const
Compares two UTF-8 strings using the Collator.
UBool greater(const UnicodeString &source, const UnicodeString &target) const
Convenience method for comparing two strings based on the collation rules.
static StringEnumeration * getKeywords(UErrorCode &status)
Create a string enumerator of all possible keywords that are relevant to collation.
virtual uint32_t getVariableTop(UErrorCode &status) const =0
Gets the variable top value of a Collator.
virtual UClassID getDynamicClassID(void) const =0
Returns a unique class ID POLYMORPHICALLY.
virtual void setStrength(ECollationStrength newStrength)
Sets the minimum strength to be used in comparison or transformation.
static int32_t getBound(const uint8_t *source, int32_t sourceLength, UColBoundMode boundType, uint32_t noOfLevels, uint8_t *result, int32_t resultLength, UErrorCode &status)
Produce a bound for a given sortkey and a number of levels.
virtual UCollationResult compare(const char16_t *source, int32_t sourceLength, const char16_t *target, int32_t targetLength, UErrorCode &status) const =0
The comparison function compares the character data stored in two different string arrays.
virtual int32_t getReorderCodes(int32_t *dest, int32_t destCapacity, UErrorCode &status) const
Retrieves the reordering codes for this collator.
virtual uint32_t setVariableTop(const UnicodeString &varTop, UErrorCode &status)=0
Sets the variable top to the primary weight of the specified string.
const UCollator * toUCollator() const
Definition coll.h:1178
ECollationStrength
Base letter represents a primary difference.
Definition coll.h:196
virtual UCollationResult compare(const UnicodeString &source, const UnicodeString &target, UErrorCode &status) const =0
The comparison function compares the character data stored in two different strings.
virtual UCollationResult compare(UCharIterator &sIter, UCharIterator &tIter, UErrorCode &status) const
Compares two strings using the Collator.
virtual CollationKey & getCollationKey(const UnicodeString &source, CollationKey &key, UErrorCode &status) const =0
Transforms the string into a series of characters that can be compared with CollationKey::compareTo.
virtual Collator & setMaxVariable(UColReorderCode group, UErrorCode &errorCode)
Sets the variable top to the top of the specified reordering group.
static URegistryKey registerFactory(CollatorFactory *toAdopt, UErrorCode &status)
Register a new CollatorFactory.
Collator(UCollationStrength collationStrength, UNormalizationMode decompositionMode)
Constructor.
static StringEnumeration * getKeywordValues(const char *keyword, UErrorCode &status)
Given a keyword, create a string enumeration of all values for that keyword that are currently in use...
virtual ~Collator()
Destructor.
virtual int32_t internalNextSortKeyPart(UCharIterator *iter, uint32_t state[2], uint8_t *dest, int32_t count, UErrorCode &errorCode) const
Implements ucol_nextSortKeyPart().
virtual CollationKey & getCollationKey(const char16_t *source, int32_t sourceLength, CollationKey &key, UErrorCode &status) const =0
Transforms the string into a series of characters that can be compared with CollationKey::compareTo.
virtual Locale getLocale(ULocDataLocaleType type, UErrorCode &status) const =0
Gets the locale of the Collator.
virtual UColAttributeValue getAttribute(UColAttribute attr, UErrorCode &status) const =0
Universal attribute getter.
virtual EComparisonResult compare(const char16_t *source, int32_t sourceLength, const char16_t *target, int32_t targetLength) const
The comparison function compares the character data stored in two different string arrays.
static Collator * createInstance(const Locale &loc, UErrorCode &err)
Gets the collation object for the desired locale.
static const Locale * getAvailableLocales(int32_t &count)
Get the set of Locales for which Collations are installed.
virtual UColReorderCode getMaxVariable() const
Returns the maximum reordering group whose characters are affected by UCOL_ALTERNATE_HANDLING.
virtual int32_t hashCode(void) const =0
Generates the hash code for the collation object.
virtual UnicodeSet * getTailoredSet(UErrorCode &status) const
Get a UnicodeSet that contains all the characters and sequences tailored in this collator.
virtual Collator * clone(void) const =0
Makes a copy of this object.
virtual int32_t getSortKey(const char16_t *source, int32_t sourceLength, uint8_t *result, int32_t resultLength) const =0
Get the sort key as an array of bytes from a char16_t buffer.
EComparisonResult
LESS is returned if source string is compared to be less than target string in the compare() method.
Definition coll.h:218
virtual void setReorderCodes(const int32_t *reorderCodes, int32_t reorderCodesLength, UErrorCode &status)
Sets the ordering of scripts for this collator.
virtual ECollationStrength getStrength(void) const
Determines the minimum strength that will be used in comparison or transformation.
virtual void setVariableTop(uint32_t varTop, UErrorCode &status)=0
Sets the variable top to the specified primary weight.
static const Collator * fromUCollator(const UCollator *uc)
Definition coll.h:1170
static StringEnumeration * getKeywordValuesForLocale(const char *keyword, const Locale &locale, UBool commonlyUsed, UErrorCode &status)
Given a key and a locale, returns an array of string values in a preferred order that would make a di...
virtual uint32_t setVariableTop(const char16_t *varTop, int32_t len, UErrorCode &status)=0
Sets the variable top to the primary weight of the specified string.
virtual UCollationResult compare(const UnicodeString &source, const UnicodeString &target, int32_t length, UErrorCode &status) const =0
Does the same thing as compare but limits the comparison to a specified length.
static UBool unregister(URegistryKey key, UErrorCode &status)
Unregister a previously-registered Collator or CollatorFactory using the key returned from the regist...
Collator(const Collator &other)
Copy constructor.
virtual EComparisonResult compare(const UnicodeString &source, const UnicodeString &target, int32_t length) const
Does the same thing as compare but limits the comparison to a specified length.
static int32_t getEquivalentReorderCodes(int32_t reorderCode, int32_t *dest, int32_t destCapacity, UErrorCode &status)
Retrieves the reorder codes that are grouped with the given reorder code.
virtual int32_t internalGetShortDefinitionString(const char *locale, char *buffer, int32_t capacity, UErrorCode &status) const
Get the short definition string for a collator.
"Smart pointer" base class; do not use directly: use LocalPointer etc.
A Locale object represents a specific geographical, political, or cultural region.
Definition locid.h:188
Base class for 'pure' C++ implementations of uenum api.
Definition strenum.h:57
A string-like object that points to a sized piece of memory.
Definition stringpiece.h:54
UObject is the common ICU "boilerplate" class.
Definition uobject.h:223
A mutable set of Unicode characters and multicharacter strings.
Definition uniset.h:278
UnicodeString is a string class that stores Unicode characters directly and provides similar function...
Definition unistr.h:287
C++ API: Locale ID object.
C++ API: StringPiece: Read-only byte string wrapper class.
C API for code unit iteration.
Definition uiter.h:341
C API: Collator.
struct UCollator UCollator
structure representing a collator object instance
Definition ucol.h:58
UColAttribute
Attributes that collation service understands.
Definition ucol.h:242
UCollationResult
UCOL_LESS is returned if source string is compared to be less than target string in the ucol_strcoll(...
Definition ucol.h:73
@ UCOL_LESS
string a < string b
Definition ucol.h:79
@ UCOL_GREATER
string a > string b
Definition ucol.h:77
@ UCOL_EQUAL
string a == string b
Definition ucol.h:75
UColBoundMode
enum that is taken by ucol_getBound API See below for explanation do not change the values assigned...
Definition ucol.h:1057
UColAttributeValue
Enum containing attribute values for controling collation behavior.
Definition ucol.h:89
@ UCOL_TERTIARY
Tertiary collation strength.
Definition ucol.h:98
@ UCOL_IDENTICAL
Identical collation strength.
Definition ucol.h:105
@ UCOL_QUATERNARY
Quaternary collation strength.
Definition ucol.h:103
@ UCOL_PRIMARY
Primary collation strength.
Definition ucol.h:94
@ UCOL_SECONDARY
Secondary collation strength.
Definition ucol.h:96
UColReorderCode
Enum containing the codes for reordering segments of the collation table that are not script codes.
Definition ucol.h:146
C API: Unicode Character Iteration.
ULocDataLocaleType
Constants for *_getLocale() Allow user to select whether she wants information on requested,...
Definition uloc.h:338
int8_t UBool
The ICU boolean type.
Definition umachine.h:236
C API:misc definitions.
const void * URegistryKey
Opaque type returned by registerInstance, registerFactory and unregister for service registration.
Definition umisc.h:57
C++ API: Unicode Set.
C API: Unicode Normalization.
UNormalizationMode
Constants for normalization modes.
Definition unorm.h:138
C++ API: Common ICU base class UObject.
void * UClassID
UClassID is used to identify classes without using the compiler's RTTI.
Definition uobject.h:93
Basic definitions for ICU, for both C and C++ APIs.
UErrorCode
Error code to replace exception handling, so that the code is compatible with all C++ compilers,...
Definition utypes.h:396
#define U_I18N_API
Set to export library symbols from inside the i18n library, and to import them from outside.
Definition utypes.h:360
#define U_NAMESPACE_END
This is used to end a declaration of a public ICU C++ API.
Definition uversion.h:138
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
#define U_NAMESPACE_BEGIN
This is used to begin a declaration of a public ICU C++ API.
Definition uversion.h:137