# wcscoll

> C++ Atlas: `cppatlas.com/w/c/string/wide/wcscoll` | Source: https://en.cppreference.com/w/c/string/wide/wcscoll | Domain: Strings | Standards: C95

Compares two null-terminated wide strings according to the collation order defined by the LC_COLLATE category of the currently installed locale.

## Official Specification Summary (cppreference)

```cpp
// Defined in header <wchar.h>
int wcscoll( const wchar_t *lhs, const wchar_t *rhs ); // (since C95)
```

Compares two null-terminated wide strings according to the collation order defined by the `LC_COLLATE` category of the currently installed locale.

### Parameters

- `lhs, rhs` - pointers to the null-terminated wide strings to compare

### Return value

Negative value if `lhs` is *less than* (precedes) `rhs`.

`​0​` if `lhs` is *equal to* `rhs`.

Positive value if `lhs` is *greater than* (follows) `rhs`.

### Notes

Collation order is the dictionary order: the position of the letter in the national alphabet (its *equivalence class*) has higher priority than its case or variant. Within an equivalence class, lowercase characters collate before their uppercase equivalents and locale-specific order may apply to the characters with diacritics. In some locales, groups of characters compare as single *collation units*. For example, `"ch"` in Czech follows `"h"` and precedes `"i"`, and `"dzs"` in Hungarian follows `"dz"` and precedes `"g"`.

### Example

```c
#include <stdio.h>
#include <wchar.h>
#include <locale.h>

void try_compare(const wchar_t* p1, const wchar_t* p2)
{
    if(wcscoll(p1, p2) < 0)
        printf("%ls before %ls\n", p1, p2);
    else
        printf("%ls before %ls\n", p2, p1);
}

int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    printf("In the American locale: ");
    try_compare(L"hrnec", L"chrt");

    setlocale(LC_COLLATE, "cs_CZ.utf8");
    printf("In the Czech locale: ");
    try_compare(L"hrnec", L"chrt");

    setlocale(LC_COLLATE, "en_US.utf8");
    printf("In the American locale: ");
    try_compare(L"år", L"ängel");

    setlocale(LC_COLLATE, "sv_SE.utf8");
    printf("In the Swedish locale: ");
    try_compare(L"år", L"ängel");
}
```

Possible output:

```text
In the American locale: chrt before hrnec
In the Czech locale: hrnec before chrt
In the American locale: ängel before år
In the Swedish locale: år before ängel
```

### References

- C11 standard (ISO/IEC 9899:2011):

  - 7.29.4.4.2 The wcscoll function (p: 433-434)

- C99 standard (ISO/IEC 9899:1999):

  - 7.24.4.4.2 The wcscoll function (p: 379-380)

### See also

- [`strcoll`](https://en.cppreference.com/w/c/string/byte/strcoll): compares two strings in accordance to the current locale (function)
- [`wcsxfrm`](https://en.cppreference.com/w/c/string/wide/wcsxfrm) (C95): transform a wide string so that wcscmp would produce the same result as wcscoll (function)
- [`wcscmp`](https://en.cppreference.com/w/c/string/wide/wcscmp) (C95): compares two wide strings (function)
- [C++ documentation for `wcscoll`](https://en.cppreference.com/w/cpp/string/wide/wcscoll)

---
Attribution: content from https://en.cppreference.com/w/c/string/wide/wcscoll (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.