C Reference ยท string.h
C strcoll() and strxfrm() functions
Reference for C strcoll() and strxfrm(): compare and transform strings according to the current locale's collation rules, with setlocale() examples.
strcoll() compares two strings using the collation rules of the current locale (the LC_COLLATE category), so words sort the way people in that language expect. In the default "C" locale it behaves exactly like strcmp: a plain comparison of byte values.
strxfrm() transforms a string into another string whose strcmp order equals the strcoll order of the originals. If you compare the same string many times, such as in a sort, transform each string once and compare the results with strcmp, which is much cheaper than calling strcoll repeatedly.
#include <string.h> int strcoll(const char *s1, const char *s2); size_t strxfrm(char *restrict dst, const char *restrict src, size_t n);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
The runner has only the "C" locale loaded for sure, so these examples show the portable behavior. In a program running on your own computer, call setlocale(LC_COLLATE, "") first to use the user's locale. A locale such as de_DE.UTF-8 or sv_SE.UTF-8 then changes the order of letters like รค or รฅ. The result depends on which locales are installed.
Syntax
int strcoll(const char *s1, const char *s2); size_t strxfrm(char *restrict dst, const char *restrict src, size_t n);
| Name | Description |
|---|---|
s1, s2 |
The null-terminated strings to compare. |
dst |
Where the transformed string is written. May be NULL only when n is 0. |
src |
The string to transform. |
n |
The size of dst in bytes, including room for the terminator. |
Returns: strcoll returns a negative number, zero or a positive number as s1 collates before, equal to or after s2. strxfrm returns the length of the transformed string, not counting the terminator. If the return value is n or more, the contents of dst are indeterminate.
Errors / undefined behavior: both strings must be valid and terminated; overlapping dst and src is undefined. strcoll has no error return, although a locale can in theory make it fail and set errno.
Usage notes
- Only the sign matters for
strcoll, as withstrcmp. - Select the locale first. The program begins in the
"C"locale.setlocale(LC_COLLATE, "")takes the collation rules from the environment, and it returnsNULLif the request cannot be met. Check that, and fall back to plainstrcmpor report the problem. - Measure, then convert. The classic idiom is
size_t len = strxfrm(NULL, s, 0);, allocatelen + 1, then callstrxfrm(buf, s, len + 1). Transformed strings can be longer than the original. - Sorting. For
qsortwith a few elements, a comparator that callsstrcollis simple. For thousands of strings, transform each once to avoid the repeated cost. - Not a Unicode collation. The result depends on what the C library implements for the locale. For full Unicode collation across platforms (accent and case rules, language tailoring), use a library such as ICU.
- Threads. The locale is a process-wide setting. Changing it while other threads compare strings is a data race.
- Do not store keys. The transformed form is only meaningful for the locale that produced it, so do not save it in files or databases; save the original text.
- Standard version. Both functions have been in ISO C since C89.