wcscoll Function

Compare two wide strings based on current locale.

Attention: This function is implemented only by MPLAB XC32 C compilers.

Include

<wchar.h>

Prototype

int wcscoll(const wchar_t * restrict s1, const wchar_t * restrict s2);

Arguments

s1
one wide string to compare
s2
the other wide string to compare

Return Value

Returns a positive integer if s1 is greater than s2, zero if s1 is equal to s2 or a negative number if s1 is less than s2.

Remarks

The function returns a value based on the first wide character that differs between s1 and s2. Wide characters that follow a null wide character are not compared.

The comparison is based on the LC_COLLATE category of the current locale. As MPLAB XC8 does not implement locales, wcscoll() is equivalent to wcscmp() for that implementation.

Example

#include <wchar.h>

int main(void)
{
  wchar_t buf1[50] = L"Where is the time?";
  wchar_t buf2[50] = L"Where did they go?";
  wchar_t buf3[50] = L"Why?";
  int res;

  wprintf(L"buf1 : %ls\n", buf1);
  wprintf(L"buf2 : %ls\n", buf2);
  wprintf(L"buf3 : %ls\n\n", buf3);

  res = wcscoll(buf1, buf2);
  if (res < 0)
    wprintf(L"buf1 comes before buf2\n");
  else if (res == 0)
    wprintf(L"buf1 and buf2 are equal\n");
  else
   wprintf(L"buf2 comes before buf1\n");
  wprintf(L"\n");

  res = wcscoll(buf1, buf3);
  if (res < 0)
    wprintf(L"buf1 comes before buf3\n");
  else if (res == 0)
    wprintf(L"buf1 and buf3 are equal\n");
  else
    wprintf(L"buf3 comes before buf1\n");
  wprintf(L"\n");

  res = wcscoll(L"Why?", buf3);
  if (res < 0)
    wprintf(L"\"Why?\" comes before buf3\n");
  else if (res == 0)
    wprintf(L"buf1 and \"Why?\" are equal\n");
  else
    wprintf(L"buf3 comes before \"Why?\"\n");
}

Example Output

The output of this program might vary based on the LC_COLLATE category of the current locale.