ICU 4.8.1.1  4.8.1.1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
ucol.h
Go to the documentation of this file.
1 /*
2 *******************************************************************************
3 * Copyright (c) 1996-2011, International Business Machines Corporation and others.
4 * All Rights Reserved.
5 *******************************************************************************
6 */
7 
8 #ifndef UCOL_H
9 #define UCOL_H
10 
11 #include "unicode/utypes.h"
12 
13 #if !UCONFIG_NO_COLLATION
14 
15 #include "unicode/unorm.h"
16 #include "unicode/localpointer.h"
17 #include "unicode/parseerr.h"
18 #include "unicode/uloc.h"
19 #include "unicode/uset.h"
20 #include "unicode/uscript.h"
21 
58 struct UCollator;
62 typedef struct UCollator UCollator;
63 
64 
77 typedef enum {
83  UCOL_LESS = -1
85 
86 
93 typedef enum {
96 
105  UCOL_CE_STRENGTH_LIMIT,
110  UCOL_STRENGTH_LIMIT,
111 
115  UCOL_OFF = 16,
119  UCOL_ON = 17,
120 
125 
131 
132  UCOL_ATTRIBUTE_VALUE_COUNT
133 
135 
144  typedef enum {
199 
227 
232 typedef enum {
295  UCOL_ATTRIBUTE_COUNT
296 } UColAttribute;
297 
301 typedef enum {
306 } UColRuleOption ;
307 
326 ucol_open(const char *loc, UErrorCode *status);
327 
354 ucol_openRules( const UChar *rules,
355  int32_t rulesLength,
356  UColAttributeValue normalizationMode,
357  UCollationStrength strength,
358  UParseError *parseError,
359  UErrorCode *status);
360 
396 ucol_openFromShortString( const char *definition,
397  UBool forceDefaults,
398  UParseError *parseError,
399  UErrorCode *status);
400 
414 U_DEPRECATED int32_t U_EXPORT2
415 ucol_getContractions( const UCollator *coll,
416  USet *conts,
417  UErrorCode *status);
418 
430 U_STABLE void U_EXPORT2
432  USet *contractions, USet *expansions,
433  UBool addPrefixes, UErrorCode *status);
434 
445 U_STABLE void U_EXPORT2
446 ucol_close(UCollator *coll);
447 
448 #if U_SHOW_CPLUSPLUS_API
449 
451 
461 U_DEFINE_LOCAL_OPEN_POINTER(LocalUCollatorPointer, UCollator, ucol_close);
462 
464 
465 #endif
466 
483 ucol_strcoll( const UCollator *coll,
484  const UChar *source,
485  int32_t sourceLength,
486  const UChar *target,
487  int32_t targetLength);
488 
504 ucol_greater(const UCollator *coll,
505  const UChar *source, int32_t sourceLength,
506  const UChar *target, int32_t targetLength);
507 
523 ucol_greaterOrEqual(const UCollator *coll,
524  const UChar *source, int32_t sourceLength,
525  const UChar *target, int32_t targetLength);
526 
542 ucol_equal(const UCollator *coll,
543  const UChar *source, int32_t sourceLength,
544  const UChar *target, int32_t targetLength);
545 
559 ucol_strcollIter( const UCollator *coll,
560  UCharIterator *sIter,
561  UCharIterator *tIter,
562  UErrorCode *status);
563 
574 ucol_getStrength(const UCollator *coll);
575 
585 U_STABLE void U_EXPORT2
587  UCollationStrength strength);
588 
603 U_DRAFT int32_t U_EXPORT2
604 ucol_getReorderCodes(const UCollator* coll,
605  int32_t* dest,
606  int32_t destCapacity,
607  UErrorCode *pErrorCode);
641 U_DRAFT void U_EXPORT2
643  const int32_t* reorderCodes,
644  int32_t reorderCodesLength,
645  UErrorCode *pErrorCode);
646 
661 U_DRAFT int32_t U_EXPORT2
662 ucol_getEquivalentReorderCodes(int32_t reorderCode,
663  int32_t* dest,
664  int32_t destCapacity,
665  UErrorCode *pErrorCode);
666 
679 U_STABLE int32_t U_EXPORT2
680 ucol_getDisplayName( const char *objLoc,
681  const char *dispLoc,
682  UChar *result,
683  int32_t resultLength,
684  UErrorCode *status);
685 
695 U_STABLE const char* U_EXPORT2
696 ucol_getAvailable(int32_t localeIndex);
697 
706 U_STABLE int32_t U_EXPORT2
707 ucol_countAvailable(void);
708 
709 #if !UCONFIG_NO_SERVICE
710 
720 #endif
721 
733 
746 ucol_getKeywordValues(const char *keyword, UErrorCode *status);
747 
765 ucol_getKeywordValuesForLocale(const char* key,
766  const char* locale,
767  UBool commonlyUsed,
768  UErrorCode* status);
769 
800 U_STABLE int32_t U_EXPORT2
801 ucol_getFunctionalEquivalent(char* result, int32_t resultCapacity,
802  const char* keyword, const char* locale,
803  UBool* isAvailable, UErrorCode* status);
804 
813 U_STABLE const UChar* U_EXPORT2
814 ucol_getRules( const UCollator *coll,
815  int32_t *length);
816 
837 U_STABLE int32_t U_EXPORT2
839  const char *locale,
840  char *buffer,
841  int32_t capacity,
842  UErrorCode *status);
843 
864 U_STABLE int32_t U_EXPORT2
865 ucol_normalizeShortDefinitionString(const char *source,
866  char *destination,
867  int32_t capacity,
868  UParseError *parseError,
869  UErrorCode *status);
870 
871 
891 U_STABLE int32_t U_EXPORT2
892 ucol_getSortKey(const UCollator *coll,
893  const UChar *source,
894  int32_t sourceLength,
895  uint8_t *result,
896  int32_t resultLength);
897 
898 
919 U_STABLE int32_t U_EXPORT2
920 ucol_nextSortKeyPart(const UCollator *coll,
921  UCharIterator *iter,
922  uint32_t state[2],
923  uint8_t *dest, int32_t count,
924  UErrorCode *status);
925 
933 typedef enum {
940  UCOL_BOUND_VALUE_COUNT
941 } UColBoundMode;
942 
980 U_STABLE int32_t U_EXPORT2
981 ucol_getBound(const uint8_t *source,
982  int32_t sourceLength,
983  UColBoundMode boundType,
984  uint32_t noOfLevels,
985  uint8_t *result,
986  int32_t resultLength,
987  UErrorCode *status);
988 
997 U_STABLE void U_EXPORT2
998 ucol_getVersion(const UCollator* coll, UVersionInfo info);
999 
1007 U_STABLE void U_EXPORT2
1008 ucol_getUCAVersion(const UCollator* coll, UVersionInfo info);
1009 
1032 U_STABLE int32_t U_EXPORT2
1033 ucol_mergeSortkeys(const uint8_t *src1, int32_t src1Length,
1034  const uint8_t *src2, int32_t src2Length,
1035  uint8_t *dest, int32_t destCapacity);
1036 
1048 U_STABLE void U_EXPORT2
1050 
1063 ucol_getAttribute(const UCollator *coll, UColAttribute attr, UErrorCode *status);
1064 
1084 U_STABLE uint32_t U_EXPORT2
1086  const UChar *varTop, int32_t len,
1087  UErrorCode *status);
1088 
1100 U_STABLE uint32_t U_EXPORT2 ucol_getVariableTop(const UCollator *coll, UErrorCode *status);
1101 
1113 U_STABLE void U_EXPORT2
1114 ucol_restoreVariableTop(UCollator *coll, const uint32_t varTop, UErrorCode *status);
1115 
1139 ucol_safeClone(const UCollator *coll,
1140  void *stackBuffer,
1141  int32_t *pBufferSize,
1142  UErrorCode *status);
1143 
1147 #define U_COL_SAFECLONE_BUFFERSIZE 512
1148 
1160 U_STABLE int32_t U_EXPORT2
1161 ucol_getRulesEx(const UCollator *coll, UColRuleOption delta, UChar *buffer, int32_t bufferLen);
1162 
1177 U_DEPRECATED const char * U_EXPORT2
1178 ucol_getLocale(const UCollator *coll, ULocDataLocaleType type, UErrorCode *status);
1179 
1180 
1195 U_STABLE const char * U_EXPORT2
1196 ucol_getLocaleByType(const UCollator *coll, ULocDataLocaleType type, UErrorCode *status);
1197 
1209 ucol_getTailoredSet(const UCollator *coll, UErrorCode *status);
1210 
1223 ucol_getAttributeOrDefault(const UCollator *coll, UColAttribute attr, UErrorCode *status);
1224 
1234 ucol_equals(const UCollator *source, const UCollator *target);
1235 
1247 U_INTERNAL int32_t U_EXPORT2
1248 ucol_getUnsafeSet( const UCollator *coll,
1249  USet *unsafe,
1250  UErrorCode *status);
1251 
1255 U_INTERNAL void U_EXPORT2
1256 ucol_forgetUCA(void);
1257 
1278 U_INTERNAL void U_EXPORT2
1279 ucol_prepareShortStringOpen( const char *definition,
1280  UBool forceDefaults,
1281  UParseError *parseError,
1282  UErrorCode *status);
1283 
1295 U_STABLE int32_t U_EXPORT2
1296 ucol_cloneBinary(const UCollator *coll,
1297  uint8_t *buffer, int32_t capacity,
1298  UErrorCode *status);
1299 
1318 ucol_openBinary(const uint8_t *bin, int32_t length,
1319  const UCollator *base,
1320  UErrorCode *status);
1321 
1322 
1323 #endif /* #if !UCONFIG_NO_COLLATION */
1324 
1325 #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:57
const UChar * ucol_getRules(const UCollator *coll, int32_t *length)
Get the collation rules from a UCollator.
Characters with the currency property.
Definition: ucol.h:187
string a < string b
Definition: ucol.h:83
Turn the feature on - works for UCOL_FRENCH_COLLATION, UCOL_CASE_LEVEL, UCOL_HIRAGANA_QUATERNARY_MODE...
Definition: ucol.h:119
Characters with the symbol property.
Definition: ucol.h:182
Retrieve UCA rules and tailoring.
Definition: ucol.h:305
UBool ucol_equal(const UCollator *coll, const UChar *source, int32_t sourceLength, const UChar *target, int32_t targetLength)
Compare two strings for equality.
A special reordering code that is used to specify all other codes used for reordering except for the ...
Definition: ucol.h:162
UColAttributeValue ucol_getAttribute(const UCollator *coll, UColAttribute attr, UErrorCode *status)
Universal attribute getter.
void ucol_getUCAVersion(const UCollator *coll, UVersionInfo info)
Gets the UCA version information for a Collator.
UCollationResult ucol_strcoll(const UCollator *coll, const UChar *source, int32_t sourceLength, const UChar *target, int32_t targetLength)
Compare two strings.
upper bound that will match all the strings that have the same initial substring as the given string ...
Definition: ucol.h:939
int32_t ucol_getSortKey(const UCollator *coll, const UChar *source, int32_t sourceLength, uint8_t *result, int32_t resultLength)
Get a sort key for a string from a UCollator.
lower bound
Definition: ucol.h:935
Controls the ordering of upper and lower case letters.
Definition: ucol.h:253
int32_t ucol_getReorderCodes(const UCollator *coll, int32_t *dest, int32_t destCapacity, UErrorCode *pErrorCode)
Retrieves the reordering codes for this collator.
UCollationResult
UCOL_LESS is returned if source string is compared to be less than target string in the u_strcoll() m...
Definition: ucol.h:77
Retrieve tailoring only.
Definition: ucol.h:303
int32_t ucol_getEquivalentReorderCodes(int32_t reorderCode, int32_t *dest, int32_t destCapacity, UErrorCode *pErrorCode)
Retrieves the reorder codes that are grouped with the given reorder code.
uint32_t ucol_setVariableTop(UCollator *coll, const UChar *varTop, int32_t len, UErrorCode *status)
Variable top is a two byte primary value which causes all the codepoints with primary values that are...
Valid for UCOL_ALTERNATE_HANDLING.
Definition: ucol.h:124
Controls whether the normalization check and necessary normalizations are performed.
Definition: ucol.h:269
struct UEnumeration UEnumeration
structure representing an enumeration object instance
Definition: uenum.h:39
int32_t ucol_countAvailable(void)
Determine how many locales have collation rules available.
void ucol_getContractionsAndExpansions(const UCollator *coll, USet *contractions, USet *expansions, UBool addPrefixes, UErrorCode *status)
Get a set containing the expansions defined by the collator.
C API for code unit iteration.
Definition: uiter.h:339
USet * ucol_getTailoredSet(const UCollator *coll, UErrorCode *status)
Get an Unicode set that contains all the characters and sequences tailored in this collator...
accepted by most attributes
Definition: ucol.h:95
#define U_INTERNAL
This is used to declare a function as an internal ICU C API.
Definition: umachine.h:145
string a == string b
Definition: ucol.h:79
int32_t ucol_getRulesEx(const UCollator *coll, UColRuleOption delta, UChar *buffer, int32_t bufferLen)
Returns current rules.
UColAttributeValue ucol_getAttributeOrDefault(const UCollator *coll, UColAttribute attr, UErrorCode *status)
Universal attribute getter that returns UCOL_DEFAULT if the value is default.
UColAttributeValue UCollationStrength
Base letter represents a primary difference.
Definition: ucol.h:226
Characters with the digit property.
Definition: ucol.h:192
Default collation strength.
Definition: ucol.h:104
Valid for UCOL_CASE_FIRST - lower case sorts before upper case.
Definition: ucol.h:128
C API: Unicode Script Information.
C API: Unicode Set.
UColReorderCode
Enum containing the codes for reordering segments of the collation table that are not script codes...
Definition: ucol.h:144
void ucol_setReorderCodes(UCollator *coll, const int32_t *reorderCodes, int32_t reorderCodesLength, UErrorCode *pErrorCode)
Sets the reordering codes for this collator.
UColAttribute
Attributes that collation service understands.
Definition: ucol.h:232
Turn the feature off - works for UCOL_FRENCH_COLLATION, UCOL_CASE_LEVEL, UCOL_HIRAGANA_QUATERNARY_MOD...
Definition: ucol.h:115
#define U_DEPRECATED
This is used to declare a function as a deprecated public ICU C API.
Definition: umachine.h:141
uint32_t ucol_getVariableTop(const UCollator *coll, UErrorCode *status)
Gets the variable top value of a Collator.
UEnumeration * ucol_openAvailableLocales(UErrorCode *status)
Create a string enumerator of all locales for which a valid collator may be opened.
A special reordering code that is used to specify no reordering codes.
Definition: ucol.h:155
#define U_NAMESPACE_BEGIN
This is used to begin a declaration of a public ICU C++ API.
Definition: uversion.h:131
UBool ucol_equals(const UCollator *source, const UCollator *target)
Check whether two collators are equal.
upper bound that will match strings of exact size
Definition: ucol.h:937
Attribute for direction of secondary weights - used in French.
Definition: ucol.h:237
The strength attribute.
Definition: ucol.h:282
When turned on, this attribute generates a collation key for the numeric value of substrings of digit...
Definition: ucol.h:294
int32_t ucol_cloneBinary(const UCollator *coll, uint8_t *buffer, int32_t capacity, UErrorCode *status)
Creates a binary image of a collator.
Secondary collation strength.
Definition: ucol.h:100
void ucol_restoreVariableTop(UCollator *coll, const uint32_t varTop, UErrorCode *status)
Sets the variable top to a collation element value supplied.
When turned on, this attribute positions Hiragana before all non-ignorables on quaternary level This ...
Definition: ucol.h:286
Controls whether an extra case level (positioned before the third level) is generated or not...
Definition: ucol.h:261
C++ API: "Smart pointers" for use with and in ICU4C C++ code.
int32_t ucol_mergeSortkeys(const uint8_t *src1, int32_t src1Length, const uint8_t *src2, int32_t src2Length, uint8_t *dest, int32_t destCapacity)
Merge two sort keys.
C API: Unicode Normalization.
int32_t ucol_getContractions(const UCollator *coll, USet *conts, UErrorCode *status)
Get a set containing the contractions defined by the collator.
upper case sorts before lower case
Definition: ucol.h:130
The first entry in the enumeration of reordering groups.
Definition: ucol.h:172
int32_t ucol_nextSortKeyPart(const UCollator *coll, UCharIterator *iter, uint32_t state[2], uint8_t *dest, int32_t count, UErrorCode *status)
Gets the next count bytes of a sort key.
UCollator * ucol_openBinary(const uint8_t *bin, int32_t length, const UCollator *base, UErrorCode *status)
Opens a collator from a collator binary image created using ucol_cloneBinary.
void ucol_prepareShortStringOpen(const char *definition, UBool forceDefaults, UParseError *parseError, UErrorCode *status)
Touches all resources needed for instantiating a collator from a short string definition, thus filling up the cache.
const char * ucol_getAvailable(int32_t localeIndex)
Get a locale for which collation rules are available.
void ucol_close(UCollator *coll)
Close a UCollator.
Tertiary collation strength.
Definition: ucol.h:102
UCollationResult ucol_strcollIter(const UCollator *coll, UCharIterator *sIter, UCharIterator *tIter, UErrorCode *status)
Compare two UTF-8 encoded trings.
int32_t ucol_getDisplayName(const char *objLoc, const char *dispLoc, UChar *result, int32_t resultLength, UErrorCode *status)
Get the display name for a UCollator.
UEnumeration * ucol_getKeywordValuesForLocale(const char *key, const char *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...
#define U_EXPORT2
Definition: platform.h:314
A special reordering code that is used to specify the default reordering codes for a locale...
Definition: ucol.h:150
const char * ucol_getLocale(const UCollator *coll, ULocDataLocaleType type, UErrorCode *status)
gets the locale name of the collator.
void ucol_getVersion(const UCollator *coll, UVersionInfo info)
Gets the version information for a Collator.
uint16_t UChar
Define UChar to be wchar_t if that is 16 bits wide; always assumed to be unsigned.
Definition: umachine.h:325
#define U_NAMESPACE_END
This is used to end a declaration of a public ICU C++ API.
Definition: uversion.h:132
struct USet USet
Definition: ucnv.h:67
UBool ucol_greaterOrEqual(const UCollator *coll, const UChar *source, int32_t sourceLength, const UChar *target, int32_t targetLength)
Determine if one string is greater than or equal to another.
string a > string b
Definition: ucol.h:81
C API: Parse Error Information.
int32_t ucol_normalizeShortDefinitionString(const char *source, char *destination, int32_t capacity, UParseError *parseError, UErrorCode *status)
Verifies and normalizes short definition string.
UCollator * ucol_openRules(const UChar *rules, int32_t rulesLength, UColAttributeValue normalizationMode, UCollationStrength strength, UParseError *parseError, UErrorCode *status)
Produce an UCollator instance according to the rules supplied.
void ucol_forgetUCA(void)
Reset UCA's static pointers.
int32_t ucol_getShortDefinitionString(const UCollator *coll, const char *locale, char *buffer, int32_t capacity, UErrorCode *status)
Get the short definition string for a collator.
UBool ucol_greater(const UCollator *coll, const UChar *source, int32_t sourceLength, const UChar *target, int32_t targetLength)
Determine if one string is greater than another.
void ucol_setAttribute(UCollator *coll, UColAttribute attr, UColAttributeValue value, UErrorCode *status)
Universal attribute setter.
UErrorCode
Error code to replace exception handling, so that the code is compatible with all C++ compilers...
Definition: utypes.h:639
ULocDataLocaleType
Constants for *_getLocale() Allow user to select whether she wants information on requested...
Definition: uloc.h:336
int32_t ucol_getUnsafeSet(const UCollator *coll, USet *unsafe, UErrorCode *status)
Calculates the set of unsafe code points, given a collator.
UEnumeration * ucol_getKeywordValues(const char *keyword, UErrorCode *status)
Given a keyword, create a string enumeration of all values for that keyword that are currently in use...
const char * ucol_getLocaleByType(const UCollator *coll, ULocDataLocaleType type, UErrorCode *status)
gets the locale name of the collator.
int32_t ucol_getFunctionalEquivalent(char *result, int32_t resultCapacity, const char *keyword, const char *locale, UBool *isAvailable, UErrorCode *status)
Return the functionally equivalent locale for the given requested locale, with respect to given keywo...
Characters with the punctuation property.
Definition: ucol.h:177
UColBoundMode
enum that is taken by ucol_getBound API See below for explanation do not change the values assigned t...
Definition: ucol.h:933
void ucol_setStrength(UCollator *coll, UCollationStrength strength)
Set the collation strength used in a UCollator.
struct UCollator UCollator
structure representing a collator object instance
Definition: ucol.h:62
Valid for UCOL_ALTERNATE_HANDLING.
Definition: ucol.h:122
A UParseError struct is used to returned detailed information about parsing errors.
Definition: parseerr.h:56
UCollator * ucol_safeClone(const UCollator *coll, void *stackBuffer, int32_t *pBufferSize, UErrorCode *status)
Thread safe cloning operation.
Basic definitions for ICU, for both C and C++ APIs.
int32_t ucol_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.
Identical collation strength.
Definition: ucol.h:109
UCollator * ucol_openFromShortString(const char *definition, UBool forceDefaults, UParseError *parseError, UErrorCode *status)
Open a collator defined by a short form string.
Quaternary collation strength.
Definition: ucol.h:107
Attribute for handling variable elements.
Definition: ucol.h:246
An alias for UCOL_NORMALIZATION_MODE attribute.
Definition: ucol.h:271
UColAttributeValue
Enum containing attribute values for controling collation behavior.
Definition: ucol.h:93
UEnumeration * ucol_getKeywords(UErrorCode *status)
Create a string enumerator of all possible keywords that are relevant to collation.
#define U_DRAFT
This is used to declare a function as a draft public ICU C API.
Definition: umachine.h:139
UCollator * ucol_open(const char *loc, UErrorCode *status)
Open a UCollator for comparing strings.
Characters with the space property.
Definition: ucol.h:167
UColRuleOption
Options for retrieving the rule string.
Definition: ucol.h:301
UCollationStrength ucol_getStrength(const UCollator *coll)
Get the collation strength used in a UCollator.
Primary collation strength.
Definition: ucol.h:98
#define U_STABLE
This is used to declare a function as a stable public ICU C API.
Definition: umachine.h:137
int8_t UBool
The ICU boolean type.
Definition: umachine.h:228
The limit of the reorder codes.
Definition: ucol.h:197
C API: Locale.