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 🔗

This function compares s1 and s2 for sorting and writes -1, 0, or 1 to result depending on if s1 < s2, s1 = s2, or s1 > s2.

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 perform comparisons with uni_sortkeycmp.

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

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

Examples 🔗

This example collates two strings. The function conceptually constructs a sort key for the input strings and then compares them. Constructing a sort key is expensive. If a string will be collated multiple times, then it is recommended to construct a sort key once and cache it for future calculations. See uni_sortkeymk for details.

#include <unicorn.h>
#include <stdio.h>

int main(void)
{
    const char *s1 = u8"Hello World";
    const char *s2 = u8"こんにちは世界";
    int result;

    if (uni_collate(s1, -1, UNI_UTF8,
                    s2, -1, UNI_UTF8,
                    UNI_NON_IGNORABLE, UNI_PRIMARY, &result) != UNI_OK)
    {
        puts("failed to collate strings");
        return 1;
    }

    printf("%d", result);
    return 0;
}

Manual