Compares two strings using a specified sort order.
CS_RETCODE cs_strcmp(context, locale, type, str1,
len1, str2, len2, result)
CS_CONTEXT *context;
CS_LOCALE *locale;
CS_INT type;
CS_CHAR *str1;
CS_INT len1;
CS_CHAR *str2;
CS_INTl len2;
CS_INT *result;
A pointer to a CS_CONTEXT structure.
A pointer to a CS_LOCALE structure. A CS_LOCALE structure contains locale information, including the collating sequence that cs_strcmp uses to define a sort order.
An application can call cs_locale with type as CS_LC_COLLATE or CS_SYB_SORTORDER to change the collating sequence in a CS_LOCALE structure.
locale can be NULL. If locale is NULL, cs_strcmp uses whatever localization information is defined in the context CS_CONTEXT structure. Localization information is always defined at the context level, because a CS_CONTEXT picks up default localization information when it is allocated.
The type of comparison to perform.
If type is CS_COMPARE, cs_strcmp performs a lexicographic comparison.
If type is CS_SORT, the values are compared as they would appear in a sorted list. It is possible for strings that are lexicographically equal to belong in different places in a sorted list.
A pointer to the first string for the comparison.
The length, in bytes, of *str1. If *str1 is null-terminated, pass len1 as CS_NULLTERM.
A pointer to the second string for the comparison.
The length, in bytes, of *str2. If *str2 is null-terminated, pass len2 as CS_NULLTERM.
A pointer to the result of the comparison. The following table lists the possible values for *result:
Value of *result |
Indicates |
|---|---|
<0 |
str1 is lexicographically less than str2, or str1 appears before str2 in a sorted list. |
0 |
str1 is lexicographically equal to str1, or str1 is identical to str2. |
>0 |
str1 is lexicographically greater than str2, or str1 appears after str2 in a sorted list. |
cs_strcmp returns:
Returns |
Indicates |
|---|---|
CS_SUCCEED |
The routine completed successfully. |
CS_FAIL |
The routine failed. |
cs_strcmp sets *result to indicate the result of the comparison.
Some languages contain strings that are lexicographically equal, according to a specific sort order, but contain different characters. Although the strings are lexicographically equal, there is a standard order used when placing them into a sorted list.
An application can use cs_strcmp to compare strings either lexicographically or how they appear in a sorted list. For example, given a sort order that specifies that uppercase characters appear before lowercase characters in a sorted list:
The strings “ABC” and “abc” are lexicographically equal.
A call to cs_strcmp that compares “ABC” (as str1) and “abc” as (str2) with type as CS_COMPARE returns with result set to 0.
“ABC” appears before “abc” in a sorted list.
A call to cs_strcmp that compares “ABC” (as str1) and “abc” as (str2) with type as CS_SORT returns with result set to a value less than 0.
cs_strcmp determines which sort order to use by examining *locale, (or *context, if locale is NULL).
To change the sort order in a CS_LOCALE structure, an application calls cs_locale with type as CS_LC_COLLATE or CS_SYB_SORTORDER.
To change the sort order in a CS_CONTEXT structure, an application must first set up a CS_LOCALE structure with the desired sort order and then call cs_config to set the CS_LOC_PROP property for the context.
