ICU 4.2.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-2009, 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/parseerr.h"
17 #include "unicode/uloc.h"
18 #include "unicode/uset.h"
19 
56 struct UCollator;
60 typedef struct UCollator UCollator;
61 
62 
75 typedef enum {
81  UCOL_LESS = -1
83 
84 
91 typedef enum {
94 
103  UCOL_CE_STRENGTH_LIMIT,
108  UCOL_STRENGTH_LIMIT,
109 
113  UCOL_OFF = 16,
117  UCOL_ON = 17,
118 
123 
129 
130  UCOL_ATTRIBUTE_VALUE_COUNT
131 
133 
161 
166 typedef enum {
225  UCOL_ATTRIBUTE_COUNT
226 } UColAttribute;
227 
231 typedef enum {
236 } UColRuleOption ;
237 
256 ucol_open(const char *loc, UErrorCode *status);
257 
284 ucol_openRules( const UChar *rules,
285  int32_t rulesLength,
286  UColAttributeValue normalizationMode,
287  UCollationStrength strength,
288  UParseError *parseError,
289  UErrorCode *status);
290 
326 ucol_openFromShortString( const char *definition,
327  UBool forceDefaults,
328  UParseError *parseError,
329  UErrorCode *status);
330 
345 ucol_getContractions( const UCollator *coll,
346  USet *conts,
347  UErrorCode *status);
348 
360 U_STABLE void U_EXPORT2
362  USet *contractions, USet *expansions,
363  UBool addPrefixes, UErrorCode *status);
364 
375 U_STABLE void U_EXPORT2
376 ucol_close(UCollator *coll);
377 
394 ucol_strcoll( const UCollator *coll,
395  const UChar *source,
396  int32_t sourceLength,
397  const UChar *target,
398  int32_t targetLength);
399 
415 ucol_greater(const UCollator *coll,
416  const UChar *source, int32_t sourceLength,
417  const UChar *target, int32_t targetLength);
418 
434 ucol_greaterOrEqual(const UCollator *coll,
435  const UChar *source, int32_t sourceLength,
436  const UChar *target, int32_t targetLength);
437 
453 ucol_equal(const UCollator *coll,
454  const UChar *source, int32_t sourceLength,
455  const UChar *target, int32_t targetLength);
456 
470 ucol_strcollIter( const UCollator *coll,
471  UCharIterator *sIter,
472  UCharIterator *tIter,
473  UErrorCode *status);
474 
485 ucol_getStrength(const UCollator *coll);
486 
496 U_STABLE void U_EXPORT2
498  UCollationStrength strength);
499 
513 ucol_getDisplayName( const char *objLoc,
514  const char *dispLoc,
515  UChar *result,
516  int32_t resultLength,
517  UErrorCode *status);
518 
528 U_STABLE const char* U_EXPORT2
529 ucol_getAvailable(int32_t localeIndex);
530 
540 ucol_countAvailable(void);
541 
542 #if !UCONFIG_NO_SERVICE
543 
553 #endif
554 
566 
579 ucol_getKeywordValues(const char *keyword, UErrorCode *status);
580 
598 ucol_getKeywordValuesForLocale(const char* key,
599  const char* locale,
600  UBool commonlyUsed,
601  UErrorCode* status);
602 
634 ucol_getFunctionalEquivalent(char* result, int32_t resultCapacity,
635  const char* keyword, const char* locale,
636  UBool* isAvailable, UErrorCode* status);
637 
646 U_STABLE const UChar* U_EXPORT2
647 ucol_getRules( const UCollator *coll,
648  int32_t *length);
649 
672  const char *locale,
673  char *buffer,
674  int32_t capacity,
675  UErrorCode *status);
676 
698 ucol_normalizeShortDefinitionString(const char *source,
699  char *destination,
700  int32_t capacity,
701  UParseError *parseError,
702  UErrorCode *status);
703 
704 
720 ucol_getSortKey(const UCollator *coll,
721  const UChar *source,
722  int32_t sourceLength,
723  uint8_t *result,
724  int32_t resultLength);
725 
726 
748 ucol_nextSortKeyPart(const UCollator *coll,
749  UCharIterator *iter,
750  uint32_t state[2],
751  uint8_t *dest, int32_t count,
752  UErrorCode *status);
753 
761 typedef enum {
768  UCOL_BOUND_VALUE_COUNT
769 } UColBoundMode;
770 
809 ucol_getBound(const uint8_t *source,
810  int32_t sourceLength,
811  UColBoundMode boundType,
812  uint32_t noOfLevels,
813  uint8_t *result,
814  int32_t resultLength,
815  UErrorCode *status);
816 
825 U_STABLE void U_EXPORT2
826 ucol_getVersion(const UCollator* coll, UVersionInfo info);
827 
835 U_STABLE void U_EXPORT2
836 ucol_getUCAVersion(const UCollator* coll, UVersionInfo info);
837 
861 ucol_mergeSortkeys(const uint8_t *src1, int32_t src1Length,
862  const uint8_t *src2, int32_t src2Length,
863  uint8_t *dest, int32_t destCapacity);
864 
876 U_STABLE void U_EXPORT2
878 
891 ucol_getAttribute(const UCollator *coll, UColAttribute attr, UErrorCode *status);
892 
914  const UChar *varTop, int32_t len,
915  UErrorCode *status);
916 
929 
941 U_STABLE void U_EXPORT2
942 ucol_restoreVariableTop(UCollator *coll, const uint32_t varTop, UErrorCode *status);
943 
967 ucol_safeClone(const UCollator *coll,
968  void *stackBuffer,
969  int32_t *pBufferSize,
970  UErrorCode *status);
971 
975 #define U_COL_SAFECLONE_BUFFERSIZE 512
976 
989 ucol_getRulesEx(const UCollator *coll, UColRuleOption delta, UChar *buffer, int32_t bufferLen);
990 
1005 U_DEPRECATED const char * U_EXPORT2
1006 ucol_getLocale(const UCollator *coll, ULocDataLocaleType type, UErrorCode *status);
1007 
1008 
1023 U_STABLE const char * U_EXPORT2
1024 ucol_getLocaleByType(const UCollator *coll, ULocDataLocaleType type, UErrorCode *status);
1025 
1037 ucol_getTailoredSet(const UCollator *coll, UErrorCode *status);
1038 
1051 ucol_getAttributeOrDefault(const UCollator *coll, UColAttribute attr, UErrorCode *status);
1052 
1062 ucol_equals(const UCollator *source, const UCollator *target);
1063 
1076 ucol_getUnsafeSet( const UCollator *coll,
1077  USet *unsafe,
1078  UErrorCode *status);
1079 
1083 U_INTERNAL void U_EXPORT2
1084 ucol_forgetUCA(void);
1085 
1106 U_INTERNAL void U_EXPORT2
1107 ucol_prepareShortStringOpen( const char *definition,
1108  UBool forceDefaults,
1109  UParseError *parseError,
1110  UErrorCode *status);
1111 
1124 ucol_cloneBinary(const UCollator *coll,
1125  uint8_t *buffer, int32_t capacity,
1126  UErrorCode *status);
1127 
1146 ucol_openBinary(const uint8_t *bin, int32_t length,
1147  const UCollator *base,
1148  UErrorCode *status);
1149 
1150 
1151 #endif /* #if !UCONFIG_NO_COLLATION */
1152 
1153 #endif
1154 
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:124
const UChar * ucol_getRules(const UCollator *coll, int32_t *length)
Get the collation rules from a UCollator.
string a < string b
Definition: ucol.h:81
Turn the feature on - works for UCOL_FRENCH_COLLATION, UCOL_CASE_LEVEL, UCOL_HIRAGANA_QUATERNARY_MODE...
Definition: ucol.h:117
Retrieve UCA rules and tailoring.
Definition: ucol.h:235
UBool ucol_equal(const UCollator *coll, const UChar *source, int32_t sourceLength, const UChar *target, int32_t targetLength)
Compare two strings for equality.
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:767
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:763
Controls the ordering of upper and lower case letters.
Definition: ucol.h:187
UCollationResult
UCOL_LESS is returned if source string is compared to be less than target string in the u_strcoll() m...
Definition: ucol.h:75
Retrieve tailoring only.
Definition: ucol.h:233
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:122
Controls whether the normalization check and necessary normalizations are performed.
Definition: ucol.h:203
struct UEnumeration UEnumeration
structure representing an enumeration object instance
Definition: uenum.h:38
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:93
#define U_INTERNAL
This is used to declare a function as an internal ICU C API.
Definition: umachine.h:125
string a == string b
Definition: ucol.h:77
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:160
Default collation strength.
Definition: ucol.h:102
unsigned char uint8_t
Define 64 bit limits.
Definition: pwin32.h:131
Valid for UCOL_CASE_FIRST - lower case sorts before upper case.
Definition: ucol.h:126
unsigned int uint32_t
Define 64 bit limits.
Definition: pwin32.h:147
C API: Unicode Set.
UColAttribute
Attributes that collation service understands.
Definition: ucol.h:166
Turn the feature off - works for UCOL_FRENCH_COLLATION, UCOL_CASE_LEVEL, UCOL_HIRAGANA_QUATERNARY_MOD...
Definition: ucol.h:113
#define U_DEPRECATED
This is used to declare a function as a deprecated public ICU C API.
Definition: umachine.h:121
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.
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:765
Attribute for direction of secondary weights - used in French.
Definition: ucol.h:171
The strength attribute.
Definition: ucol.h:216
When turned on, this attribute generates a collation key for the numeric value of substrings of digit...
Definition: ucol.h:224
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:98
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:220
Controls whether an extra case level (positioned before the third level) is generated or not...
Definition: ucol.h:195
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:128
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:100
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:338
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:299
struct USet USet
Definition: ucnv.h:66
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:79
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:593
ULocDataLocaleType
Constants for *_getLocale() Allow user to select whether she wants information on requested...
Definition: uloc.h:314
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...
UColBoundMode
enum that is taken by ucol_getBound API See below for explanation do not change the values assigned t...
Definition: ucol.h:761
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:60
Valid for UCOL_ALTERNATE_HANDLING.
Definition: ucol.h:120
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:107
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:105
Attribute for handling variable elements.
Definition: ucol.h:180
An alias for UCOL_NORMALIZATION_MODE attribute.
Definition: ucol.h:205
UColAttributeValue
Enum containing attribute values for controling collation behavior.
Definition: ucol.h:91
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:119
UCollator * ucol_open(const char *loc, UErrorCode *status)
Open a UCollator for comparing strings.
UColRuleOption
Options for retrieving the rule string.
Definition: ucol.h:231
UCollationStrength ucol_getStrength(const UCollator *coll)
Get the collation strength used in a UCollator.
Primary collation strength.
Definition: ucol.h:96
signed int int32_t
Define 64 bit limits.
Definition: pwin32.h:143
#define U_STABLE
This is used to declare a function as a stable public ICU C API.
Definition: umachine.h:117
int8_t UBool
The ICU boolean type.
Definition: umachine.h:208
C API: Locale.