ICU 60.2  60.2
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 
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 
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 
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  }
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 
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 
1271 
1272 #endif /* #if !UCONFIG_NO_COLLATION */
1273 
1274 #endif
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
string a < string b
Definition: ucol.h:79
The Collator class performs locale-sensitive string comparison.
Definition: coll.h:165
virtual UClassID getDynamicClassID() const
ICU4C "poor man&#39;s RTTI", returns a UClassID for the actual ICU class.
UCollationResult
UCOL_LESS is returned if source string is compared to be less than target string in the ucol_strcoll(...
Definition: ucol.h:73
const UCollator * toUCollator() const
Definition: coll.h:1178
UNormalizationMode
Constants for normalization modes.
Definition: unorm.h:138
U_EXPORT UBool operator==(const StringPiece &x, const StringPiece &y)
Global operator == for StringPiece.
void * UClassID
UClassID is used to identify classes without using the compiler&#39;s RTTI.
Definition: uobject.h:93
A factory, used with registerFactory, the creates multiple collators and provides display names for t...
Definition: coll.h:1214
C API:misc definitions.
C API for code unit iteration.
Definition: uiter.h:341
Base class for &#39;pure&#39; C++ implementations of uenum api.
Definition: strenum.h:57
string a == string b
Definition: ucol.h:75
static const Collator * fromUCollator(const UCollator *uc)
Definition: coll.h:1170
ECollationStrength
Base letter represents a primary difference.
Definition: coll.h:195
UColReorderCode
Enum containing the codes for reordering segments of the collation table that are not script codes...
Definition: ucol.h:146
UColAttribute
Attributes that collation service understands.
Definition: ucol.h:242
#define U_I18N_API
Set to export library symbols from inside the i18n library, and to import them from outside...
Definition: utypes.h:360
UCollator * toUCollator()
Definition: coll.h:1174
C++ API: StringPiece: Read-only byte string wrapper class.
#define U_NAMESPACE_BEGIN
This is used to begin a declaration of a public ICU C++ API.
Definition: uversion.h:131
Secondary collation strength.
Definition: ucol.h:96
UBool operator!=(const StringPiece &x, const StringPiece &y)
Global operator != for StringPiece.
Definition: stringpiece.h:218
C API: Unicode Normalization.
EComparisonResult
LESS is returned if source string is compared to be less than target string in the compare() method...
Definition: coll.h:217
C API: Collator.
Collation keys are generated by the Collator class.
Definition: sortkey.h:99
Tertiary collation strength.
Definition: ucol.h:98
A mutable set of Unicode characters and multicharacter strings.
Definition: uniset.h:278
C API: Unicode Character Iteration.
C++ API: Common ICU base class UObject.
const void * URegistryKey
Opaque type returned by registerInstance, registerFactory and unregister for service registration...
Definition: umisc.h:57
#define U_NAMESPACE_END
This is used to end a declaration of a public ICU C++ API.
Definition: uversion.h:132
string a > string b
Definition: ucol.h:77
UErrorCode
Error code to replace exception handling, so that the code is compatible with all C++ compilers...
Definition: utypes.h:396
ULocDataLocaleType
Constants for *_getLocale() Allow user to select whether she wants information on requested...
Definition: uloc.h:338
UColBoundMode
enum that is taken by ucol_getBound API See below for explanation do not change the values assigned t...
Definition: ucol.h:1057
C++ API: Locale ID object.
struct UCollator UCollator
structure representing a collator object instance
Definition: ucol.h:58
Basic definitions for ICU, for both C and C++ APIs.
static Collator * fromUCollator(UCollator *uc)
Definition: coll.h:1166
Identical collation strength.
Definition: ucol.h:105
Quaternary collation strength.
Definition: ucol.h:103
UnicodeString is a string class that stores Unicode characters directly and provides similar function...
Definition: unistr.h:286
UColAttributeValue
Enum containing attribute values for controling collation behavior.
Definition: ucol.h:89
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
Primary collation strength.
Definition: ucol.h:94
int8_t UBool
The ICU boolean type.
Definition: umachine.h:236
A Locale object represents a specific geographical, political, or cultural region.
Definition: locid.h:188
C++ API: Unicode Set.