Function

uni_sortkeymk

Make sort key.

Since v1.0

unistat uni_sortkeymk(

const void *text, unisize text_len, uniattr text_attr, uniweighting weighting, unistrength strength, uint16_t *sortkey, size_t *sortkey_cap)

Parameters 🔗

text	in	Text to build the sort key for.
text_len	in	Number of code units in `text` or `-1` if `text` is null terminated.
text_attr	in	Attributes of `text`.
weighting	in	Collation weighting algorithm (see uniweighting for details).
strength	in	Levels to be considered in comparison (see unistrength for details).
sortkey	out	Collation element weights for `text`.
sortkey_cap	inout	Capacity of `sortkey` on input; number of weights needed for the sort key on output.

Return Value 🔗

UNI_OK	If the scalar was successfully decoded.
UNI_NO_SPACE	If `sortkey` lacks capacity for the collation elements.
UNI_BAD_OPERATION	If `text` or `sortkey_cap` are NULL.
UNI_BAD_ENCODING	If `text` is not well-formed (checks are omitted if `text_attr` has UNI_TRUST).
UNI_NO_MEMORY	If dynamic memory allocation failed.

Discussion 🔗

Build a sort key for text and writes the result to sortkey. The number of code units in text is specified by text_len. If text_len is negative then text is assumed to be null terminated. Pairs of sort keys can be compared with uni_sortkeycmp.

The capacity of sortkey is specified by sortkey_cap. The implementation always writes to sortkey_cap the total number of weights needed for text. If the capacity of sortkey is insufficient, then UNI_NO_SPACE is returned otherwise it returns UNI_OK. If sortkey is NULL, then sortkey_cap must be zero.

If the implementation detects text is malformed, then it returns UNI_BAD_ENCODING.

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

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

Examples 🔗

This example constructs two sort keys and compares them. Sort keys must be generated with the same settings for their order to make sense. In this example, the sort keys are constructed with UNI_SHIFTED weighting and UNI_PRIMARY strength. In a real application you would cache the sort keys for future comparisons. For one-off comparisons, use uni_collate.

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

int main(void)
{
    const char *s1 = "hello", *s2 = "Hi";
    uint16_t sk1[16] = {0}, sk2[16] = {0};
    size_t sk1_len = 16, sk2_len = 16;

    if (uni_sortkeymk(s1, -1, UNI_UTF8, UNI_SHIFTED, UNI_PRIMARY, sk1, &sk1_len) != UNI_OK ||
        uni_sortkeymk(s2, -1, UNI_UTF8, UNI_SHIFTED, UNI_PRIMARY, sk2, &sk2_len) != UNI_OK)
    {
        puts("failed to construct sort keys");
        return 1;
    }

    int result;
    if (uni_sortkeycmp(sk1, sk1_len, sk2, sk2_len, &result) != UNI_OK)
    {
        puts("failed to compare sort keys");
        return 1;
    }

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

Manual