Manual

 Collation

Function

uni_collate

Compare strings for sorting.

Since v1.0
unistat uni_collate(
const void *s1, unisize s1_len, uniattr s1_attr, const void *s2, unisize s2_len, uniattr s2_attr, uniweighting weighting, unistrength strength, int32_t *result)

Parameters 🔗

s1 in

The first string.

s1_len in

The number of code units in s1 or -1 if null terminated.

s1_attr in

Attributes of s1.

s2 in

The second string.

s2_len in

The number of code units in s2 or -1 if null terminated.

s2_attr in

Attributes of s2.

weighting in

Collation weighting algorithm (see uniweighting for details).

strength in

Levels to be considered in comparison (see unistrength for details).

result out

The integer -1, 0, or 1 depending on if s1 < s2, s1 = s2, or s1 > s2.

Return Value 🔗

UNI_OK

On success.

UNI_BAD_OPERATION

If s1 or s2 are NULL, or if result is NULL.

UNI_BAD_ENCODING

If s1 or s2 is not well-formed (checks are omitted if the corresponding uniattr has UNI_TRUST).

UNI_FEATURE_DISABLED

If Unicorn was built without support for collation.

UNI_NO_MEMORY

If dynamic memory allocation failed.

Discussion 🔗

Compare strings s1 and s2 and write -1, 0, or 1 to result depending on if s1 < s2, s1 = s2, or s1 > s2.

The length and text attributes for s1 are specified by s1_len and s1_attr. The length and text attributes for s2 are specified by s2_len and s2_attr. If s1_len is -1, then the implementation assumes s1 is null terminated. If s2_len is -1, then the implementation assumes s2 is null terminated.

This function is intended for one-off string comparisons. If a string will be compared multiple times, then it’s recommended to construct a sort key once with uni_sortkeymk and compare with uni_sortkeycmp.

Support for collation must be enabled in the JSON configuration file.

{
    "algorithms": {
        "collation": true
    }
}